docutils.parsers.rst.directives

package documentation

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`	No summary
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`	No summary
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 =

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 =

Cache of imported directives.

def directive(directive_name, language_module, document):

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

def flag(argument):

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

Return the argument text, unchanged. (Directive option conversion function.)

Raise ValueError if no argument is found.

def unchanged(argument):

Return the argument text, unchanged. (Directive option conversion function.)

No argument implies empty string ("").

def path(argument):

Return the path argument unwrapped (with newlines removed). (Directive option conversion function.)

Raise ValueError if no argument is found.

def uri(argument):

Return the URI argument with unescaped whitespace removed. (Directive option conversion function.)

Raise ValueError if no argument is found.

def nonnegative_int(argument):

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

def percentage(argument):

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

length_units: list[str] =

Undocumented

def get_measure(argument, units):

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

Undocumented

def length_or_percentage_or_unitless(argument, default=''):

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

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 =

Undocumented

def unicode_code(code):

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

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

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

def positive_int(argument):

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

def positive_int_list(argument):

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

Verifies the encoding argument by lookup. (Directive option conversion function.)

Raises ValueError for unknown encodings.

def choice(argument, values):

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

Undocumented

def value_or(values, other):

Directive option conversion function.

The argument can be any of values or argument_type.

def parser_name(argument):

Return a docutils parser whose name matches the argument. (Directive option conversion function.)

Return None, if the argument evaluates to False.