docutils.utils

package documentation
(source)

Miscellaneous utilities for the documentation utilities.

Module code_analyzer Lexical analysis of formal languages (i.e. code) using Pygments.
Module error_reporting Deprecated module to handle Exceptions across Python versions.
Package math This is the Docutils (Python Documentation Utilities) "math" sub-package.
Module punctuation_chars No module docstring; 1/5 variable, 1/1 function documented
Module roman Convert to and from Roman numerals
Module smartquotes ========================= Smart Quotes for Docutils =========================
Module urischemes `schemes` is a dictionary with lowercase URI addressing schemes as keys and descriptions as values. It was compiled from the index at http://www.iana.org/assignments/uri-schemes (revised 2005-11-28) and an older list at https://www...

From __init__.py:

Class BadOptionDataError Undocumented
Class BadOptionError Undocumented
Class DependencyList List of dependencies, with file recording support.
Class DuplicateOptionError Undocumented
Class ExtensionOptionError Undocumented
Class NameValueError Undocumented
Class Reporter Info/warning/error reporter and ``system_message`` element generator.
Class SystemMessage Undocumented
Class SystemMessagePropagation Undocumented
Function assemble_option_dict Return a mapping of option names to values.
Function clean_rcs_keywords Undocumented
Function column_indices Indices of Unicode string `text` when skipping combining characters.
Function column_width Return the column width of text.
Function decode_path Ensure `path` is Unicode. Return `str` instance.
Function escape2null Return a string with escape-backslashes converted to nulls.
Function extract_extension_options Return a dictionary mapping extension option names to converted values.
Function extract_name_value Return a list of (name, value) from a line of the form "name=value ...".
Function extract_options Return a list of option (name, value) pairs from field names & bodies.
Function find_combining_chars Return indices of all combining chars in Unicode string `text`.
Function find_file_in_dirs Search for `path` in the list of directories `dirs`.
Function get_source_line Return the "source" and "line" attributes from the `node` given or from its closest ancestor.
Function get_stylesheet_list Retrieve list of stylesheet references from the settings object.
Function get_stylesheet_reference Retrieve a stylesheet reference from the settings object.
Function get_trim_footnote_ref_space Return whether or not to trim footnote space.
Function new_document Return a new empty document object.
Function new_reporter Return a new Reporter object.
Function normalize_language_tag Return a list of normalized combinations for a `BCP 47` language tag.
Function relative_path Build and return a path to `target`, relative to `source` (both files).
Function split_escaped_whitespace Split `text` on escaped whitespace (null+space or null+newline). Return a list of strings.
Function strip_combining_chars Undocumented
Function uniq Undocumented
Function version_identifier 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...
Variable east_asian_widths Mapping of result codes from `unicodedata.east_asian_widt()` to character column widths.
Variable release_level_abbreviations Undocumented
def extract_extension_options(field_list, options_spec): (source)

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.).

def extract_options(field_list): (source)

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.).

def assemble_option_dict(option_list, options_spec): (source)

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).

def decode_path(path): (source)

Ensure `path` is Unicode. Return `str` instance. Decode file/path string in a failsafe manner if not already done.

def extract_name_value(line): (source)

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.).

def new_reporter(source_path, settings): (source)

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.

def new_document(source_path, settings=None): (source)

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()

def clean_rcs_keywords(paragraph, keyword_substitutions): (source)

Undocumented

def relative_path(source, target): (source)

Build and return a path to `target`, relative to `source` (both files). If there is no common prefix, return the absolute path to `target`.

def get_stylesheet_reference(settings, relative_to=None): (source)

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.

def get_stylesheet_list(settings): (source)

Retrieve list of stylesheet references from the settings object.

def find_file_in_dirs(path, dirs): (source)

Search for `path` in the list of directories `dirs`. Return the first expansion that matches an existing file.

def get_trim_footnote_ref_space(settings): (source)

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'.

def get_source_line(node): (source)

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

def escape2null(text): (source)

Return a string with escape-backslashes converted to nulls.

def split_escaped_whitespace(text): (source)

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

def strip_combining_chars(text): (source)

Undocumented

def find_combining_chars(text): (source)

Return indices of all combining chars in Unicode string `text`. >>> from docutils.utils import find_combining_chars >>> find_combining_chars('A t̆ab̆lĕ') [3, 6, 9]

def column_indices(text): (source)

Indices of Unicode string `text` when skipping combining characters. >>> from docutils.utils import column_indices >>> column_indices('A t̆ab̆lĕ') [0, 1, 2, 4, 5, 7, 8]

east_asian_widths: dict[str, int] = (source)

Mapping of result codes from `unicodedata.east_asian_widt()` to character column widths.

def column_width(text): (source)

Return the column width of text. Correct ``len(text)`` for wide East Asian and combining Unicode chars.

def uniq(L): (source)

Undocumented

def normalize_language_tag(tag): (source)

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']

release_level_abbreviations: dict[str, str] = (source)

Undocumented

def version_identifier(version_info=None): (source)

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).