Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commitee0301a

Browse files
committed
More docstring revisions in second-level modules and git.__init__
1 parent679d2e8 commitee0301a

File tree

7 files changed

+59
-55
lines changed

7 files changed

+59
-55
lines changed

‎git/__init__.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -127,7 +127,7 @@ def refresh(path: Optional[PathLike] = None) -> None:
127127
immediately, relative to the current directory.
128128
129129
:note:
130-
The*path* parameter is usually omitted and cannot be used to specify a custom
130+
The`path` parameter is usually omitted and cannot be used to specify a custom
131131
command whose location is looked up in a path search on each call. See
132132
:meth:`Git.refresh <git.cmd.Git.refresh>` for details on how to achieve this.
133133

‎git/cmd.py

Lines changed: 19 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -106,7 +106,7 @@ def handle_process_output(
106106
decode_streams:bool=True,
107107
kill_after_timeout:Union[None,float]=None,
108108
)->None:
109-
"""Register for notifications to learn that process output is ready to read, and
109+
R"""Register for notifications to learn that process output is ready to read, and
110110
dispatch lines to the respective line handlers.
111111
112112
This function returns once the finalizer returns.
@@ -126,8 +126,11 @@ def handle_process_output(
126126
:param decode_streams:
127127
Assume stdout/stderr streams are binary and decode them before pushing their
128128
contents to handlers.
129-
Set this to ``False`` if ``universal_newlines == True`` (then streams are in
130-
text mode) or if decoding must happen later (i.e. for :class:`~git.diff.Diff`s).
129+
130+
This defaults to ``True``. Set it to ``False``:
131+
132+
- if ``universal_newlines == True``, as then streams are in text mode, or
133+
- if decoding must happen later, such as for :class:`~git.diff.Diff`\s.
131134
132135
:param kill_after_timeout:
133136
:class:`float` or ``None``, Default = ``None``
@@ -379,15 +382,14 @@ def __setstate__(self, d: Dict[str, Any]) -> None:
379382
380383
:note:
381384
The git executable is actually found during the refresh step in the top level
382-
:mod:`__init__`. It can also be changed by explicitly calling
383-
:func:`git.refresh`.
385+
``__init__``. It can also be changed by explicitly calling :func:`git.refresh`.
384386
"""
385387

386388
_refresh_token=object()# Since None would match an initial _version_info_token.
387389

388390
@classmethod
389391
defrefresh(cls,path:Union[None,PathLike]=None)->bool:
390-
"""This gets called by the refresh function (see the top level __init__).
392+
"""This gets called by the refresh function (see the top level``__init__``).
391393
392394
:param path:
393395
Optional path to the git executable. If not absolute, it is resolved
@@ -868,8 +870,7 @@ def __init__(self, working_dir: Union[None, PathLike] = None):
868870
self.cat_file_all:Union[None,TBD]=None
869871

870872
def__getattr__(self,name:str)->Any:
871-
"""A convenience method as it allows to call the command as if it was
872-
an object.
873+
"""A convenience method as it allows to call the command as if it was an object.
873874
874875
:return:
875876
Callable object that will execute call :meth:`_call_process` with your
@@ -899,7 +900,7 @@ def working_dir(self) -> Union[None, PathLike]:
899900
@property
900901
defversion_info(self)->Tuple[int, ...]:
901902
"""
902-
:return: tuple with integers representing the major, minor and additional
903+
:return:Tuple with integers representing the major, minor and additional
903904
version numbers as parsed from ``git version``. Up to four fields are used.
904905
905906
This value is generated on demand and is cached.
@@ -1021,7 +1022,7 @@ def execute(
10211022
:param output_stream:
10221023
If set to a file-like object, data produced by the git command will be
10231024
copied to the given stream instead of being returned as a string.
1024-
This feature only has any effect if `as_process` is False.
1025+
This feature only has any effect if `as_process` is``False``.
10251026
10261027
:param stdout_as_string:
10271028
If ``False``, the command's standard output will be bytes. Otherwise, it
@@ -1030,10 +1031,10 @@ def execute(
10301031
10311032
:param kill_after_timeout:
10321033
Specifies a timeout in seconds for the git command, after which the process
1033-
should be killed. This will have no effect if `as_process` is set to True.
1034-
It is set to None by default and will let the process run until the timeout
1035-
is explicitly specified. Uses of this feature should be carefully
1036-
considered, due to the following limitations:
1034+
should be killed. This will have no effect if `as_process` is set to
1035+
``True``.It is set to``None`` by default and will let the process run
1036+
until the timeoutis explicitly specified. Uses of this feature should be
1037+
carefullyconsidered, due to the following limitations:
10371038
10381039
1. This feature is not supported at all on Windows.
10391040
2. Effectiveness may vary by operating system. ``ps --ppid`` is used to
@@ -1099,7 +1100,7 @@ def execute(
10991100
11001101
:note:
11011102
If you add additional keyword arguments to the signature of this method,
1102-
you must update the execute_kwargs tuple housed in this module.
1103+
you must update the``execute_kwargs`` variable housed in this module.
11031104
"""
11041105
# Remove password for the command if present.
11051106
redacted_command=remove_password_if_present(command)
@@ -1420,9 +1421,10 @@ def _call_process(
14201421
:param kwargs:
14211422
Contains key-values for the following:
14221423
1423-
- The :meth:`execute()` kwds, as listed in:var:`execute_kwargs`.
1424+
- The :meth:`execute()` kwds, as listed in``execute_kwargs``.
14241425
- "Command options" to be converted by :meth:`transform_kwargs`.
1425-
- The ``insert_kwargs_after`` key which its value must match one of ``*args``.
1426+
- The ``insert_kwargs_after`` key which its value must match one of
1427+
``*args``.
14261428
14271429
It also contains any command options, to be appended after the matched arg.
14281430

‎git/config.py

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -411,7 +411,7 @@ def release(self) -> None:
411411
not be used anymore afterwards.
412412
413413
In Python 3, it's required to explicitly release locks and flush changes, as
414-
:meth:`__del__` is not called deterministically anymore.
414+
``__del__`` is not called deterministically anymore.
415415
"""
416416
# Checking for the lock here makes sure we do not raise during write()
417417
# in case an invalid parser was created who could not get a lock.
@@ -539,7 +539,7 @@ def _included_paths(self) -> List[Tuple[str, str]]:
539539
"""List all paths that must be included to configuration.
540540
541541
:return:
542-
The list of paths, where each path is a tuple of``(option, value)``.
542+
The list of paths, where each path is a tuple of (option, value).
543543
"""
544544
paths= []
545545

@@ -591,9 +591,6 @@ def read(self) -> None: # type: ignore[override]
591591
This will ignore files that cannot be read, possibly leaving an empty
592592
configuration.
593593
594-
:return:
595-
Nothing
596-
597594
:raise IOError:
598595
If a file cannot be handled.
599596
"""
@@ -765,7 +762,7 @@ def add_section(self, section: str) -> None:
765762

766763
@property
767764
defread_only(self)->bool:
768-
""":return: True if this instance may change the configuration file"""
765+
""":return:``True`` if this instance may change the configuration file"""
769766
returnself._read_only
770767

771768
# FIXME: Figure out if default or return type can really include bool.
@@ -918,7 +915,7 @@ def add_value(self, section: str, option: str, value: Union[str, bytes, int, flo
918915
returnself
919916

920917
defrename_section(self,section:str,new_name:str)->"GitConfigParser":
921-
"""Rename the given section to new_name.
918+
"""Rename the given section to`new_name`.
922919
923920
:raise ValueError:
924921
If:

‎git/db.py

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,8 @@ def stream(self, binsha: bytes) -> OStream:
5454

5555
defpartial_to_complete_sha_hex(self,partial_hexsha:str)->bytes:
5656
"""
57-
:return: Full binary 20 byte sha from the given partial hexsha
57+
:return:
58+
Full binary 20 byte sha from the given partial hexsha
5859
5960
:raise gitdb.exc.AmbiguousObjectName:
6061

‎git/diff.py

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -121,9 +121,9 @@ def diff(
121121
* If ``None``, we will be compared to the working tree.
122122
* If :class:`~git.index.base.Treeish`, it will be compared against the
123123
respective tree.
124-
* If :class:`~Diffable.Index`, it will be compared against the index.
124+
* If :class:`Diffable.Index`, it will be compared against the index.
125125
* If :attr:`git.NULL_TREE`, it will compare against the empty tree.
126-
* It defaults to :class:`~Diffable.Index` so that the method will not by
126+
* It defaults to :class:`Diffable.Index` so that the method will not by
127127
default fail on bare repositories.
128128
129129
:param paths:
@@ -280,11 +280,11 @@ class Diff:
280280
Working Tree Blobs:
281281
282282
When comparing to working trees, the working tree blob will have a null hexsha
283-
as a corresponding object does not yet exist. The mode will be null as well.
284-
Thepath will be available, though.
283+
as a corresponding object does not yet exist. The mode will be null as well. The
284+
path will be available, though.
285285
286-
If it is listed in a diff, the working tree version of the file must
287-
differ fromthe version in the index or tree, and hence has been modified.
286+
If it is listed in a diff, the working tree version of the file must differ from
287+
the version in the index or tree, and hence has been modified.
288288
"""
289289

290290
# Precompiled regex.
@@ -468,7 +468,8 @@ def rename_to(self) -> Optional[str]:
468468

469469
@property
470470
defrenamed(self)->bool:
471-
"""
471+
"""Deprecated, use :attr:`renamed_file` instead.
472+
472473
:return:
473474
``True`` if the blob of our diff has been renamed
474475
@@ -480,7 +481,7 @@ def renamed(self) -> bool:
480481

481482
@property
482483
defrenamed_file(self)->bool:
483-
""":return: True if the blob of our diff has been renamed"""
484+
""":return:``True`` if the blob of our diff has been renamed"""
484485
returnself.rename_from!=self.rename_to
485486

486487
@classmethod

‎git/remote.py

Lines changed: 21 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -338,7 +338,7 @@ class FetchInfo(IterableObj):
338338

339339
@classmethod
340340
defrefresh(cls)->Literal[True]:
341-
"""This gets called by the refresh function (see the top level __init__)."""
341+
"""This gets called by the refresh function (see the top level``__init__``)."""
342342
# Clear the old values in _flag_map.
343343
withcontextlib.suppress(KeyError):
344344
delcls._flag_map["t"]
@@ -386,19 +386,22 @@ def _from_line(cls, repo: "Repo", line: str, fetch_line: str) -> "FetchInfo":
386386
"""Parse information from the given line as returned by ``git-fetch -v`` and
387387
return a new :class:`FetchInfo` object representing this information.
388388
389-
We can handle a line as follows:
390-
"%c %-\\*s %-\\*s -> %s%s"
389+
We can handle a line as follows::
391390
392-
Where c is either ' ', !, +, -,\\*, or =
393-
! means error
394-
+ means success forcing update
395-
- means a tag was updated
396-
* means birth of new branch or tag
397-
= means the head was up to date (and not moved)
398-
' ' means a fast-forward
391+
%c %-*s %-*s -> %s%s
399392
400-
fetch line is the corresponding line from FETCH_HEAD, like
401-
acb0fa8b94ef421ad60c8507b634759a472cd56c not-for-merge branch '0.1.7RC' of /tmp/tmpya0vairemote_repo
393+
Where ``c`` is either a space, ``!``, ``+``, ``-``, ``*``, or ``=``:
394+
395+
- '!' means error
396+
- '+' means success forcing update
397+
- '-' means a tag was updated
398+
- '*' means birth of new branch or tag
399+
- '=' means the head was up to date (and not moved)
400+
- ' ' means a fast-forward
401+
402+
`fetch_line` is the corresponding line from FETCH_HEAD, like::
403+
404+
acb0fa8b94ef421ad60c8507b634759a472cd56c not-for-merge branch '0.1.7RC' of /tmp/tmpya0vairemote_repo
402405
"""
403406
match=cls._re_fetch_result.match(line)
404407
ifmatchisNone:
@@ -625,7 +628,7 @@ def exists(self) -> bool:
625628

626629
@classmethod
627630
defiter_items(cls,repo:"Repo",*args:Any,**kwargs:Any)->Iterator["Remote"]:
628-
""":return: Iterator yielding Remote objects of the given repository"""
631+
""":return: Iterator yielding:class:`Remote` objects of the given repository"""
629632
forsectioninrepo.config_reader("repository").sections():
630633
ifnotsection.startswith("remote "):
631634
continue
@@ -639,7 +642,7 @@ def iter_items(cls, repo: "Repo", *args: Any, **kwargs: Any) -> Iterator["Remote
639642
defset_url(
640643
self,new_url:str,old_url:Optional[str]=None,allow_unsafe_protocols:bool=False,**kwargs:Any
641644
)->"Remote":
642-
"""Configure URLs on current remote (cf command ``git remote set-url``).
645+
"""Configure URLs on current remote (cf. command ``git remote set-url``).
643646
644647
This command manages URLs on the remote.
645648
@@ -1020,7 +1023,7 @@ def fetch(
10201023
facility.
10211024
10221025
:param progress:
1023-
See :meth:`push` method.
1026+
Seethe:meth:`push` method.
10241027
10251028
:param verbose:
10261029
Boolean for verbose output.
@@ -1081,8 +1084,8 @@ def pull(
10811084
allow_unsafe_options:bool=False,
10821085
**kwargs:Any,
10831086
)->IterableList[FetchInfo]:
1084-
"""Pull changes from the given branch, being the same as a fetch followed
1085-
by amerge of branch with your local branch.
1087+
"""Pull changes from the given branch, being the same as a fetch followed by a
1088+
merge of branch with your local branch.
10861089
10871090
:param refspec:
10881091
See :meth:`fetch` method.
@@ -1157,7 +1160,7 @@ def push(
11571160
11581161
:param kill_after_timeout:
11591162
To specify a timeout in seconds for the git command, after which the process
1160-
should be killed. It is set to None by default.
1163+
should be killed. It is set to``None`` by default.
11611164
11621165
:param allow_unsafe_protocols:
11631166
Allow unsafe protocols to be used, like ``ext``.

‎git/util.py

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -762,9 +762,9 @@ def update(self, *args: Any, **kwargs: Any) -> None:
762762

763763

764764
classActor:
765-
"""Actors hold information about a person acting on the repository. They
766-
can becommitters and authors or anything with a name and an email as mentioned in
767-
the gitlog entries."""
765+
"""Actors hold information about a person acting on the repository. They can be
766+
committers and authors or anything with a name and an email as mentioned in the git
767+
log entries."""
768768

769769
# PRECOMPILED REGEX
770770
name_only_regex=re.compile(r"<(.*)>")

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp