android-notify 1.59.3__py3-none-any.whl → 1.60.0__py3-none-any.whl

venv/Lib/site-packages/docutils/transforms/frontmatter.py

@@ -0,0 +1,548 @@
+# $Id: frontmatter.py 10136 2025-05-20 15:48:27Z milde $
+# Author: David Goodger, Ueli Schlaepfer <goodger@python.org>
+# Copyright: This module has been placed in the public domain.
+
+"""
+Transforms_ related to the front matter of a document or a section
+(information found before the main text):
+
+- `DocTitle`: Used to transform a lone top level section's title to
+  the document title, promote a remaining lone top-level section's
+  title to the document subtitle, and determine the document's title
+  metadata (document['title']) based on the document title and/or the
+  "title" setting.
+
+- `SectionSubTitle`: Used to transform a lone subsection into a
+  subtitle.
+
+- `DocInfo`: Used to transform a bibliographic field list into docinfo
+  elements.
+
+.. _transforms: https://docutils.sourceforge.io/docs/api/transforms.html
+"""
+
+from __future__ import annotations
+
+__docformat__ = 'reStructuredText'
+
+import re
+
+from docutils import nodes, parsers, utils
+from docutils.transforms import TransformError, Transform
+
+
+class TitlePromoter(Transform):
+
+    """
+    Abstract base class for DocTitle and SectionSubTitle transforms.
+    """
+
+    def promote_title(self, node) -> bool:
+        """
+        Transform the following tree::
+
+            <node>
+                <section>
+                    <title>
+                    ...
+
+        into ::
+
+            <node>
+                <title>
+                ...
+
+        `node` is normally a document.
+        """
+        # Type check
+        if not isinstance(node, nodes.Element):
+            raise TypeError('node must be of Element-derived type.')
+
+        # `node` must not have a title yet.
+        assert not (len(node) and isinstance(node[0], nodes.title))
+        section, index = self.candidate_index(node)
+        if index is None:
+            return False
+
+        # Transfer the section's attributes to the node:
+        # NOTE: Change `replace` to False to NOT replace attributes that
+        #       already exist in node with those in section.
+        # NOTE: Remove `and_source` to NOT copy the 'source'
+        #       attribute from section
+        node.update_all_atts_concatenating(section, replace=True,
+                                           and_source=True)
+
+        # setup_child is called automatically for all nodes.
+        node[:] = (section[:1]        # section title
+                   + node[:index]     # everything that was in the
+                                      # node before the section
+                   + section[1:])     # everything that was in the section
+        assert isinstance(node[0], nodes.title)
+        return True
+
+    def promote_subtitle(self, node) -> bool:
+        """
+        Transform the following node tree::
+
+            <node>
+                <title>
+                <section>
+                    <title>
+                    ...
+
+        into ::
+
+            <node>
+                <title>
+                <subtitle>
+                ...
+        """
+        # Type check
+        if not isinstance(node, nodes.Element):
+            raise TypeError('node must be of Element-derived type.')
+
+        subsection, index = self.candidate_index(node)
+        if index is None:
+            return False
+        subtitle = nodes.subtitle()
+
+        # Transfer the subsection's attributes to the new subtitle
+        # NOTE: Change `replace` to False to NOT replace attributes
+        #       that already exist in node with those in section.
+        # NOTE: Remove `and_source` to NOT copy the 'source'
+        #       attribute from section.
+        subtitle.update_all_atts_concatenating(subsection, replace=True,
+                                               and_source=True)
+
+        # Transfer the contents of the subsection's title to the
+        # subtitle:
+        subtitle[:] = subsection[0][:]
+        node[:] = (node[:1]       # title
+                   + [subtitle]
+                   # everything that was before the section:
+                   + node[1:index]
+                   # everything that was in the subsection:
+                   + subsection[1:])
+        return True
+
+    def candidate_index(self, node):
+        """
+        Find and return the promotion candidate and its index.
+
+        Return (None, None) if no valid candidate was found.
+        """
+        index = node.first_child_not_matching_class(
+            nodes.PreBibliographic)
+        if (index is None or len(node) > (index + 1)
+            or not isinstance(node[index], nodes.section)):
+            return None, None
+        else:
+            return node[index], index
+
+
+class DocTitle(TitlePromoter):
+
+    """
+    In reStructuredText_, there is no way to specify a document title
+    and subtitle explicitly. Instead, we can supply the document title
+    (and possibly the subtitle as well) implicitly, and use this
+    two-step transform to "raise" or "promote" the title(s) (and their
+    corresponding section contents) to the document level.
+
+    1. If the document contains a single top-level section as its first
+       element (instances of `nodes.PreBibliographic` are ignored),
+       the top-level section's title becomes the document's title, and
+       the top-level section's contents become the document's immediate
+       contents. The title is also used for the <document> element's
+       "title" attribute default value.
+
+    2. If step 1 successfully determines the document title, we
+       continue by checking for a subtitle.
+
+       If the lone top-level section itself contains a single second-level
+       section as its first "non-PreBibliographic" element, that section's
+       title is promoted to the document's subtitle, and that section's
+       contents become the document's immediate contents.
+
+    Example:
+       Given this input text::
+
+           =================
+            Top-Level Title
+           =================
+
+           Second-Level Title
+           ~~~~~~~~~~~~~~~~~~
+
+           A paragraph.
+
+       After parsing and running the DocTitle transform, the result is::
+
+           <document names="top-level title">
+               <title>
+                   Top-Level Title
+               <subtitle names="second-level title">
+                   Second-Level Title
+               <paragraph>
+                   A paragraph.
+
+       (Note that the implicit hyperlink target generated by the
+       "Second-Level Title" is preserved on the <subtitle> element
+       itself.)
+
+    Any `nodes.PreBibliographic` instances occurring before the
+    document title or subtitle are accumulated and inserted as
+    the first body elements after the title(s).
+
+    .. _reStructuredText: https://docutils.sourceforge.io/rst.html
+    """
+
+    default_priority = 320
+
+    def set_metadata(self) -> None:
+        """
+        Set document['title'] metadata title from the following
+        sources, listed in order of priority:
+
+        * Existing document['title'] attribute.
+        * "title" setting.
+        * Document title node (as promoted by promote_title).
+        """
+        if not self.document.hasattr('title'):
+            if self.document.settings.title is not None:
+                self.document['title'] = self.document.settings.title
+            elif len(self.document) and isinstance(self.document[0],
+                                                   nodes.title):
+                self.document['title'] = self.document[0].astext()
+
+    def apply(self) -> None:
+        if self.document.settings.setdefault('doctitle_xform', True):
+            # promote_(sub)title defined in TitlePromoter base class.
+            if self.promote_title(self.document):
+                # If a title has been promoted, also try to promote a
+                # subtitle.
+                self.promote_subtitle(self.document)
+        # Set document['title'].
+        self.set_metadata()
+
+
+class SectionSubTitle(TitlePromoter):
+
+    """
+    This works like document subtitles, but for sections.  For example, ::
+
+        <section>
+            <title>
+                Title
+            <section>
+                <title>
+                    Subtitle
+                ...
+
+    is transformed into ::
+
+        <section>
+            <title>
+                Title
+            <subtitle>
+                Subtitle
+            ...
+
+    For details refer to the docstring of DocTitle.
+    """
+
+    default_priority = 350
+
+    def apply(self) -> None:
+        if not self.document.settings.setdefault('sectsubtitle_xform', True):
+            return
+        for section in self.document.findall(nodes.section):
+            # On our way through the node tree, we are modifying it
+            # but only the not-yet-visited part, so that the iterator
+            # returned by findall() is not corrupted.
+            self.promote_subtitle(section)
+
+
+class DocInfo(Transform):
+
+    """
+    This transform is specific to the reStructuredText_ markup syntax;
+    see "Bibliographic Fields" in the `reStructuredText Markup
+    Specification`_ for a high-level description. This transform
+    should be run *after* the `DocTitle` transform.
+
+    If the document contains a field list as the first element (instances
+    of `nodes.PreBibliographic` are ignored), registered bibliographic
+    field names are transformed to the corresponding DTD elements,
+    becoming child elements of the <docinfo> element (except for a
+    dedication and/or an abstract, which become <topic> elements after
+    <docinfo>).
+
+    For example, given this document fragment after parsing::
+
+        <document>
+            <title>
+                Document Title
+            <field_list>
+                <field>
+                    <field_name>
+                        Author
+                    <field_body>
+                        <paragraph>
+                            A. Name
+                <field>
+                    <field_name>
+                        Status
+                    <field_body>
+                        <paragraph>
+                            $RCSfile$
+            ...
+
+    After running the bibliographic field list transform, the
+    resulting document tree would look like this::
+
+        <document>
+            <title>
+                Document Title
+            <docinfo>
+                <author>
+                    A. Name
+                <status>
+                    frontmatter.py
+            ...
+
+    The "Status" field contained an expanded RCS keyword, which is
+    normally (but optionally) cleaned up by the transform. The sole
+    contents of the field body must be a paragraph containing an
+    expanded RCS keyword of the form "$keyword: expansion text $". Any
+    RCS keyword can be processed in any bibliographic field. The
+    dollar signs and leading RCS keyword name are removed. Extra
+    processing is done for the following RCS keywords:
+
+    - "RCSfile" expands to the name of the file in the RCS or CVS
+      repository, which is the name of the source file with a ",v"
+      suffix appended. The transform will remove the ",v" suffix.
+
+    - "Date" expands to the format "YYYY/MM/DD hh:mm:ss" (in the UTC
+      time zone). The RCS Keywords transform will extract just the
+      date itself and transform it to an ISO 8601 format date, as in
+      "2000-12-31".
+
+      (Since the source file for this text is itself stored under CVS,
+      we can't show an example of the "Date" RCS keyword because we
+      can't prevent any RCS keywords used in this explanation from
+      being expanded. Only the "RCSfile" keyword is stable; its
+      expansion text changes only if the file name changes.)
+
+    .. _reStructuredText: https://docutils.sourceforge.io/rst.html
+    .. _reStructuredText Markup Specification:
+       https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
+    """
+
+    default_priority = 340
+
+    biblio_nodes = {
+          'author': nodes.author,
+          'authors': nodes.authors,
+          'organization': nodes.organization,
+          'address': nodes.address,
+          'contact': nodes.contact,
+          'version': nodes.version,
+          'revision': nodes.revision,
+          'status': nodes.status,
+          'date': nodes.date,
+          'copyright': nodes.copyright,
+          'dedication': nodes.topic,
+          'abstract': nodes.topic}
+    """Canonical field name (lowcased) to node class name mapping for
+    bibliographic fields (field_list)."""
+
+    def apply(self) -> None:
+        if not self.document.settings.setdefault('docinfo_xform', True):
+            return
+        document = self.document
+        index = document.first_child_not_matching_class(
+              nodes.PreBibliographic)
+        if index is None:
+            return
+        candidate = document[index]
+        if isinstance(candidate, nodes.field_list):
+            biblioindex = document.first_child_not_matching_class(
+                  (nodes.Titular, nodes.decoration, nodes.meta))
+            nodelist = self.extract_bibliographic(candidate)
+            del document[index]         # untransformed field list (candidate)
+            document[biblioindex:biblioindex] = nodelist
+
+    def extract_bibliographic(self, field_list):
+        docinfo = nodes.docinfo()
+        bibliofields = self.language.bibliographic_fields
+        labels = self.language.labels
+        topics = {'dedication': None, 'abstract': None}
+        for field in field_list:
+            try:
+                name = field[0][0].astext()
+                normedname = nodes.fully_normalize_name(name)
+                if not (len(field) == 2 and normedname in bibliofields
+                        and self.check_empty_biblio_field(field, name)):
+                    raise TransformError
+                canonical = bibliofields[normedname]
+                biblioclass = self.biblio_nodes[canonical]
+                if issubclass(biblioclass, nodes.TextElement):
+                    if not self.check_compound_biblio_field(field, name):
+                        raise TransformError
+                    utils.clean_rcs_keywords(
+                          field[1][0], self.rcs_keyword_substitutions)
+                    docinfo.append(biblioclass('', '', *field[1][0]))
+                elif issubclass(biblioclass, nodes.authors):
+                    self.extract_authors(field, name, docinfo)
+                elif issubclass(biblioclass, nodes.topic):
+                    if topics[canonical]:
+                        field[-1] += self.document.reporter.warning(
+                            'There can only be one "%s" field.' % name,
+                            base_node=field)
+                        raise TransformError
+                    title = nodes.title(name, labels[canonical])
+                    title[0].rawsource = labels[canonical]
+                    topics[canonical] = biblioclass(
+                        '', title, classes=[canonical], *field[1].children)
+                else:
+                    docinfo.append(biblioclass('', *field[1].children))
+            except TransformError:
+                if len(field[-1]) == 1 \
+                       and isinstance(field[-1][0], nodes.paragraph):
+                    utils.clean_rcs_keywords(
+                        field[-1][0], self.rcs_keyword_substitutions)
+                # if normedname not in bibliofields:
+                classvalue = nodes.make_id(normedname)
+                if classvalue:
+                    field['classes'].append(classvalue)
+                docinfo.append(field)
+        nodelist = []
+        if len(docinfo):
+            nodelist.append(docinfo)
+        if topics['dedication']:
+            nodelist.append(topics['dedication'])
+        if topics['abstract']:
+            nodelist.append(topics['abstract'])
+        return nodelist
+
+    def check_empty_biblio_field(self, field, name) -> bool:
+        if len(field[-1]) < 1:
+            field[-1] += self.document.reporter.warning(
+                  f'Cannot extract empty bibliographic field "{name}".',
+                  base_node=field)
+            return False
+        return True
+
+    def check_compound_biblio_field(self, field, name) -> bool:
+        # Check that the `field` body contains a single paragraph
+        # (i.e. it must *not* be a compound element).
+        f_body = field[-1]
+        if len(f_body) == 1 and isinstance(f_body[0], nodes.paragraph):
+            return True
+        # Restore single author name with initial (E. Xampl) parsed as
+        # enumerated list
+        # https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#enumerated-lists
+        if (isinstance(f_body[0], nodes.enumerated_list)
+            and '\n' not in f_body.rawsource.strip()):
+            # parse into a dummy document and use created nodes
+            _document = utils.new_document('*DocInfo transform*',
+                                           field.document.settings)
+            parser = parsers.rst.Parser()
+            parser.parse('\\'+f_body.rawsource, _document)
+            if (len(_document.children) == 1
+                and isinstance(_document.children[0], nodes.paragraph)):
+                f_body.children = _document.children
+                return True
+        # Check failed, add a warning
+        content = [f'<{e.tagname}>' for e in f_body.children
+                   if not isinstance(e, nodes.system_message)]
+        if len(content) > 1:
+            content = '[' + ', '.join(content) + ']'
+        else:
+            content = 'a ' + content[0]
+        f_body += self.document.reporter.warning(
+                      f'Bibliographic field "{name}"\nmust contain '
+                      f'a single <paragraph>, not {content}.',
+                      base_node=field)
+        return False
+
+    rcs_keyword_substitutions = [
+        (re.compile(r'\$' r'Date: '  # NoQA: ISC001
+                    r'(\d\d\d\d)[-/](\d\d)[-/](\d\d)[ T][\d:]+'
+                    r'[^$]* \$', re.IGNORECASE), r'\1-\2-\3'),
+        (re.compile(r'\$' r'RCSfile: (.+),v \$',  # NoQA: ISC001
+                    re.IGNORECASE), r'\1'),
+        (re.compile(r'\$[a-zA-Z]+: (.+) \$'), r'\1'),
+    ]
+
+    def extract_authors(self, field, name, docinfo):
+        try:
+            if len(field[1]) == 1:
+                if isinstance(field[1][0], nodes.paragraph):
+                    authors = self.authors_from_one_paragraph(field)
+                elif isinstance(field[1][0], nodes.bullet_list):
+                    authors = self.authors_from_bullet_list(field)
+                else:
+                    raise TransformError
+            else:
+                authors = self.authors_from_paragraphs(field)
+            authornodes = [nodes.author('', '', *author)
+                           for author in authors if author]
+            if len(authornodes) >= 1:
+                docinfo.append(nodes.authors('', *authornodes))
+            else:
+                raise TransformError
+        except TransformError:
+            field[-1] += self.document.reporter.warning(
+                f'Cannot extract "{name}" from bibliographic field:\n'
+                f'Bibliographic field "{name}" must contain either\n'
+                ' a single paragraph (with author names separated by a'
+                ' character from the set '
+                f'"{"".join(self.language.author_separators)}"),\n'
+                ' multiple paragraphs (one per author),\n'
+                ' or a bullet list with one author name per item.\n'
+                'Note: Leading initials can cause (mis)recognizing names '
+                'as enumerated list.',
+                base_node=field)
+            raise
+
+    def authors_from_one_paragraph(self, field):
+        """Return list of Text nodes with author names in `field`.
+
+        Author names must be separated by one of the "autor separators"
+        defined for the document language (default: ";" or ",").
+        """
+        # @@ keep original formatting? (e.g. ``:authors: A. Test, *et-al*``)
+        text = ''.join(str(node)
+                       for node in field[1].findall(nodes.Text))
+        if not text:
+            raise TransformError
+        for authorsep in self.language.author_separators:
+            # don't split at escaped `authorsep`:
+            pattern = '(?<!\x00)%s' % authorsep
+            authornames = re.split(pattern, text)
+            if len(authornames) > 1:
+                break
+        authornames = (name.strip() for name in authornames)
+        return [[nodes.Text(name)] for name in authornames if name]
+
+    def authors_from_bullet_list(self, field):
+        authors = []
+        for item in field[1][0]:
+            if isinstance(item, nodes.comment):
+                continue
+            if len(item) != 1 or not isinstance(item[0], nodes.paragraph):
+                raise TransformError
+            authors.append(item[0].children)
+        if not authors:
+            raise TransformError
+        return authors
+
+    def authors_from_paragraphs(self, field):
+        for item in field[1]:
+            if not isinstance(item, (nodes.paragraph, nodes.comment)):
+                raise TransformError
+        authors = [item.children for item in field[1]
+                   if not isinstance(item, nodes.comment)]
+        return authors

