8000 Further revise docstrings within git.objects.submodule · gitpython-developers/GitPython@08a80aa · GitHub
[go: up one dir, main page]
Skip to content

Commit 08a80aa

Browse files
EliahKaganEliahKagan
committed
Further revise docstrings within git.objects.submodule
1 parent 1b25a13 commit 08a80aa

File tree

3 files changed

+86
-72
lines changed

3 files changed

+86
-72
lines changed

‎git/objects/submodule/base.py

Lines changed: 70 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -266,8 +266,8 @@ def _clear_cache(self) -> None:
266266
def _sio_modules(cls, parent_commit: Commit_ish) -> BytesIO:
267267
"""
268268
:return:
269-
Configuration file as BytesIO - we only access it through the respective
270-
blob's data
269+
Configuration file as :class:`~io.BytesIO` - we only access it through the
270+
respective blob's data
271271
"""
272272
sio = BytesIO(parent_commit.tree[cls.k_modules_file].data_stream.read())
273273
sio.name = cls.k_modules_file
@@ -354,7 +354,7 @@ def _to_relative_path(cls, parent_repo: "Repo", path: PathLike) -> PathLike:
354354
""":return: a path guaranteed to be relative to the given parent repository
355355
356356
:raise ValueError:
357-
If path is not contained in the parent repository's working tree
357+
If path is not contained in the parent repository's working tree.
358358
"""
359359
path = to_native_path_linux(path)
360360
if path.endswith("/"):
@@ -378,8 +378,8 @@ def _to_relative_path(cls, parent_repo: "Repo", path: PathLike) -> PathLike:
378378

