4.4.1.1.8.2.1. directives

• 4.4.1.1.8.2.1.1. admonitions
• 4.4.1.1.8.2.1.2. body
• 4.4.1.1.8.2.1.3. html
• 4.4.1.1.8.2.1.4. images
• 4.4.1.1.8.2.1.5. misc
• 4.4.1.1.8.2.1.6. parts
• 4.4.1.1.8.2.1.7. references
• 4.4.1.1.8.2.1.8. tables

This package contains directive implementation modules.

docutils.parsers.rst.directives.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).

docutils.parsers.rst.directives.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.

docutils.parsers.rst.directives.encoding(argument)

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

Raises ValueError for unknown encodings.

docutils.parsers.rst.directives.flag(argument)

Check for a valid flag option (no argument) and return None. (Directive option conversion function.)

Raise ValueError if an argument is found.

docutils.parsers.rst.directives.format_values(values)

docutils.parsers.rst.directives.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).

To be called from directive option conversion functions.

docutils.parsers.rst.directives.length_or_percentage_or_unitless(argument, default='')

Return normalized string of a length or percentage unit.

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'

docutils.parsers.rst.directives.length_or_unitless(argument)

docutils.parsers.rst.directives.nonnegative_int(argument)

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

docutils.parsers.rst.directives.path(argument)

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

Raise ValueError if no argument is found.

docutils.parsers.rst.directives.percentage(argument)

Check for an integer percentage value with optional percent sign.

docutils.parsers.rst.directives.positive_int(argument)

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

docutils.parsers.rst.directives.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.

docutils.parsers.rst.directives.register_directive(name, directive)

Register a nonstandard application-defined directive function. Language lookups are not needed for such functions.

docutils.parsers.rst.directives.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.)

docutils.parsers.rst.directives.single_char_or_whitespace_or_unicode(argument)

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

docutils.parsers.rst.directives.unchanged(argument)

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

No argument implies empty string (“”).

docutils.parsers.rst.directives.unchanged_required(argument)

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

Raise ValueError if no argument is found.

docutils.parsers.rst.directives.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.

docutils.parsers.rst.directives.uri(argument)

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

Raise ValueError if no argument is found.

docutils.parsers.rst.directives.value_or(values, other)

The argument can be any of values or argument_type.