Namespaces
namespace	code_analyzer

namespace	error_reporting

namespace	math

namespace	punctuation_chars

namespace	smartquotes

namespace	urischemes

Classes
class	BadOptionDataError

class	BadOptionError

class	DependencyList

class	DuplicateOptionError

class	ExtensionOptionError

class	NameValueError

class	Reporter

class	SystemMessage

class	SystemMessagePropagation

Functions
	extract_extension_options (field_list, options_spec)

	extract_options (field_list)

	assemble_option_dict (option_list, options_spec)

	decode_path (path)

	extract_name_value (line)

	new_reporter (source_path, settings)

	new_document (source_path, settings=None)

	clean_rcs_keywords (paragraph, keyword_substitutions)

	relative_path (source, target)

	get_stylesheet_reference (settings, relative_to=None)

	get_stylesheet_list (settings)

	find_file_in_dirs (path, dirs)

	get_trim_footnote_ref_space (settings)

	get_source_line (node)

	escape2null (text)

	split_escaped_whitespace (text)

	strip_combining_chars (text)

	find_combining_chars (text)

	column_indices (text)

	column_width (text)

	uniq (L)

	normalize_language_tag (tag)

	xml_declaration (encoding=None)

	version_identifier (version_info=None)

Variables
dict	east_asian_widths

dict	release_level_abbreviations

Detailed Description

Miscellaneous utilities for the documentation utilities.

Function Documentation

◆ assemble_option_dict()

docutils.utils.assemble_option_dict	(	option_list,
		options_spec
	)

Return a mapping of option names to values.

:Parameters:
    - `option_list`: A list of (name, value) pairs (the output of
      `extract_options()`).
    - `options_spec`: Dictionary mapping known option names to a
      conversion function such as `int` or `float`.

:Exceptions:
    - `KeyError` for unknown option names.
    - `DuplicateOptionError` for duplicate options.
    - `ValueError` for invalid option values (raised by conversion
       function).
    - `TypeError` for invalid option value types (raised by conversion
       function).

◆ column_indices()

docutils.utils.column_indices ( text )

Indices of Unicode string `text` when skipping combining characters.

>>> from docutils.utils import column_indices
>>> column_indices('A t̆ab̆lĕ')
[0, 1, 2, 4, 5, 7, 8]

◆ column_width()

docutils.utils.column_width ( text )

Return the column width of text.

Correct ``len(text)`` for wide East Asian and combining Unicode chars.

◆ decode_path()

docutils.utils.decode_path ( path )

Ensure `path` is Unicode. Return `str` instance.

Decode file/path string in a failsafe manner if not already done.

◆ escape2null()

docutils.utils.escape2null ( text )

Return a string with escape-backslashes converted to nulls.

◆ extract_extension_options()

docutils.utils.extract_extension_options	(	field_list,
		options_spec
	)

Return a dictionary mapping extension option names to converted values.

:Parameters:
    - `field_list`: A flat field list without field arguments, where each
      field body consists of a single paragraph only.
    - `options_spec`: Dictionary mapping known option names to a
      conversion function such as `int` or `float`.

:Exceptions:
    - `KeyError` for unknown option names.
    - `ValueError` for invalid option values (raised by the conversion
       function).
    - `TypeError` for invalid option value types (raised by conversion
       function).
    - `DuplicateOptionError` for duplicate options.
    - `BadOptionError` for invalid fields.
    - `BadOptionDataError` for invalid option data (missing name,
      missing data, bad quotes, etc.).

◆ extract_name_value()

docutils.utils.extract_name_value ( line )

Return a list of (name, value) from a line of the form "name=value ...".

:Exception:
    `NameValueError` for invalid input (missing name, missing data, bad
    quotes, etc.).

◆ extract_options()

docutils.utils.extract_options ( field_list )

Return a list of option (name, value) pairs from field names & bodies.

:Parameter:
    `field_list`: A flat field list, where each field name is a single
    word and each field body consists of a single paragraph only.

:Exceptions:
    - `BadOptionError` for invalid fields.
    - `BadOptionDataError` for invalid option data (missing name,
      missing data, bad quotes, etc.).

◆ find_combining_chars()

docutils.utils.find_combining_chars ( text )

Return indices of all combining chars in  Unicode string `text`.

>>> from docutils.utils import find_combining_chars
>>> find_combining_chars('A t̆ab̆lĕ')
[3, 6, 9]

◆ find_file_in_dirs()

docutils.utils.find_file_in_dirs	(	path,
		dirs
	)

Search for `path` in the list of directories `dirs`.

Return the first expansion that matches an existing file.

◆ get_source_line()

docutils.utils.get_source_line ( node )

Return the "source" and "line" attributes from the `node` given or from
its closest ancestor.

