docutils.utils

package documentation

(source)

Miscellaneous utilities for the documentation utilities.

Package	`math`	This is the Docutils (Python Documentation Utilities) "math" sub-package.
Module	`code_analyzer`	Lexical analysis of formal languages (i.e. code) using Pygments.
Module	`error_reporting`	Error reporting should be safe from encoding/decoding errors. However, implicit conversions of strings and exceptions like
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`	No summary

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 `nodes.reprunicode` object.
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	`unique_combinations`	Return `itertools.combinations`.
Function	`version_identifier`	No summary
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`.
Unknown Field: newfield
exceptions	Exceptions
Unknown Field: 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.

Raises
`BadOptionError`	for invalid fields.
`BadOptionDataError`	for invalid option data (missing name, missing data, bad quotes, etc.).
Unknown Field: 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.

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`.
Unknown Field: newfield
exceptions	Exceptions
Unknown Field: 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 nodes.reprunicode object.

Decode file/path string in a failsave 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 ...".

Unknown Field: 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_path	Undocumented
settings:optparse.Values object	Runtime settings.
source:string	The path to or description of the source text of the document.

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:

settings = docutils.frontend.OptionParser(
    components=(docutils.parsers.rst.Parser,)
    ).get_default_values()

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(u'A t̆ab̆lĕ')
[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(u'A t̆ab̆lĕ')
[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 unique_combinations(items, n): (source)

Return itertools.combinations.

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