Visitar URL original
Revise docstrings in second-level modules · gitpython-developers/GitPython@1cd73ba · GitHub
Skip to content

Commit 1cd73ba

Browse files
EliahKaganEliahKagan
committed
Revise docstrings in second-level modules
Except for: - git.cmd, where docstrings were revised in e08066c. - git.types, where docstring changes may best be made together with changes to how imports are organized and documented, which seems not to be in the same scope as the changes in this commit. This change, as well as those in e08066c, are largely along the lines of #1725, with most revisions here being to docstrings and a few being to comments. The major differences between the kinds of docstring changes here and those ind #1725 are that the changes here push somewhat harder for consistency and apply some kinds of changes I was reluctant to apply widely in #1725: - Wrap all docstrings and comments to 88 columns, except for parts that are decisively clearer when not wrapped. Note that semi- paragraph changes represented as single newlines are still kept where meaningful, which is one reason this is not always the same effect as automatic wrapping would produce. - Avoid code formatting (double backticks) for headings that precede sections and code blocks. This was done enough that it seems to have been intentional, but it doesn't really have the right semantics, and the documentation is currently rendering in such a way (including on readthedocs.org) where removing that formatting seems clearly better. - References (single backticks with a role prefix) and code spans (double backticks) everywhere applicable, even in the first lines of docstrings. - Single-backticks around parameter names, with no role prefix. These were mostly either formatted that way or emphasized (with asterisks). This is one of the rare cases that I have used single backticks without a role prefix, which ordinarily should be avoided, but to get a role for references to a function's parameters within that function, a plugin would be needed. In the rare case that one function's docstring refers to another function's parameters by names those are double-backticked as code spans (and where applicable the name of the referred-to function is single-backticked with the :func: or :meth: role). - All sections, such as :param blah:, :note:, and :return:, now have a newline before any text in them. This was already often but far from always done, and the style was overall inconsistent. Of consistent approaches that are clear and easy to write, this is the simplest. It also seems to substantially improve readability, when taken together with... - Sections are always separated by a blank line, even if they are very short. - Essentially unlimited use of `~a.b.c`, where applicable, to refer and link to the documentation for a.b.c while showing the text "a" and revealing "a.b.c" on hover. I had previously somewhat limited my use of this tilde notation in case readers of the source code itself (where it is not rendered) weren't familiar with it, but at the cost of less consistency in when an entity was referred to. There remain a couple places in git.util where I do not do this because the explicit form `a <a.b.c>`, which is equivalent, lined things up better and was thus easier to read. Those are the major differences between the approach taken here and in #1725, but not necessarily most of the changes done here (many of which are the same kinds of revisions as done there). Note that this commit only modifies some git/*.py files, and there are more git/**/*.py files that remain to be revised accordingly.
1 parent fa471fe commit 1cd73ba

7 files changed

Lines changed: 439 additions & 261 deletions

File tree

‎git/compat.py‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -35,8 +35,9 @@
3535
:attr:`sys.platform` checks explicitly, especially in cases where it matters which is
3636
used.
3737
38-
:note: ``is_win`` is ``False`` on Cygwin, but is often wrongly assumed ``True``. To
39-
detect Cygwin, use ``sys.platform == "cygwin"``.
38+
:note:
39+
``is_win`` is ``False`` on Cygwin, but is often wrongly assumed ``True``. To detect
40+
Cygwin, use ``sys.platform == "cygwin"``.
4041
"""
4142

4243
is_posix = os.name == "posix"
@@ -46,9 +47,10 @@
4647
:attr:`sys.platform` checks explicitly, especially in cases where it matters which is
4748
used.
4849
49-
:note: For POSIX systems, more detailed information is available in
50-
:attr:`sys.platform`, while :attr:`os.name` is always ``"posix"`` on such systems,
51-
including macOS (Darwin).
50+
:note:
51+
For POSIX systems, more detailed information is available in :attr:`sys.platform`,
52+
while :attr:`os.name` is always ``"posix"`` on such systems, including macOS
53+
(Darwin).
5254
"""
5355

