1berry/cpython
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

gh-100520: Fix rst markup in configparser docstrings (#100524)

Browse Source
This commit is contained in:
Nikita Sobolev 2022-12-26 14:38:49 +03:00 committed by GitHub
parent 3ccc98fc24
commit 199507b81a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 37 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
Lib/configparser.py
View File

@ -19,36 +19,37 @@ ConfigParser -- responsible for parsing a list of
inline_comment_prefixes=None, strict=True, inline_comment_prefixes=None, strict=True,
empty_lines_in_values=True, default_section='DEFAULT', empty_lines_in_values=True, default_section='DEFAULT',
interpolation=<unset>, converters=<unset>): interpolation=<unset>, converters=<unset>):
Create the parser. When `defaults' is given, it is initialized into the
Create the parser. When `defaults` is given, it is initialized into the
dictionary or intrinsic defaults. The keys must be strings, the values dictionary or intrinsic defaults. The keys must be strings, the values
must be appropriate for %()s string interpolation. must be appropriate for %()s string interpolation.
When `dict_type' is given, it will be used to create the dictionary When `dict_type` is given, it will be used to create the dictionary
objects for the list of sections, for the options within a section, and objects for the list of sections, for the options within a section, and
for the default values. for the default values.
When `delimiters' is given, it will be used as the set of substrings When `delimiters` is given, it will be used as the set of substrings
that divide keys from values. that divide keys from values.
When `comment_prefixes' is given, it will be used as the set of When `comment_prefixes` is given, it will be used as the set of
substrings that prefix comments in empty lines. Comments can be substrings that prefix comments in empty lines. Comments can be
indented. indented.
When `inline_comment_prefixes' is given, it will be used as the set of When `inline_comment_prefixes` is given, it will be used as the set of
substrings that prefix comments in non-empty lines. substrings that prefix comments in non-empty lines.
When `strict` is True, the parser won't allow for any section or option When `strict` is True, the parser won't allow for any section or option
duplicates while reading from a single source (file, string or duplicates while reading from a single source (file, string or
dictionary). Default is True. dictionary). Default is True.
When `empty_lines_in_values' is False (default: True), each empty line When `empty_lines_in_values` is False (default: True), each empty line
marks the end of an option. Otherwise, internal empty lines of marks the end of an option. Otherwise, internal empty lines of
a multiline option are kept as part of the value. a multiline option are kept as part of the value.
When `allow_no_value' is True (default: False), options without When `allow_no_value` is True (default: False), options without
values are accepted; the value presented for these is None. values are accepted; the value presented for these is None.
When `default_section' is given, the name of the special section is When `default_section` is given, the name of the special section is
named accordingly. By default it is called ``"DEFAULT"`` but this can named accordingly. By default it is called ``"DEFAULT"`` but this can
be customized to point to any other valid section name. Its current be customized to point to any other valid section name. Its current
value can be retrieved using the ``parser_instance.default_section`` value can be retrieved using the ``parser_instance.default_section``
@ -87,7 +88,7 @@ ConfigParser -- responsible for parsing a list of
read_file(f, filename=None) read_file(f, filename=None)
Read and parse one configuration file, given as a file object. Read and parse one configuration file, given as a file object.
The filename defaults to f.name; it is only used in error The filename defaults to f.name; it is only used in error
messages (if f has no `name' attribute, the string `<???>' is used). messages (if f has no `name` attribute, the string `<???>` is used).
read_string(string) read_string(string)
Read configuration from a given string. Read configuration from a given string.
@ -103,9 +104,9 @@ ConfigParser -- responsible for parsing a list of
Return a string value for the named option. All % interpolations are Return a string value for the named option. All % interpolations are
expanded in the return values, based on the defaults passed into the expanded in the return values, based on the defaults passed into the
constructor and the DEFAULT section. Additional substitutions may be constructor and the DEFAULT section. Additional substitutions may be
provided using the `vars' argument, which must be a dictionary whose provided using the `vars` argument, which must be a dictionary whose
contents override any pre-existing defaults. If `option' is a key in contents override any pre-existing defaults. If `option` is a key in
`vars', the value from `vars' is used. `vars`, the value from `vars` is used.
getint(section, options, raw=False, vars=None, fallback=_UNSET) getint(section, options, raw=False, vars=None, fallback=_UNSET)
Like get(), but convert value to an integer. Like get(), but convert value to an integer.
@ -134,7 +135,7 @@ ConfigParser -- responsible for parsing a list of
write(fp, space_around_delimiters=True) write(fp, space_around_delimiters=True)
Write the configuration state in .ini format. If Write the configuration state in .ini format. If
`space_around_delimiters' is True (the default), delimiters `space_around_delimiters` is True (the default), delimiters
between keys and values are surrounded by spaces. between keys and values are surrounded by spaces.
""" """
@ -323,7 +324,7 @@ class MissingSectionHeaderError(ParsingError):
# Used in parser getters to indicate the default behaviour when a specific # Used in parser getters to indicate the default behaviour when a specific
# option is not found it to raise an exception. Created to enable `None' as # option is not found it to raise an exception. Created to enable `None` as
# a valid fallback value. # a valid fallback value.
_UNSET = object() _UNSET = object()
@ -357,7 +358,7 @@ class BasicInterpolation(Interpolation):
would resolve the "%(dir)s" to the value of dir. All reference would resolve the "%(dir)s" to the value of dir. All reference
expansions are done late, on demand. If a user needs to use a bare % in expansions are done late, on demand. If a user needs to use a bare % in
a configuration file, she can escape it by writing %%. Other % usage a configuration file, she can escape it by writing %%. Other % usage
is considered a user error and raises `InterpolationSyntaxError'.""" is considered a user error and raises `InterpolationSyntaxError`."""
_KEYCRE = re.compile(r"%\(([^)]+)\)s") _KEYCRE = re.compile(r"%\(([^)]+)\)s")
@ -418,7 +419,7 @@ class BasicInterpolation(Interpolation):
class ExtendedInterpolation(Interpolation): class ExtendedInterpolation(Interpolation):
"""Advanced variant of interpolation, supports the syntax used by """Advanced variant of interpolation, supports the syntax used by
`zc.buildout'. Enables interpolation between sections.""" `zc.buildout`. Enables interpolation between sections."""
_KEYCRE = re.compile(r"\$\{([^}]+)\}") _KEYCRE = re.compile(r"\$\{([^}]+)\}")
@ -691,10 +692,10 @@ class RawConfigParser(MutableMapping):
def read_file(self, f, source=None): def read_file(self, f, source=None):
"""Like read() but the argument must be a file-like object. """Like read() but the argument must be a file-like object.
The `f' argument must be iterable, returning one line at a time. The `f` argument must be iterable, returning one line at a time.
Optional second argument is the `source' specifying the name of the Optional second argument is the `source` specifying the name of the
file being read. If not given, it is taken from f.name. If `f' has no file being read. If not given, it is taken from f.name. If `f` has no
`name' attribute, `<???>' is used. `name` attribute, `<???>` is used.
""" """
if source is None: if source is None:
try: try:
@ -718,7 +719,7 @@ class RawConfigParser(MutableMapping):
All types held in the dictionary are converted to strings during All types held in the dictionary are converted to strings during
reading, including section names, option names and keys. reading, including section names, option names and keys.
Optional second argument is the `source' specifying the name of the Optional second argument is the `source` specifying the name of the
dictionary being read. dictionary being read.
""" """
elements_added = set() elements_added = set()
@ -742,15 +743,15 @@ class RawConfigParser(MutableMapping):
def get(self, section, option, *, raw=False, vars=None, fallback=_UNSET): def get(self, section, option, *, raw=False, vars=None, fallback=_UNSET):
"""Get an option value for a given section. """Get an option value for a given section.
If `vars' is provided, it must be a dictionary. The option is looked up If `vars` is provided, it must be a dictionary. The option is looked up
in `vars' (if provided), `section', and in `DEFAULTSECT' in that order. in `vars` (if provided), `section`, and in `DEFAULTSECT` in that order.
If the key is not found and `fallback' is provided, it is used as If the key is not found and `fallback` is provided, it is used as
a fallback value. `None' can be provided as a `fallback' value. a fallback value. `None` can be provided as a `fallback` value.
If interpolation is enabled and the optional argument `raw' is False, If interpolation is enabled and the optional argument `raw` is False,
all interpolations are expanded in the return values. all interpolations are expanded in the return values.
Arguments `raw', `vars', and `fallback' are keyword only. Arguments `raw`, `vars`, and `fallback` are keyword only.
The section DEFAULT is special. The section DEFAULT is special.
""" """
@ -810,8 +811,8 @@ class RawConfigParser(MutableMapping):
All % interpolations are expanded in the return values, based on the All % interpolations are expanded in the return values, based on the
defaults passed into the constructor, unless the optional argument defaults passed into the constructor, unless the optional argument
`raw' is true. Additional substitutions may be provided using the `raw` is true. Additional substitutions may be provided using the
`vars' argument, which must be a dictionary whose contents overrides `vars` argument, which must be a dictionary whose contents overrides
any pre-existing defaults. any pre-existing defaults.
The section DEFAULT is special. The section DEFAULT is special.
@ -853,8 +854,8 @@ class RawConfigParser(MutableMapping):
def has_option(self, section, option): def has_option(self, section, option):
"""Check for the existence of a given option in a given section. """Check for the existence of a given option in a given section.
If the specified `section' is None or an empty string, DEFAULT is If the specified `section` is None or an empty string, DEFAULT is
assumed. If the specified `section' does not exist, returns False.""" assumed. If the specified `section` does not exist, returns False."""
if not section or section == self.default_section: if not section or section == self.default_section:
option = self.optionxform(option) option = self.optionxform(option)
return option in self._defaults return option in self._defaults
@ -882,7 +883,7 @@ class RawConfigParser(MutableMapping):
def write(self, fp, space_around_delimiters=True): def write(self, fp, space_around_delimiters=True):
"""Write an .ini-format representation of the configuration state. """Write an .ini-format representation of the configuration state.
If `space_around_delimiters' is True (the default), delimiters If `space_around_delimiters` is True (the default), delimiters
between keys and values are surrounded by spaces. between keys and values are surrounded by spaces.
Please note that comments in the original configuration file are not Please note that comments in the original configuration file are not
@ -900,7 +901,7 @@ class RawConfigParser(MutableMapping):
self._sections[section].items(), d) self._sections[section].items(), d)
def _write_section(self, fp, section_name, section_items, delimiter): def _write_section(self, fp, section_name, section_items, delimiter):
"""Write a single section to the specified `fp'.""" """Write a single section to the specified `fp`."""
fp.write("[{}]\n".format(section_name)) fp.write("[{}]\n".format(section_name))
for key, value in section_items: for key, value in section_items:
value = self._interpolation.before_write(self, section_name, key, value = self._interpolation.before_write(self, section_name, key,
@ -974,8 +975,8 @@ class RawConfigParser(MutableMapping):
"""Parse a sectioned configuration file. """Parse a sectioned configuration file.
Each section in a configuration file contains a header, indicated by Each section in a configuration file contains a header, indicated by
a name in square brackets (`[]'), plus key/value options, indicated by a name in square brackets (`[]`), plus key/value options, indicated by
`name' and `value' delimited with a specific substring (`=' or `:' by `name` and `value` delimited with a specific substring (`=` or `:` by
default). default).
Values can span multiple lines, as long as they are indented deeper Values can span multiple lines, as long as they are indented deeper
@ -983,7 +984,7 @@ class RawConfigParser(MutableMapping):
lines may be treated as parts of multiline values or ignored. lines may be treated as parts of multiline values or ignored.
Configuration files may include comments, prefixed by specific Configuration files may include comments, prefixed by specific
characters (`#' and `;' by default). Comments may appear on their own characters (`#` and `;` by default). Comments may appear on their own
in an otherwise empty line or may be entered in lines holding values or in an otherwise empty line or may be entered in lines holding values or
section names. Please note that comments get stripped off when reading configuration files. section names. Please note that comments get stripped off when reading configuration files.
""" """