venv/Lib/site-packages/docutils/transforms/misc.py

@@ -0,0 +1,151 @@
+# $Id: misc.py 10166 2025-06-16 09:45:10Z milde $
+# Author: David Goodger <goodger@python.org>
+# Copyright: This module has been placed in the public domain.
+
+"""
+Miscellaneous transforms.
+"""
+
+from __future__ import annotations
+
+__docformat__ = 'reStructuredText'
+
+from docutils import nodes
+from docutils.transforms import Transform
+
+
+class CallBack(Transform):
+
+    """
+    Inserts a callback into a document.  The callback is called when the
+    transform is applied, which is determined by its priority.
+
+    For use with `nodes.pending` elements.  Requires a ``details['callback']``
+    entry, a bound method or function which takes one parameter: the pending
+    node.  Other data can be stored in the ``details`` attribute or in the
+    object hosting the callback method.
+    """
+
+    default_priority = 990
+
+    def apply(self) -> None:
+        pending = self.startnode
+        pending.details['callback'](pending)
+        pending.parent.remove(pending)
+
+
+class ClassAttribute(Transform):
+
+    """
+    Move the "class" attribute specified in the "pending" node into the
+    next visible element.
+    """
+
+    default_priority = 210
+
+    def apply(self) -> None:
+        pending = self.startnode
+        parent = pending.parent
+        child = pending
+        while parent:
+            # Check for appropriate following siblings:
+            for index in range(parent.index(child) + 1, len(parent)):
+                element = parent[index]
+                if (isinstance(element, nodes.Invisible)
+                    or isinstance(element, nodes.system_message)):
+                    continue
+                element['classes'] += pending.details['class']
+                pending.parent.remove(pending)
+                return
+            else:
+                # At end of section or container; apply to sibling
+                child = parent
+                parent = parent.parent
+        error = self.document.reporter.error(
+            'No suitable element following "%s" directive'
+            % pending.details['directive'],
+            nodes.literal_block(pending.rawsource, pending.rawsource),
+            line=pending.line)
+        pending.replace_self(error)
+
+
+class Transitions(Transform):
+
+    """
+    Move transitions at the end of sections up the tree.  Complain
+    on transitions after a title, subtitle, meta, or decoration element,
+    at the beginning or end of the document, and after another transition.
+
+    For example, transform this::
+
+        <section>
+            ...
+            <transition>
+        <section>
+            ...
+
+    into this::
+
+        <section>
+            ...
+        <transition>
+        <section>
+            ...
+    """
+
+    default_priority = 830
+
+    def apply(self) -> None:
+        for node in self.document.findall(nodes.transition):
+            self.visit_transition(node)
+
+    def visit_transition(self, node) -> None:
+        index = node.parent.index(node)
+        previous_sibling = node.previous_sibling()
+        msg = ''
+        if not isinstance(node.parent, (nodes.document, nodes.section)):
+            msg = 'Transition must be child of <document> or <section>.'
+        elif index == 0 or isinstance(previous_sibling, (nodes.title,
+                                                         nodes.subtitle,
+                                                         nodes.meta,
+                                                         nodes.decoration)):
+            msg = 'Document or section may not begin with a transition.'
+        elif isinstance(previous_sibling, nodes.transition):
+            msg = ('At least one body element must separate transitions; '
+                   'adjacent transitions are not allowed.')
+        if msg:
+            warning = self.document.reporter.warning(msg, base_node=node)
+            # Check, if it is valid to insert a body element
+            node.parent[index] = nodes.paragraph()
+            try:
+                node.parent.validate(recursive=False)
+            except nodes.ValidationError:
+                node.parent[index] = node
+            else:
+                node.parent[index] = node
+                node.parent.insert(index+1, warning)
+                index += 1
+        if not isinstance(node.parent, (nodes.document, nodes.section)):
+            return
+        assert index < len(node.parent)
+        if index != len(node.parent) - 1:
+            # No need to move the node.
+            return
+        # Node behind which the transition is to be moved.
+        sibling = node
+        # While sibling is the last node of its parent.
+        while index == len(sibling.parent) - 1:
+            sibling = sibling.parent
+            if sibling.parent is None:  # sibling is the top node (document)
+                # Transition at the end of document.  Do not move the
+                # transition up, and place a warning behind.
+                warning = self.document.reporter.warning(
+                              'Document may not end with a transition.',
+                              base_node=node)
+                node.parent.append(warning)
+                return
+            index = sibling.parent.index(sibling)
+        # Remove the original transition node.
+        node.parent.remove(node)
+        # Insert the transition after the sibling.
+        sibling.parent.insert(index + 1, node)