python-docs-venv/lib/python3.11/site-packages/docutils/__init__.py - datasketches-python - Git at Google

 # $Id: __init__.py 8900 2021-11-23 17:44:14Z grubert $
 # Author: David Goodger <goodger@python.org>
 # Copyright: This module has been placed in the public domain.

 """
 This is the Docutils (Python Documentation Utilities) package.

 Package Structure
 =================

 Modules:

 - __init__.py: Contains component base classes, exception classes, and
   Docutils version information.

 - core.py: Contains the ``Publisher`` class and ``publish_*()`` convenience
   functions.

 - frontend.py: Runtime settings (command-line interface, configuration files)
   processing, for Docutils front-ends.

 - io.py: Provides a uniform API for low-level input and output.

 - nodes.py: Docutils document tree (doctree) node class library.

 - statemachine.py: A finite state machine specialized for
   regular-expression-based text filters.

 Subpackages:

 - languages: Language-specific mappings of terms.

 - parsers: Syntax-specific input parser modules or packages.

 - readers: Context-specific input handlers which understand the data
   source and manage a parser.

 - transforms: Modules used by readers and writers to modify DPS
   doctrees.

 - utils: Contains the ``Reporter`` system warning class and miscellaneous
   utilities used by readers, writers, and transforms.

   utils/urischemes.py: Contains a complete mapping of known URI addressing
   scheme names to descriptions.

 - utils/math: Contains functions for conversion of mathematical notation
   between different formats (LaTeX, MathML, text, ...).

 - writers: Format-specific output translators.
 """

 import sys
 from collections import namedtuple


 __docformat__ = 'reStructuredText'

 __version__ = '0.18.1'
 """Docutils version identifier (complies with PEP 440)::

     major.minor[.micro][releaselevel[serial]][.dev]

 For version comparison operations, use `__version_info__` (see, below)
 rather than parsing the text of `__version__`.

 See 'Version Numbering' in docs/dev/policies.txt.
 """

 # from functools import total_ordering
 # @total_ordering
 class VersionInfo(namedtuple('VersionInfo',
                              'major minor micro releaselevel serial release')):

     def __new__(cls, major=0, minor=0, micro=0,
                 releaselevel='final', serial=0, release=True):
         releaselevels = ('alpha', 'beta', 'candidate', 'final')
         if releaselevel not in releaselevels:
             raise ValueError('releaselevel must be one of %r.'
                              % (releaselevels, ))
         if releaselevel == 'final':
             if not release:
                 raise ValueError('releaselevel "final" must not be used '
                              'with development versions (leads to wrong '
                              'version ordering of the related __version__')
             if serial != 0:
                 raise ValueError('"serial" must be 0 for final releases')

         return super(VersionInfo, cls).__new__(cls, major, minor, micro,
                                                releaselevel, serial, release)

     def __lt__(self, other):
         if isinstance(other, tuple):
             other = VersionInfo(*other)
         return tuple.__lt__(self, other)

     def __gt__(self, other):
         if isinstance(other, tuple):
             other = VersionInfo(*other)
         return tuple.__gt__(self, other)

     def __le__(self, other):
         if isinstance(other, tuple):
             other = VersionInfo(*other)
         return tuple.__le__(self, other)

     def __ge__(self, other):
         if isinstance(other, tuple):
             other = VersionInfo(*other)
         return tuple.__ge__(self, other)

 __version_info__ = VersionInfo(
     major=0,
     minor=18,
     micro=1,
     releaselevel='final', # one of 'alpha', 'beta', 'candidate', 'final'
     # pre-release serial number (0 for final releases and active development):
     serial=0,
     release=True # True for official releases and pre-releases
     )
 """Comprehensive version information tuple. See 'Version Numbering' in
 docs/dev/policies.txt."""

 __version_details__ = 'release'
 """Optional extra version details (e.g. 'snapshot 2005-05-29, r3410').
 (For development and release status see `__version_info__`.)
 """


 class ApplicationError(Exception): pass

 class DataError(ApplicationError): pass


 class SettingsSpec(object):

     """
     Runtime setting specification base class.

     SettingsSpec subclass objects used by `docutils.frontend.OptionParser`.
     """

     settings_spec = ()
     """Runtime settings specification.  Override in subclasses.

     Defines runtime settings and associated command-line options, as used by
     `docutils.frontend.OptionParser`.  This is a tuple of:

     - Option group title (string or `None` which implies no group, just a list
       of single options).

     - Description (string or `None`).

     - A sequence of option tuples.  Each consists of:

       - Help text (string)

       - List of option strings (e.g. ``['-Q', '--quux']``).

       - Dictionary of keyword arguments sent to the OptionParser/OptionGroup
         ``add_option`` method.

         Runtime setting names are derived implicitly from long option names
         ('--a-setting' becomes ``settings.a_setting``) or explicitly from the
         'dest' keyword argument.

         Most settings will also have a 'validator' keyword & function.  The
         validator function validates setting values (from configuration files
         and command-line option arguments) and converts them to appropriate
         types.  For example, the ``docutils.frontend.validate_boolean``
         function, **required by all boolean settings**, converts true values
         ('1', 'on', 'yes', and 'true') to 1 and false values ('0', 'off',
         'no', 'false', and '') to 0.  Validators need only be set once per
         setting.  See the `docutils.frontend.validate_*` functions.

         See the optparse docs for more details.

     - More triples of group title, description, options, as many times as
       needed.  Thus, `settings_spec` tuples can be simply concatenated.
     """

     settings_defaults = None
     """A dictionary of defaults for settings not in `settings_spec` (internal
     settings, intended to be inaccessible by command-line and config file).
     Override in subclasses."""

     settings_default_overrides = None
     """A dictionary of auxiliary defaults, to override defaults for settings
     defined in other components.  Override in subclasses."""

     relative_path_settings = ()
     """Settings containing filesystem paths.  Override in subclasses.
     Settings listed here are to be interpreted relative to the current working
     directory."""

     config_section = None
     """The name of the config file section specific to this component
     (lowercase, no brackets).  Override in subclasses."""

     config_section_dependencies = None
     """A list of names of config file sections that are to be applied before
     `config_section`, in order (from general to specific).  In other words,
     the settings in `config_section` are to be overlaid on top of the settings
     from these sections.  The "general" section is assumed implicitly.
     Override in subclasses."""


 class TransformSpec:

     """
     Runtime transform specification base class.

     TransformSpec subclass objects used by `docutils.transforms.Transformer`.
     """

     def get_transforms(self):
         """Transforms required by this class.  Override in subclasses."""
         if self.default_transforms != ():
             import warnings
             warnings.warn('TransformSpec: the "default_transforms" attribute '
                           'will be removed in Docutils 1.1.\n'
                           'Use get_transforms() method instead.',
                           DeprecationWarning)
             return list(self.default_transforms)
         return []

     # Deprecated; for compatibility.
     default_transforms = ()

     unknown_reference_resolvers = ()
     """List of functions to try to resolve unknown references.  Unknown
     references have a 'refname' attribute which doesn't correspond to any
     target in the document.  Called when the transforms in
     `docutils.transforms.references` are unable to find a correct target.  The
     list should contain functions which will try to resolve unknown
     references, with the following signature::

         def reference_resolver(node):
             '''Returns boolean: true if resolved, false if not.'''

     If the function is able to resolve the reference, it should also remove
     the 'refname' attribute and mark the node as resolved::

         del node['refname']
         node.resolved = 1

     Each function must have a "priority" attribute which will affect the order
     the unknown_reference_resolvers are run::

         reference_resolver.priority = 100

     Override in subclasses."""


 class Component(SettingsSpec, TransformSpec):

     """Base class for Docutils components."""

     component_type = None
     """Name of the component type ('reader', 'parser', 'writer').  Override in
     subclasses."""

     supported = ()
     """Names for this component.  Override in subclasses."""

     def supports(self, format):
         """
         Is `format` supported by this component?

         To be used by transforms to ask the dependent component if it supports
         a certain input context or output format.
         """
         return format in self.supported
	# $Id: __init__.py 8900 2021-11-23 17:44:14Z grubert $
	# Author: David Goodger <goodger@python.org>
	# Copyright: This module has been placed in the public domain.

	"""
	This is the Docutils (Python Documentation Utilities) package.

	Package Structure
	=================

	Modules:

	- __init__.py: Contains component base classes, exception classes, and
	Docutils version information.

	- core.py: Contains the ``Publisher`` class and ``publish_*()`` convenience
	functions.

	- frontend.py: Runtime settings (command-line interface, configuration files)
	processing, for Docutils front-ends.

	- io.py: Provides a uniform API for low-level input and output.

	- nodes.py: Docutils document tree (doctree) node class library.

	- statemachine.py: A finite state machine specialized for
	regular-expression-based text filters.

	Subpackages:

	- languages: Language-specific mappings of terms.

	- parsers: Syntax-specific input parser modules or packages.

	- readers: Context-specific input handlers which understand the data
	source and manage a parser.

	- transforms: Modules used by readers and writers to modify DPS
	doctrees.

	- utils: Contains the ``Reporter`` system warning class and miscellaneous
	utilities used by readers, writers, and transforms.

	utils/urischemes.py: Contains a complete mapping of known URI addressing
	scheme names to descriptions.

	- utils/math: Contains functions for conversion of mathematical notation
	between different formats (LaTeX, MathML, text, ...).

	- writers: Format-specific output translators.
	"""

	import sys
	from collections import namedtuple


	__docformat__ = 'reStructuredText'

	__version__ = '0.18.1'
	"""Docutils version identifier (complies with PEP 440)::

	major.minor[.micro][releaselevel[serial]][.dev]

	For version comparison operations, use `__version_info__` (see, below)
	rather than parsing the text of `__version__`.

	See 'Version Numbering' in docs/dev/policies.txt.
	"""

	# from functools import total_ordering
	# @total_ordering
	class VersionInfo(namedtuple('VersionInfo',
	'major minor micro releaselevel serial release')):

	def __new__(cls, major=0, minor=0, micro=0,
	releaselevel='final', serial=0, release=True):
	releaselevels = ('alpha', 'beta', 'candidate', 'final')
	if releaselevel not in releaselevels:
	raise ValueError('releaselevel must be one of %r.'
	% (releaselevels, ))
	if releaselevel == 'final':
	if not release:
	raise ValueError('releaselevel "final" must not be used '
	'with development versions (leads to wrong '
	'version ordering of the related __version__')
	if serial != 0:
	raise ValueError('"serial" must be 0 for final releases')

	return super(VersionInfo, cls).__new__(cls, major, minor, micro,
	releaselevel, serial, release)

	def __lt__(self, other):
	if isinstance(other, tuple):
	other = VersionInfo(*other)
	return tuple.__lt__(self, other)

	def __gt__(self, other):
	if isinstance(other, tuple):
	other = VersionInfo(*other)
	return tuple.__gt__(self, other)

	def __le__(self, other):
	if isinstance(other, tuple):
	other = VersionInfo(*other)
	return tuple.__le__(self, other)

	def __ge__(self, other):
	if isinstance(other, tuple):
	other = VersionInfo(*other)
	return tuple.__ge__(self, other)

	__version_info__ = VersionInfo(
	major=0,
	minor=18,
	micro=1,
	releaselevel='final', # one of 'alpha', 'beta', 'candidate', 'final'
	# pre-release serial number (0 for final releases and active development):
	serial=0,
	release=True # True for official releases and pre-releases
	)
	"""Comprehensive version information tuple. See 'Version Numbering' in
	docs/dev/policies.txt."""

	__version_details__ = 'release'
	"""Optional extra version details (e.g. 'snapshot 2005-05-29, r3410').
	(For development and release status see `__version_info__`.)
	"""


	class ApplicationError(Exception): pass

	class DataError(ApplicationError): pass


	class SettingsSpec(object):

	"""
	Runtime setting specification base class.

	SettingsSpec subclass objects used by `docutils.frontend.OptionParser`.
	"""

	settings_spec = ()
	"""Runtime settings specification. Override in subclasses.

	Defines runtime settings and associated command-line options, as used by
	`docutils.frontend.OptionParser`. This is a tuple of:

	- Option group title (string or `None` which implies no group, just a list
	of single options).

	- Description (string or `None`).

	- A sequence of option tuples. Each consists of:

	- Help text (string)

	- List of option strings (e.g. ``['-Q', '--quux']``).

	- Dictionary of keyword arguments sent to the OptionParser/OptionGroup
	``add_option`` method.

	Runtime setting names are derived implicitly from long option names
	('--a-setting' becomes ``settings.a_setting``) or explicitly from the
	'dest' keyword argument.

	Most settings will also have a 'validator' keyword & function. The
	validator function validates setting values (from configuration files
	and command-line option arguments) and converts them to appropriate
	types. For example, the ``docutils.frontend.validate_boolean``
	function, required by all boolean settings, converts true values
	('1', 'on', 'yes', and 'true') to 1 and false values ('0', 'off',
	'no', 'false', and '') to 0. Validators need only be set once per
	setting. See the `docutils.frontend.validate_*` functions.

	See the optparse docs for more details.

	- More triples of group title, description, options, as many times as
	needed. Thus, `settings_spec` tuples can be simply concatenated.
	"""

	settings_defaults = None
	"""A dictionary of defaults for settings not in `settings_spec` (internal
	settings, intended to be inaccessible by command-line and config file).
	Override in subclasses."""

	settings_default_overrides = None
	"""A dictionary of auxiliary defaults, to override defaults for settings
	defined in other components. Override in subclasses."""

	relative_path_settings = ()
	"""Settings containing filesystem paths. Override in subclasses.
	Settings listed here are to be interpreted relative to the current working
	directory."""

	config_section = None
	"""The name of the config file section specific to this component
	(lowercase, no brackets). Override in subclasses."""

	config_section_dependencies = None
	"""A list of names of config file sections that are to be applied before
	`config_section`, in order (from general to specific). In other words,
	the settings in `config_section` are to be overlaid on top of the settings
	from these sections. The "general" section is assumed implicitly.
	Override in subclasses."""


	class TransformSpec:

	"""
	Runtime transform specification base class.

	TransformSpec subclass objects used by `docutils.transforms.Transformer`.
	"""

	def get_transforms(self):
	"""Transforms required by this class. Override in subclasses."""
	if self.default_transforms != ():
	import warnings
	warnings.warn('TransformSpec: the "default_transforms" attribute '
	'will be removed in Docutils 1.1.\n'
	'Use get_transforms() method instead.',
	DeprecationWarning)
	return list(self.default_transforms)
	return []

	# Deprecated; for compatibility.
	default_transforms = ()

	unknown_reference_resolvers = ()
	"""List of functions to try to resolve unknown references. Unknown
	references have a 'refname' attribute which doesn't correspond to any
	target in the document. Called when the transforms in
	`docutils.transforms.references` are unable to find a correct target. The
	list should contain functions which will try to resolve unknown
	references, with the following signature::

	def reference_resolver(node):
	'''Returns boolean: true if resolved, false if not.'''

	If the function is able to resolve the reference, it should also remove
	the 'refname' attribute and mark the node as resolved::

	del node['refname']
	node.resolved = 1

	Each function must have a "priority" attribute which will affect the order
	the unknown_reference_resolvers are run::

	reference_resolver.priority = 100

	Override in subclasses."""


	class Component(SettingsSpec, TransformSpec):

	"""Base class for Docutils components."""

	component_type = None
	"""Name of the component type ('reader', 'parser', 'writer'). Override in
	subclasses."""

	supported = ()
	"""Names for this component. Override in subclasses."""

	def supports(self, format):
	"""
	Is `format` supported by this component?

	To be used by transforms to ask the dependent component if it supports
	a certain input context or output format.
	"""
	return format in self.supported