5456
is_darwin = sys.platform == "darwin"
@@ -57,7 +59,8 @@
5759
This is deprecated because it clearer to write out :attr:`os.name` or
5860
:attr:`sys.platform` checks explicitly.
5961
60-
:note: For macOS (Darwin), ``os.name == "posix"`` as in other Unix-like systems, while
62+
:note:
63+
For macOS (Darwin), ``os.name == "posix"`` as in other Unix-like systems, while
6164
``sys.platform == "darwin"`.
6265
"""
6366

‎git/config.py‎

Lines changed: 96 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -73,11 +73,13 @@
7373

7474

7575
class MetaParserBuilder(abc.ABCMeta): # noqa: B024
76-
"""Utility class wrapping base-class methods into decorators that assure read-only properties."""
76+
"""Utility class wrapping base-class methods into decorators that assure read-only
77+
properties."""
7778

7879
def __new__(cls, name: str, bases: Tuple, clsdict: Dict[str, Any]) -> "MetaParserBuilder":
7980
"""Equip all base-class methods with a needs_values decorator, and all non-const
80-
methods with a set_dirty_and_flush_changes decorator in addition to that.
81+
methods with a :func:`set_dirty_and_flush_changes` decorator in addition to
82+
that.
8183
"""
8284
kmm = "_mutating_methods_"
8385
if kmm in clsdict:
@@ -102,7 +104,8 @@ def __new__(cls, name: str, bases: Tuple, clsdict: Dict[str, Any]) -> "MetaParse
102104

103105

104106
def needs_values(func: Callable[..., _T]) -> Callable[..., _T]:
105-
"""Return a method for ensuring we read values (on demand) before we try to access them."""
107+
"""Return a method for ensuring we read values (on demand) before we try to access
108+
them."""
106109

107110
@wraps(func)
108111
def assure_data_present(self: "GitConfigParser", *args: Any, **kwargs: Any) -> _T:
@@ -116,7 +119,8 @@ def assure_data_present(self: "GitConfigParser", *args: Any, **kwargs: Any) -> _
116119
def set_dirty_and_flush_changes(non_const_func: Callable[..., _T]) -> Callable[..., _T]:
117120
"""Return a method that checks whether given non constant function may be called.
118121
119-
If so, the instance will be set dirty. Additionally, we flush the changes right to disk.
122+
If so, the instance will be set dirty. Additionally, we flush the changes right to
123+
disk.
120124
"""
121125

122126
def flush_changes(self: "GitConfigParser", *args: Any, **kwargs: Any) -> _T:
@@ -136,7 +140,8 @@ class SectionConstraint(Generic[T_ConfigParser]):
136140
137141
It supports all ConfigParser methods that operate on an option.
138142
139-
:note: If used as a context manager, will release the wrapped ConfigParser.
143+
:note:
144+
If used as a context manager, will release the wrapped ConfigParser.
140145
"""
141146

142147
__slots__ = ("_config", "_section_name")
@@ -171,8 +176,8 @@ def __getattr__(self, attr: str) -> Any:
171176
return super().__getattribute__(attr)
172177

173178
def _call_config(self, method: str, *args: Any, **kwargs: Any) -> Any:
174-
"""Call the configuration at the given method which must take a section name
175-
as first argument."""
179+
"""Call the configuration at the given method which must take a section name as
180+
first argument."""
176181
return getattr(self._config, method)(self._section_name, *args, **kwargs)
177182

178183
@property
@@ -254,7 +259,8 @@ def get_config_path(config_level: Lit_config_levels) -> str:
254259
elif config_level == "repository":
255260
raise ValueError("No repo to get repository configuration from. Use Repo._get_config_path")
256261
else:
257-
# Should not reach here. Will raise ValueError if does. Static typing will warn missing elifs
262+
# Should not reach here. Will raise ValueError if does. Static typing will warn
263+
# about missing elifs.
258264
assert_never( # type: ignore[unreachable]
259265
config_level,
260266
ValueError(f"Invalid configuration level: {config_level!r}"),
@@ -264,14 +270,15 @@ def get_config_path(config_level: Lit_config_levels) -> str:
264270
class GitConfigParser(cp.RawConfigParser, metaclass=MetaParserBuilder):
265271
"""Implements specifics required to read git style configuration files.
266272
267-
This variation behaves much like the git.config command such that the configuration
268-
will be read on demand based on the filepath given during initialization.
273+
This variation behaves much like the ``git config`` command, such that the
274+
configuration will be read on demand based on the filepath given during
275+
initialization.
269276
270277
The changes will automatically be written once the instance goes out of scope, but
271278
can be triggered manually as well.
272279
273-
The configuration file will be locked if you intend to change values preventing other
274-
instances to write concurrently.
280+
The configuration file will be locked if you intend to change values preventing
281+
other instances to write concurrently.
275282
276283
:note:
277284
The config is case-sensitive even when queried, hence section and option names
@@ -301,7 +308,8 @@ class GitConfigParser(cp.RawConfigParser, metaclass=MetaParserBuilder):
301308
del optvalueonly_source
302309

303310
_mutating_methods_ = ("add_section", "remove_section", "remove_option", "set")
304-
"""List of RawConfigParser methods able to change the instance."""
311+
"""Names of :class:`~configparser.RawConfigParser` methods able to change the
312+
instance."""
305313

306314
def __init__(
307315
self,
@@ -311,8 +319,8 @@ def __init__(
311319
config_level: Union[Lit_config_levels, None] = None,
312320
repo: Union["Repo", None] = None,
313321
) -> None:
314-
"""Initialize a configuration reader to read the given file_or_files and to
315-
possibly allow changes to it by setting read_only False.
322+
"""Initialize a configuration reader to read the given `file_or_files` and to
323+
possibly allow changes to it by setting `read_only` False.
316324
317325
:param file_or_files:
318326
A file path or file object, or a sequence of possibly more than one of them.
@@ -385,7 +393,7 @@ def _acquire_lock(self) -> None:
385393
# END read-only check
386394

387395
def __del__(self) -> None:
388-
"""Write pending changes if required and release locks"""
396+
"""Write pending changes if required and release locks."""
389397
# NOTE: Only consistent in Python 2.
390398
self.release()
391399

@@ -397,10 +405,12 @@ def __exit__(self, *args: Any) -> None:
397405
self.release()
398406

399407
def release(self) -> None:
400-
"""Flush changes and release the configuration write lock. This instance must not be used anymore afterwards.
408+
"""Flush changes and release the configuration write lock. This instance must
409+
not be used anymore afterwards.
401410
402-
In Python 3, it's required to explicitly release locks and flush changes, as __del__ is not called
403-
deterministically anymore."""
411+
In Python 3, it's required to explicitly release locks and flush changes, as
412+
:meth:`__del__` is not called deterministically anymore.
413+
"""
404414
# Checking for the lock here makes sure we do not raise during write()
405415
# in case an invalid parser was created who could not get a lock.
406416
if self.read_only or (self._lock and not self._lock._has_lock()):
@@ -424,8 +434,9 @@ def optionxform(self, optionstr: str) -> str:
424434
return optionstr
425435

426436
def _read(self, fp: Union[BufferedReader, IO[bytes]], fpname: str) -> None:
427-
"""Originally a direct copy of the Python 2.4 version of RawConfigParser._read,
428-
to ensure it uses ordered dicts.
437+
"""Originally a direct copy of the Python 2.4 version of
438+
:meth:`RawConfigParser._read <configparser.RawConfigParser._read>`, to ensure it
439+
uses ordered dicts.
429440
430441
The ordering bug was fixed in Python 2.4, and dict itself keeps ordering since
431442
Python 3.7. This has some other changes, especially that it ignores initial
@@ -525,7 +536,8 @@ def _has_includes(self) -> Union[bool, int]:
525536
def _included_paths(self) -> List[Tuple[str, str]]:
526537
"""List all paths that must be included to configuration.
527538
528-
:return: The list of paths, where each path is a tuple of ``(option, value)``.
539+
:return:
540+
The list of paths, where each path is a tuple of ``(option, value)``.
529541
"""
530542
paths = []
531543

@@ -577,8 +589,11 @@ def read(self) -> None: # type: ignore[override]
577589
This will ignore files that cannot be read, possibly leaving an empty
578590
configuration.
579591
580-
:return: Nothing
581-
:raise IOError: If a file cannot be handled
592+
:return:
593+
Nothing
594+
595+
:raise IOError:
596+
If a file cannot be handled
582597
"""
583598
if self._is_initialized:
584599
return
@@ -591,7 +606,7 @@ def read(self) -> None: # type: ignore[override]
591606
elif not isinstance(self._file_or_files, (tuple, list, Sequence)):
592607
# Could merge with above isinstance once runtime type known.
593608
files_to_read = [self._file_or_files]
594-
else: # for lists or tuples
609+
else: # For lists or tuples.
595610
files_to_read = list(self._file_or_files)
596611
# END ensure we have a copy of the paths to handle
597612

@@ -603,7 +618,8 @@ def read(self) -> None: # type: ignore[override]
603618

604619
if hasattr(file_path, "seek"):
605620
# Must be a file-object.
606-
file_path = cast(IO[bytes], file_path) # TODO: Replace with assert to narrow type, once sure.
621+
# TODO: Replace cast with assert to narrow type, once sure.
622+
file_path = cast(IO[bytes], file_path)
607623
self._read(file_path, file_path.name)
608624
else:
609625
# Assume a path if it is not a file-object.
@@ -615,8 +631,8 @@ def read(self) -> None: # type: ignore[override]
615631
except IOError:
616632
continue
617633

618-
# Read includes and append those that we didn't handle yet.
619-
# We expect all paths to be normalized and absolute (and will ensure that is the case).
634+
# Read includes and append those that we didn't handle yet. We expect all
635+
# paths to be normalized and absolute (and will ensure that is the case).
620636
if self._has_includes():
621637
for _, include_path in self._included_paths():
622638
if include_path.startswith("~"):
@@ -695,8 +711,9 @@ def items_all(self, section_name: str) -> List[Tuple[str, List[str]]]:
695711
def write(self) -> None:
696712
"""Write changes to our file, if there are changes at all.
697713
698-
:raise IOError: If this is a read-only writer instance or if we could not obtain
699-
a file lock"""
714+
:raise IOError:
715+
If this is a read-only writer instance or if we could not obtain a file lock
716+
"""
700717
self._assure_writable("write")
701718
if not self._dirty:
702719
return
@@ -740,7 +757,7 @@ def _assure_writable(self, method_name: str) -> None:
740757
raise IOError("Cannot execute non-constant method %s.%s" % (self, method_name))
741758

742759
def add_section(self, section: str) -> None:
743-
"""Assures added options will stay in order"""
760+
"""Assures added options will stay in order."""
744761
return super().add_section(section)
745762

746763
@property
@@ -757,16 +774,18 @@ def get_value(
757774
) -> Union[int, float, str, bool]:
758775
"""Get an option's value.
759776
760-
If multiple values are specified for this option in the section, the
761-
last one specified is returned.
777+
If multiple values are specified for this option in the section, the last one
778+
specified is returned.
762779
763780
:param default:
764-
If not None, the given default value will be returned in case
765-
the option did not exist
781+
If not None, the given default value will be returned in case the option did
782+
not exist
766783
767-
:return: a properly typed value, either int, float or string
784+
:return:
785+
A properly typed value, either int, float or string
768786
769-
:raise TypeError: in case the value could not be understood
787+
:raise TypeError:
788+
In case the value could not be understood.
770789
Otherwise the exceptions known to the ConfigParser will be raised.
771790
"""
772791
try:
@@ -790,12 +809,14 @@ def get_values(
790809
returned.
791810
792811
:param default:
793-
If not None, a list containing the given default value will be
794-
returned in case the option did not exist
812+
If not None, a list containing the given default value will be returned in
813+
case the option did not exist.
795814
796-
:return: a list of properly typed values, either int, float or string
815+
:return:
816+
A list of properly typed values, either int, float or string
797817
798-
:raise TypeError: in case the value could not be understood
818+
:raise TypeError:
819+
In case the value could not be understood.
799820
Otherwise the exceptions known to the ConfigParser will be raised.
800821
"""
801822
try:
@@ -849,11 +870,17 @@ def set_value(self, section: str, option: str, value: Union[str, bytes, int, flo
849870
This will create the section if required, and will not throw as opposed to the
850871
default ConfigParser 'set' method.
851872
852-
:param section: Name of the section in which the option resides or should reside
853-
:param option: Name of the options whose value to set
854-
:param value: Value to set the option to. It must be a string or convertible to
855-
a string.
856-
:return: This instance
873+
:param section:
874+
Name of the section in which the option resides or should reside.
875+
876+
:param option:
877+
Name of the options whose value to set.
878+
879+
:param value:
880+
Value to set the option to. It must be a string or convertible to a string.
881+
882+
:return:
883+
This instance
857884
"""
858885
if not self.has_section(section):
859886
self.add_section(section)
@@ -865,15 +892,22 @@ def set_value(self, section: str, option: str, value: Union[str, bytes, int, flo
865892
def add_value(self, section: str, option: str, value: Union[str, bytes, int, float, bool]) -> "GitConfigParser":
866893
"""Add a value for the given option in section.
867894
868-
This will create the section if required, and will not throw as opposed to the default
869-
ConfigParser 'set' method. The value becomes the new value of the option as returned
870-
by 'get_value', and appends to the list of values returned by 'get_values`'.
895+
This will create the section if required, and will not throw as opposed to the
896+
default ConfigParser 'set' method. The value becomes the new value of the option
897+
as returned by 'get_value', and appends to the list of values returned by
898+
'get_values'.
871899
872-
:param section: Name of the section in which the option resides or should reside
873-
:param option: Name of the option
874-
:param value: Value to add to option. It must be a string or convertible
875-
to a string
876-
:return: This instance
900+
:param section:
901+
Name of the section in which the option resides or should reside.
902+
903+
:param option:
904+
Name of the option.
905+
906+
:param value:
907+
Value to add to option. It must be a string or convertible to a string.
908+
909+
:return:
910+
This instance
877911
"""
878912
if not self.has_section(section):
879913
self.add_section(section)
@@ -883,8 +917,12 @@ def add_value(self, section: str, option: str, value: Union[str, bytes, int, flo
883917
def rename_section(self, section: str, new_name: str) -> "GitConfigParser":
884918
"""Rename the given section to new_name.
885919
886-
:raise ValueError: If ``section`` doesn't exist
887-
:raise ValueError: If a section with ``new_name`` does already exist
920+
:raise ValueError:
921+
If:
922+
923+
* ``section`` doesn't exist.
924+
* A section with ``new_name`` does already exist.
925+
888926
:return: This instance
889927
"""
890928
if not self.has_section(section):
@@ -898,6 +936,7 @@ def rename_section(self, section: str, new_name: str) -> "GitConfigParser":
898936
new_section.setall(k, vs)
899937
# END for each value to copy
900938

901-
# This call writes back the changes, which is why we don't have the respective decorator.
939+
# This call writes back the changes, which is why we don't have the respective
940+
# decorator.
902941
self.remove_section(section)
903942
return self

0 commit comments

Comments
 (0)