docutils.parsers.rst.directives

package documentation

(source)

This package contains directive implementation modules.

Module	`admonitions`	Admonition directives.
Module	`body`	Directives for additional body elements.
Module	`html`	Dummy module for backwards compatibility.
Module	`images`	Directives for figures and simple images.
Module	`misc`	Miscellaneous directives.
Module	`parts`	Directives for document parts.
Module	`references`	Directives for references and targets.
Module	`tables`	Directives for table elements.

From __init__.py:

Function	`choice`	Directive option utility function, supplied to enable options whose argument must be a member of a finite set of possible values (must be lower case). A custom conversion function must be written to use it...
Function	`class_option`	Convert the argument into a list of ID-compatible strings and return it. (Directive option conversion function.)
Function	`directive`	Locate and return a directive function from its language-dependent name. If not found in the current language, check English. Return None if the named directive cannot be found.
Function	`encoding`	Verifies the encoding argument by lookup. (Directive option conversion function.)
Function	`flag`	Check for a valid flag option (no argument) and return ``None``. (Directive option conversion function.)
Function	`format_values`	Undocumented
Function	`get_measure`	Check for a positive argument of one of the units and return a normalized string of the form "<value><unit>" (without space in between). (Directive option conversion function.)
Function	`length_or_percentage_or_unitless`	Return normalized string of a length or percentage unit. (Directive option conversion function.)
Function	`length_or_unitless`	Undocumented
Function	`nonnegative_int`	Check for a nonnegative integer argument; raise ``ValueError`` if not. (Directive option conversion function.)
Function	`parser_name`	Return a docutils parser whose name matches the argument. (Directive option conversion function.)
Function	`path`	Return the path argument unwrapped (with newlines removed). (Directive option conversion function.)
Function	`percentage`	Check for an integer percentage value with optional percent sign. (Directive option conversion function.)
Function	`positive_int`	Converts the argument into an integer. Raises ValueError for negative, zero, or non-integer values. (Directive option conversion function.)
Function	`positive_int_list`	Converts a space- or comma-separated list of values into a Python list of integers. (Directive option conversion function.)
Function	`register_directive`	Register a nonstandard application-defined directive function. Language lookups are not needed for such functions.
Function	`single_char_or_unicode`	A single character is returned as-is. Unicode characters codes are converted as in `unicode_code`. (Directive option conversion function.)
Function	`single_char_or_whitespace_or_unicode`	As with `single_char_or_unicode`, but "tab" and "space" are also supported. (Directive option conversion function.)
Function	`unchanged`	Return the argument text, unchanged. (Directive option conversion function.)
Function	`unchanged_required`	Return the argument text, unchanged. (Directive option conversion function.)
Function	`unicode_code`	Convert a Unicode character code to a Unicode character. (Directive option conversion function.)
Function	`uri`	Return the URI argument with unescaped whitespace removed. (Directive option conversion function.)
Function	`value_or`	Directive option conversion function.
Variable	`length_units`	Undocumented
Variable	`unicode_pattern`	Undocumented
Variable	`_directive_registry`	Mapping of directive name to (module name, class name). The directive name is canonical & must be lowercase. Language-dependent names are defined in the ``language`` subpackage.
Variable	`_directives`	Cache of imported directives.

_directive_registry: dict = (source)

Mapping of directive name to (module name, class name). The directive name is canonical & must be lowercase. Language-dependent names are defined in the ``language`` subpackage.

_directives: dict = (source)

Cache of imported directives.

def directive(directive_name, language_module, document): (source)

Locate and return a directive function from its language-dependent name. If not found in the current language, check English. Return None if the named directive cannot be found.

def register_directive(name, directive): (source)

def flag(argument): (source)

Check for a valid flag option (no argument) and return ``None``. (Directive option conversion function.) Raise ``ValueError`` if an argument is found.

def unchanged_required(argument): (source)

Return the argument text, unchanged. (Directive option conversion function.) Raise ``ValueError`` if no argument is found.

def unchanged(argument): (source)

Return the argument text, unchanged. (Directive option conversion function.) No argument implies empty string ("").

def path(argument): (source)

Return the path argument unwrapped (with newlines removed). (Directive option conversion function.) Raise ``ValueError`` if no argument is found.

def uri(argument): (source)

Return the URI argument with unescaped whitespace removed. (Directive option conversion function.) Raise ``ValueError`` if no argument is found.

def nonnegative_int(argument): (source)

Check for a nonnegative integer argument; raise ``ValueError`` if not. (Directive option conversion function.)

def percentage(argument): (source)

Check for an integer percentage value with optional percent sign. (Directive option conversion function.)

length_units: list[str] = (source)

Undocumented

def get_measure(argument, units): (source)

Check for a positive argument of one of the units and return a normalized string of the form "<value><unit>" (without space in between). (Directive option conversion function.) To be called from directive option conversion functions.

def length_or_unitless(argument): (source)

Undocumented

def length_or_percentage_or_unitless(argument, default=''): (source)

Return normalized string of a length or percentage unit. (Directive option conversion function.) Add <default> if there is no unit. Raise ValueError if the argument is not a positive measure of one of the valid CSS units (or without unit). >>> length_or_percentage_or_unitless('3 pt') '3pt' >>> length_or_percentage_or_unitless('3%', 'em') '3%' >>> length_or_percentage_or_unitless('3') '3' >>> length_or_percentage_or_unitless('3', 'px') '3px'

def class_option(argument): (source)

Convert the argument into a list of ID-compatible strings and return it. (Directive option conversion function.) Raise ``ValueError`` if no argument is found.

unicode_pattern = (source)

Undocumented

def unicode_code(code): (source)

Convert a Unicode character code to a Unicode character. (Directive option conversion function.) Codes may be decimal numbers, hexadecimal numbers (prefixed by ``0x``, ``x``, ``\x``, ``U+``, ``u``, or ``\u``; e.g. ``U+262E``), or XML-style numeric character entities (e.g. ``☮``). Other text remains as-is. Raise ValueError for illegal Unicode code values.

def single_char_or_unicode(argument): (source)

A single character is returned as-is. Unicode characters codes are converted as in `unicode_code`. (Directive option conversion function.)

def single_char_or_whitespace_or_unicode(argument): (source)

As with `single_char_or_unicode`, but "tab" and "space" are also supported. (Directive option conversion function.)

def positive_int(argument): (source)

Converts the argument into an integer. Raises ValueError for negative, zero, or non-integer values. (Directive option conversion function.)

def positive_int_list(argument): (source)

Converts a space- or comma-separated list of values into a Python list of integers. (Directive option conversion function.) Raises ValueError for non-positive-integer values.

def encoding(argument): (source)

Verifies the encoding argument by lookup. (Directive option conversion function.) Raises ValueError for unknown encodings.

def choice(argument, values): (source)

Directive option utility function, supplied to enable options whose argument must be a member of a finite set of possible values (must be lower case). A custom conversion function must be written to use it. For example:: from docutils.parsers.rst import directives def yesno(argument): return directives.choice(argument, ('yes', 'no')) Raise ``ValueError`` if no argument is found or if the argument's value is not valid (not an entry in the supplied list).

def format_values(values): (source)

Undocumented

def value_or(values, other): (source)

Directive option conversion function. The argument can be any of `values` or `argument_type`.

def parser_name(argument): (source)

Return a docutils parser whose name matches the argument. (Directive option conversion function.) Return `None`, if the argument evaluates to `False`. Raise `ValueError` if importing the parser module fails.