379379
@classmethod
380380
def _write_git_file_and_module_config(cls, working_tree_dir: PathLike, module_abspath: PathLike) -> None:
381-
"""Write a .git file containing a (preferably) relative path to the actual git
382-
module repository.
381+
"""Write a ``.git`` file containing a (preferably) relative path to the actual
382+
git module repository.
383383
384384
It is an error if the `module_abspath` cannot be made into a relative path,
385385
relative to the `working_tree_dir`.
@@ -430,10 +430,10 @@ def add(
430430
allow_unsafe_options: bool = False,
431431
allow_unsafe_protocols: bool = False,
432432
) -> "Submodule":
433-
"""Add a new submodule to the given repository. This will alter the index
434-
as well as the ``.gitmodules`` file, but will not create a new commit.
435-
If the submodule already exists, no matter if the configuration differs
436-
from the one provided, the existing submodule will be returned.
433+
"""Add a new submodule to the given repository. This will alter the index as
434+
well as the ``.gitmodules`` file, but will not create a new commit. If the
435+
submodule already exists, no matter if the configuration differs from the one
436+
provided, the existing submodule will be returned.
437437
438438
:param repo:
439439
Repository instance which should receive the submodule.
@@ -448,23 +448,23 @@ def add(
448448
449449
:param url:
450450
git-clone compatible URL, see git-clone reference for more information.
451-
If None, the repository is assumed to exist, and the url of the first remote
452-
is taken instead. This is useful if you want to make an existing repository
453-
a submodule of another one.
451+
If ``None```, the repository is assumed to exist, and the url of the first
452+
remote is taken instead. This is useful if you want to make an existing
453+
repository a submodule of another one.
454454
455455
:param branch:
456456
Name of branch at which the submodule should (later) be checked out. The
457457
given branch must exist in the remote repository, and will be checked out
458458
locally as a tracking branch.
459-
It will only be written into the configuration if it not None, which is when
460-
the checked out branch will be the one the remote HEAD pointed to.
459+
It will only be written into the configuration if it not ``None``, which is
460+
when the checked out branch will be the one the remote HEAD pointed to.
461461
The result you get in these situation is somewhat fuzzy, and it is
462462
recommended to specify at least ``master`` here.
463463
Examples are ``master`` or ``feature/new``.
464464
465465
:param no_checkout:
466-
If True, and if the repository has to be cloned manually, no checkout will
467-
be performed.
466+
If ``True``, and if the 9E88 repository has to be cloned manually, no checkout
467+
will be performed.
468468
469469
:param depth:
470470
Create a shallow clone with a history truncated to the specified number of
@@ -479,7 +479,8 @@ def add(
479479
want to unset some variable, consider providing an empty string as its
480480
value.
481481
482-
:param clone_multi_options: A list of Clone options. Please see
482+
:param clone_multi_options:
483+
A list of clone options. Please see
483484
:meth:`Repo.clone <git.repo.base.Repo.clone>` for details.
484485
485486
:param allow_unsafe_protocols:
@@ -632,44 +633,49 @@ def update(
632633
with the binsha of this instance.
633634
634635
:param recursive:
635-
If True, we will operate recursively and update child modules as well.
636+
If ``True``, we will operate recursively and update child modules as well.
636637
637638
:param init:
638-
If True, the module repository will be cloned into place if necessary.
639+
If ``True``, the module repository will be cloned into place if necessary.
639640
640641
:param to_latest_revision:
641-
If True, the submodule's sha will be ignored during checkout. Instead, the
642-
remote will be fetched, and the local tracking branch updated. This only
642+
If ``True``, the submodule's sha will be ignored during checkout. Instead,
643+
the remote will be fetched, and the local tracking branch updated. This only
643644
works if we have a local tracking branch, which is the case if the remote
644-
repository had a master branch, or of the 'branch' option was specified for
645-
this submodule and the branch existed remotely.
645+
repository had a master branch, or of the ``branch`` option was specified
646+
for this submodule and the branch existed remotely.
646647
647648
:param progress:
648-
:class:`UpdateProgress` instance, or None if no progress should be shown.
649+
:class:`UpdateProgress` instance, or ``None`` if no progress should be
650+
shown.
649651
650652
:param dry_run:
651-
If True, the operation will only be simulated, but not performed.
653+
If ``True``, the operation will only be simulated, but not performed.
652654
All performed operations are read-only.
653655
654656
:param force:
655-
If True, we may reset heads even if the repository in question is dirty.
657+
If ``True``, we may reset heads even if the repository in question is dirty.
656658
Additionally we will be allowed to set a tracking branch which is ahead of
657659
its remote branch back into the past or the location of the remote branch.
658660
This will essentially 'forget' commits.
659-
If False, local tracking branches that are in the future of their respective
660-
remote branches will simply not be moved.
661+
662+
If ``False``, local tracking branches that are in the future of their
663+
respective remote branches will simply not be moved.
661664
662665
:param keep_going:
663-
If True, we will ignore but log all errors, and keep going recursively.
666+
If ``True``, we will ignore but log all errors, and keep going recursively.
664667
Unless `dry_run` is set as well, `keep_going` could cause
665668
subsequent/inherited errors you wouldn't see otherwise.
666669
In conjunction with `dry_run`, it can be useful to anticipate all errors
667670
when updating submodules.
668671
669-
:param env: Optional dictionary containing the desired environment variables.
672+
:param env:
673+
Optional dictionary containing the desired environment variables.
674+
670675
Note: Provided variables will be used to update the execution environment
671676
for ``git``. If some variable is not specified in `env` and is defined in
672677
attr:`os.environ`, value from attr:`os.environ` will be used.
678+
673679
If you want to unset some variable, consider providing the empty string as
674680
its value.
675681
@@ -688,7 +694,7 @@ def update(
688694
Does nothing in bare repositories.
689695
690696
:note:
691-
This method is definitely not atomic if `recursive` is True.
697+
This method is definitely not atomic if `recursive` is ``True``.
692698
693699
:return:
694700
self
@@ -950,18 +956,18 @@ def move(self, module_path: PathLike, configuration: bool = True, module: bool =
950956
951957
:param module_path:
952958
The path to which to move our module in the parent repository's working
953-
tree, given as repository - relative or absolute path. Intermediate
959+
tree, given as repository-relative or absolute path. Intermediate
954960
directories will be created accordingly. If the path already exists, it must
955961
be empty. Trailing (back)slashes are removed automatically.
956962
957963
:param configuration:
958-
If True, the configuration will be adjusted to let the submodule point to
959-
the given path.
964+
If ``True``, the configuration will be adjusted to let the submodule point
965+
to the given path.
960966
961967
:param module:
962-
If True, the repository managed by this submodule will be moved as well. If
963-
False, we don't move the submodule's checkout, which may leave the parent
964-
repository in an inconsistent state.
968+
If ``True``, the repository managed by this submodule will be moved as well.
969+
If ``False``, we don't move the submodule's checkout, which may leave the
970+
parent repository in an inconsistent state.
965971
966972
:return:
967973
self
@@ -1074,12 +1080,13 @@ def remove(
10741080
from the ``.gitmodules`` file and the entry in the ``.git/config`` file.
10751081
10761082
:param module:
1077-
If True, the checked out module we point to will be deleted as well. If that
1078-
module is currently on a commit outside any branch in the remote, or if it
1079-
is ahead of its tracking branch, or if there are modified or untracked files
1080-
in its working tree, then the removal will fail. In case the removal of the
1081-
repository fails for these reasons, the submodule status will not have been
1082-
altered.
1083+
If ``True``, the checked out module we point to will be deleted as well. If
1084+
that module is currently on a commit outside any branch in the remote, or if
1085+
it is ahead of its tracking branch, or if there are modified or untracked
1086+
files in its working tree, then the removal will fail. In case the removal
1087+
of the repository fails for these reasons, the submodule status will not
1088+
have been altered.
1089+
10831090
If this submodule has child modules of its own, these will be deleted prior
10841091
to touching the direct submodule.
10851092
@@ -1088,12 +1095,12 @@ def remove(
10881095
This basically enforces a brute-force file system based deletion.
10891096
10901097
:param configuration:
1091-
If True, the submodule is deleted from the configuration, otherwise it
1098+
If ``True``, the submodule is deleted from the configuration, otherwise it
10921099
isn't. Although this should be enabled most of the time, this flag enables
10931100
you to safely delete the repository of your submodule.
10941101
10951102
:param dry_run:
1096-
If True, we will not actually do anything, but throw the errors we would
1103+
If ``True``, we will not actually do anything, but throw the errors we would
10971104
usually throw.
10981105
10991106
:return:
@@ -1239,12 +1246,12 @@ def set_parent_commit(self, commit: Union[Commit_ish, None], check: bool = True)
12391246
contain the ``.gitmodules`` blob.
12401247
12411248
:param commit:
1242-
Commit-ish reference pointing at the root_tree, or None to always point to
1243-
the most recent commit
1249+
Commit-ish reference pointing at the root_tree, or ``None`` to always point
1250+
to the most recent commit.
12441251
12451252
:param check:
1246-
If True, relatively expensive checks will be performed to verify validity of
1247-
the submodule.
1253+
If ``True``, relatively expensive checks will be performed to verify
1254+
validity of the submodule.
12481255
12491256
:raise ValueError:
12501257
If the commit's tree didn't contain the ``.gitmodules`` blob.
@@ -1297,8 +1304,9 @@ def config_writer(
12971304
to this submodule into the ``.gitmodules`` file.
12981305
12991306
:param index:
1300-
If not None, an IndexFile instance which should be written.
1301-
Defaults to the index of the Submodule's parent repository.
1307+
If not ``None``, an :class:`~git.index.base.IndexFile` instance which should
1308+
be written. Defaults to the index of the :class:`Submodule`'s parent
1309+
repository.
13021310
13031311
:param write:
13041312
If True, the index will be written each time a configuration value changes.
@@ -1380,7 +1388,9 @@ def rename(self, new_name: str) -> "Submodule":
13801388
@unbare_repo
13811389
def module(self) -> "Repo":
13821390
"""
1383-
:return: Repo instance initialized from the repository at our submodule path
1391+
:return:
1392+
:class:`~git.repo.base.Repo` instance initialized from the repository at our
1393+
submodule path
13841394
13851395
:raise git.exc.InvalidGitRepositoryError:
13861396
If a repository was not available.
@@ -1401,7 +1411,7 @@ def module(self) -> "Repo":
14011411
def module_exists(self) -> bool:
14021412
"""
14031413
:return:
1404-
True if our module exists and is a valid git repository.
1414+
``True`` if our module exists and is a valid git repository.
14051415
See the :meth:`module` method.
14061416
"""
14071417
try:
@@ -1414,7 +1424,7 @@ def module_exists(self) -> bool:
14141424
def exists(self) -> bool:
14151425
"""
14161426
:return:
1417-
True if the submodule exists, False otherwise.
1427+
``True`` if the submodule exists, ``False`` otherwise.
14181428
Please note that a submodule may exist (in the ``.gitmodules`` file) even
14191429
though its module doesn't exist on disk.
14201430
"""
@@ -1480,14 +1490,15 @@ def branch_name(self) -> str:
14801490

14811491
@property
14821492
def url(self) -> str:
1483-
""":return: The url to the repository which our module - repository refers to"""
1493+
""":return: The url to the repository our submodule's repository refers to"""
14841494
return self._url
14851495

14861496
@property
14871497
def parent_commit(self) -> "Commit_ish":
14881498
"""
14891499
:return:
1490-
Commit instance with the tree containing the ``.gitmodules`` file
1500+
:class:`~git.objects.commit.Commit` instance with the tree containing the
1501+
``.gitmodules`` file
14911502
14921503
:note:
14931504
Will always point to the current head's commit if it was not set explicitly.
@@ -1531,8 +1542,9 @@ def config_reader(self) -> SectionConstraint[SubmoduleConfigParser]:
15311542
def children(self) -> IterableList["Submodule"]:
15321543
"""
15331544
:return:
1534-
IterableList(Submodule, ...) An iterable list of submodules instances which
1535-
are children of this submodule or 0 if the submodule is not checked out.
1545+
IterableList(Submodule, ...) An iterable list of :class:`Submodule`
1546+
instances which are children of this submodule or 0 if the submodule is not
1547+
checked out.
15361548
"""
15371549
return self._get_intermediate_items(self)
15381550

‎git/objects/submodule/root.py

Lines changed: 15 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -89,21 +89,21 @@ def update(
8989
) -> "RootModule":
9090
"""Update the submodules of this repository to the current HEAD commit.
9191
92-
This method behaves smartly by determining changes of the path of a submodules
92+
This method behaves smartly by determining changes of the path of a submodule's
9393
repository, next to changes to the to-be-checked-out commit or the branch to be
94-
checked out. This works if the submodules ID does not change.
94+
checked out. This works if the submodule's ID does not change.
9595
9696
Additionally it will detect addition and removal of submodules, which will be
9797
handled gracefully.
9898
9999
:param previous_commit:
100100
If set to a commit-ish, the commit we should use as the previous commit the
101101
HEAD pointed to before it was set to the commit it points to now.
102-
If None, it defaults to ``HEAD@{1}`` otherwise.
102+
If ``None``, it defaults to ``HEAD@{1}`` otherwise.
103103
104104
:param recursive:
105-
If True, the children of submodules will be updated as well using the same
106-
technique.
105+
If ``True``, the children of submodules will be updated as well using the
106+
same technique.
107107
108108
:param force_remove:
109109
If submodules have been deleted, they will be forcibly removed. Otherwise
@@ -116,28 +116,30 @@ def update(
116116
If we encounter a new module which would need to be initialized, then do it.
117117
118118
:param to_latest_revision:
119-
If True, instead of checking out the revision pointed to by this submodule's
120-
sha, the checked out tracking branch will be merged with the latest remote
121-
branch fetched from the repository's origin.
119+
If ``True``, instead of checking out the revision pointed to by this
120+
submodule's sha, the checked out tracking branch will be merged with the
121+
latest remote branch fetched from the repository's origin.
122+
122123
Unless `force_reset` is specified, a local tracking branch will never be
123124
reset into its past, therefore the remote branch must be in the future for
124125
this to have an effect.
125126
126127
:param force_reset:
127-
If True, submodules may checkout or reset their branch even if the
128+
If ``True``, submodules may checkout or reset their branch even if the
128129
repository has pending changes that would be overwritten, or if the local
129130
tracking branch is in the future of the remote tracking branch and would be
130131
reset into its past.
131132
132133
:param progress:
133-
:class:`RootUpdateProgress` instance or None if no progress should be sent.
134+
:class:`RootUpdateProgress` instance, or ``None`` if no progress should be
135+
sent.
134136
135137
:param dry_run:
136-
If True, operations will not actually be performed. Progress messages will
137-
change accordingly to indicate the WOULD DO state of the operation.
138+
If ``True``, operations will not actually be performed. Progress messages
139+
will change accordingly to indicate the WOULD DO state of the operation.
138140
139141
:param keep_going:
140-
If True, we will ignore but log all errors, and keep going recursively.
142+
If ``True``, we will ignore but log all errors, and keep going recursively.
141143
Unless `dry_run` is set as well, `keep_going` could cause
142144
subsequent/inherited errors you wouldn't see otherwise.
143145
In conjunction with `dry_run`, this can be useful to anticipate all errors

‎git/objects/submodule/util.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ def mkhead(repo: "Repo", path: PathLike) -> "Head":
5252

5353
def find_first_remote_branch(remotes: Sequence["Remote"], branch_name: str) -> "RemoteReference":
5454
"""Find the remote branch matching the name of the given branch or raise
55-
:class:`git.exc.InvalidGitRepositoryError`."""
55+
:class:`~git.exc.InvalidGitRepositoryError`."""
5656
for remote in remotes:
5757
try:
5858
return remote.refs[branch_name]

0 commit comments

Comments
 (0)
0