D7net
Home
Console
Upload
information
Create File
Create Folder
About
Tools
:
/
proc
/
self
/
root
/
opt
/
imunify360
/
venv
/
lib64
/
python3.11
/
site-packages
/
docutils
/
transforms
/
Filename :
__init__.py
back
Copy
# $Id: __init__.py 9320 2023-01-17 15:40:15Z milde $ # Authors: David Goodger <goodger@python.org>; Ueli Schlaepfer # Copyright: This module has been placed in the public domain. """ This package contains modules for standard tree transforms available to Docutils components. Tree transforms serve a variety of purposes: - To tie up certain syntax-specific "loose ends" that remain after the initial parsing of the input plaintext. These transforms are used to supplement a limited syntax. - To automate the internal linking of the document tree (hyperlink references, footnote references, etc.). - To extract useful information from the document tree. These transforms may be used to construct (for example) indexes and tables of contents. Each transform is an optional step that a Docutils component may choose to perform on the parsed document. """ __docformat__ = 'reStructuredText' from docutils import languages, ApplicationError, TransformSpec class TransformError(ApplicationError): pass class Transform: """Docutils transform component abstract base class.""" default_priority = None """Numerical priority of this transform, 0 through 999 (override).""" def __init__(self, document, startnode=None): """ Initial setup for in-place document transforms. """ self.document = document """The document tree to transform.""" self.startnode = startnode """Node from which to begin the transform. For many transforms which apply to the document as a whole, `startnode` is not set (i.e. its value is `None`).""" self.language = languages.get_language( document.settings.language_code, document.reporter) """Language module local to this document.""" def apply(self, **kwargs): """Override to apply the transform to the document tree.""" raise NotImplementedError('subclass must override this method') class Transformer(TransformSpec): """ Store "transforms" and apply them to the document tree. Collect lists of `Transform` instances and "unknown_reference_resolvers" from Docutils components (`TransformSpec` instances). Apply collected "transforms" to the document tree. Also keeps track of components by component type name. https://docutils.sourceforge.io/docs/peps/pep-0258.html#transformer """ def __init__(self, document): self.transforms = [] """List of transforms to apply. Each item is a 4-tuple: ``(priority string, transform class, pending node or None, kwargs)``. """ self.unknown_reference_resolvers = [] """List of hook functions which assist in resolving references.""" self.document = document """The `nodes.document` object this Transformer is attached to.""" self.applied = [] """Transforms already applied, in order.""" self.sorted = False """Boolean: is `self.tranforms` sorted?""" self.components = {} """Mapping of component type name to component object. Set by `self.populate_from_components()`. """ self.serialno = 0 """Internal serial number to keep track of the add order of transforms.""" def add_transform(self, transform_class, priority=None, **kwargs): """ Store a single transform. Use `priority` to override the default. `kwargs` is a dictionary whose contents are passed as keyword arguments to the `apply` method of the transform. This can be used to pass application-specific data to the transform instance. """ if priority is None: priority = transform_class.default_priority priority_string = self.get_priority_string(priority) self.transforms.append( (priority_string, transform_class, None, kwargs)) self.sorted = False def add_transforms(self, transform_list): """Store multiple transforms, with default priorities.""" for transform_class in transform_list: priority_string = self.get_priority_string( transform_class.default_priority) self.transforms.append( (priority_string, transform_class, None, {})) self.sorted = False def add_pending(self, pending, priority=None): """Store a transform with an associated `pending` node.""" transform_class = pending.transform if priority is None: priority = transform_class.default_priority priority_string = self.get_priority_string(priority) self.transforms.append( (priority_string, transform_class, pending, {})) self.sorted = False def get_priority_string(self, priority): """ Return a string, `priority` combined with `self.serialno`. This ensures FIFO order on transforms with identical priority. """ self.serialno += 1 return '%03d-%03d' % (priority, self.serialno) def populate_from_components(self, components): """ Store each component's default transforms and reference resolvers Transforms are stored with default priorities for later sorting. "Unknown reference resolvers" are sorted and stored. Components that don't inherit from `TransformSpec` are ignored. Also, store components by type name in a mapping for later lookup. """ resolvers = [] for component in components: if not isinstance(component, TransformSpec): continue self.add_transforms(component.get_transforms()) self.components[component.component_type] = component resolvers.extend(component.unknown_reference_resolvers) self.sorted = False # sort transform list in self.apply_transforms() # Sort and add helper functions to help resolve unknown references. def keyfun(f): return f.priority resolvers.sort(key=keyfun) self.unknown_reference_resolvers += resolvers def apply_transforms(self): """Apply all of the stored transforms, in priority order.""" self.document.reporter.attach_observer( self.document.note_transform_message) while self.transforms: if not self.sorted: # Unsorted initially, and whenever a transform is added # (transforms may add other transforms). self.transforms.sort(reverse=True) self.sorted = True priority, transform_class, pending, kwargs = self.transforms.pop() transform = transform_class(self.document, startnode=pending) transform.apply(**kwargs) self.applied.append((priority, transform_class, pending, kwargs))