◆ get_stylesheet_list()

docutils.utils.get_stylesheet_list ( settings )

Retrieve list of stylesheet references from the settings object.

◆ get_stylesheet_reference()

docutils.utils.get_stylesheet_reference	(	settings,
		relative_to = `None`
	)

Retrieve a stylesheet reference from the settings object.

Deprecated. Use get_stylesheet_list() instead to
enable specification of multiple stylesheets as a comma-separated
list.

◆ get_trim_footnote_ref_space()

docutils.utils.get_trim_footnote_ref_space ( settings )

Return whether or not to trim footnote space.

If trim_footnote_reference_space is not None, return it.

If trim_footnote_reference_space is None, return False unless the
footnote reference style is 'superscript'.

◆ new_document()

docutils.utils.new_document	(	source_path,
		settings = `None`
	)

Return a new empty document object.

:Parameters:
    `source_path` : string
        The path to or description of the source text of the document.
    `settings` : optparse.Values object
        Runtime settings.  If none are provided, a default core set will
        be used.  If you will use the document object with any Docutils
        components, you must provide their default settings as well.

        For example, if parsing rST, at least provide the rst-parser
        settings, obtainable as follows:

        Defaults for parser component::

            settings = docutils.frontend.get_default_settings(
                           docutils.parsers.rst.Parser)

        Defaults and configuration file customizations::

            settings = docutils.core.Publisher(
                parser=docutils.parsers.rst.Parser).get_settings()

◆ new_reporter()

docutils.utils.new_reporter	(	source_path,
		settings
	)

Return a new Reporter object.

:Parameters:
    `source` : string
        The path to or description of the source text of the document.
    `settings` : optparse.Values object
        Runtime settings.

◆ normalize_language_tag()

docutils.utils.normalize_language_tag ( tag )

Return a list of normalized combinations for a `BCP 47` language tag.

Example:

>>> from docutils.utils import normalize_language_tag
>>> normalize_language_tag('de_AT-1901')
['de-at-1901', 'de-at', 'de-1901', 'de']
>>> normalize_language_tag('de-CH-x_altquot')
['de-ch-x-altquot', 'de-ch', 'de-x-altquot', 'de']

◆ relative_path()

docutils.utils.relative_path	(	source,
		target
	)

Build and return a path to `target`, relative to `source` (both files).

The return value is a `str` suitable to be included in `source`
as a reference to `target`.

:Parameters:
    `source` : path-like object or None
        Path of a file in the start directory for the relative path
        (the file does not need to exist).
        The value ``None`` is replaced with "<cwd>/dummy_file".
    `target` : path-like object
        End point of the returned relative path.

Differences to `os.path.relpath()`:

* Inverse argument order.
* `source` is assumed to be a FILE in the start directory (add a "dummy"
  file name to obtain the path relative from a directory)
  while `os.path.relpath()` expects a DIRECTORY as `start` argument.
* Always use Posix path separator ("/") for the output.
* Use `os.sep` for parsing the input
  (changing the value of `os.sep` is ignored by `os.relpath()`).
* If there is no common prefix, return the absolute path to `target`.

Differences to `pathlib.PurePath.relative_to(other)`:

* pathlib offers an object oriented interface.
* `source` expects path to a FILE while `other` expects a DIRECTORY.
* `target` defaults to the cwd, no default value for `other`.
* `relative_path()` always returns a path (relative or absolute),
  while `PurePath.relative_to()` raises a ValueError
  if `target` is not a subpath of `other` (no ".." inserted).

◆ split_escaped_whitespace()

docutils.utils.split_escaped_whitespace ( text )

Split `text` on escaped whitespace (null+space or null+newline).
Return a list of strings.

◆ version_identifier()

docutils.utils.version_identifier ( version_info = None )

Return a version identifier string built from `version_info`, a
`docutils.VersionInfo` namedtuple instance or compatible tuple. If
`version_info` is not provided, by default return a version identifier
string based on `docutils.__version_info__` (i.e. the current Docutils
version).

◆ xml_declaration()

docutils.utils.xml_declaration ( encoding = None )

Return an XML text declaration.

Include an encoding declaration, if `encoding`
is not 'unicode', '', or None.

Variable Documentation

◆ east_asian_widths

dict docutils.utils.east_asian_widths

Initial value:

=  {'W': 2,   # Wide
                     'F': 2,   # Full-width (wide)
                     'Na': 1,  # Narrow
                     'H': 1,   # Half-width (narrow)
                     'N': 1,   # Neutral (not East Asian, treated as narrow)
                     'A': 1,   # Ambiguous (s/b wide in East Asian context,
                     }

◆ release_level_abbreviations

dict docutils.utils.release_level_abbreviations