elementpath 4.1.5__tar.gz → 4.2.0__tar.gz

{elementpath-4.1.5 → elementpath-4.2.0}/CHANGELOG.rst

@@ -2,6 +2,13 @@
 CHANGELOG
 *********
 
+`v4.2.0`_ (2024-02-03)
+======================
+* Drop support for Python 3.7
+* Add *uri* and *fragment* options to dynamic context
+* Make context root node not mandatory (issue #63)
+* Add function objects constructor (issue #70)
+
 `v4.1.5`_ (2023-07-25)
 ======================
 * Fix typed value of ElementNode() if self.elem.text is None
@@ -435,3 +442,4 @@ CHANGELOG
 .. _v4.1.3: https://github.com/sissaschool/elementpath/compare/v4.1.2...v4.1.3
 .. _v4.1.4: https://github.com/sissaschool/elementpath/compare/v4.1.3...v4.1.4
 .. _v4.1.5: https://github.com/sissaschool/elementpath/compare/v4.1.4...v4.1.5
+.. _v4.2.0: https://github.com/sissaschool/elementpath/compare/v4.1.5...v4.2.0

{elementpath-4.1.5 → elementpath-4.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: elementpath
-Version: 4.1.5
+Version: 4.2.0
 Summary: XPath 1.0/2.0/3.0/3.1 parsers and selectors for ElementTree and lxml
 Home-page: https://github.com/sissaschool/elementpath
 Author: Davide Brunato
@@ -16,7 +16,6 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.7
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
@@ -26,9 +25,19 @@ Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Text Processing :: Markup :: XML
-Requires-Python: >=3.7
-Provides-Extra: dev
+Requires-Python: >=3.8
 License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: tox; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: lxml; extra == "dev"
+Requires-Dist: xmlschema>=2.0.0; extra == "dev"
+Requires-Dist: Sphinx; extra == "dev"
+Requires-Dist: memory-profiler; extra == "dev"
+Requires-Dist: memray; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: lxml-stubs; extra == "dev"
 
 ***********
 elementpath

{elementpath-4.1.5 → elementpath-4.2.0}/doc/advanced.rst

@@ -194,10 +194,24 @@ done using a subtree of nodes:
 Both choices can be useful, depends if you need to keep the whole tree or
 to restrict the scope to a subtree.
 
+The context *item* can be set with an XPath node, an atomic value or an XPath function.
+
+.. note::
+    Since release v4.2.0 the *root* is optional. If the argument *root* is absent
+    the argument *item* is mandatory and the dynamic context remain without a root.
+
 
 The root document and the root element
 ======================================
 
+.. warning::
+    The initialization of context root and item is changed in release v4.2.0.
+
+    Since then the provided XML is still considered a document for default, but the
+    item is set with the root instead of `None` and the new attribute *document* is
+    set with a dummy document for handling the document position. The dummy document
+    is not referred by the root element and is discarded from results.
+
 Canonically the dynamic evaluation is performed on an XML document, created
 from an ElementTree instance:
 
@@ -212,18 +226,20 @@ from an ElementTree instance:
     <xml.etree.ElementTree.ElementTree object at ...>
 
 In this case a document node is created at context initialization and the
-context item is not set:
+context item is set to context root:
 
 .. doctest::
 
     >>> context = XPathContext(doc)
     >>> context.root
     DocumentNode(document=<xml.etree.ElementTree.ElementTree object at ...>)
-    >>> context.item is None
+    >>> context.item is context.root
+    True
+    >>> context.document is context.root
     True
 
 Providing a root element the document is not created and the context item is
-set to root element node:
+set to root element node. In this case the context document is a dummy document:
 
 .. doctest::
 
@@ -233,6 +249,10 @@ set to root element node:
     ElementNode(elem=<Element 'root' at ...>)
     >>> context.item is context.root
     True
+    >>> context.document
+    DocumentNode(document=<xml.etree.ElementTree.ElementTree object at ...>)
+    >>> context.root.parent is None
+    True
 
 Exception to this is if XML data root has siblings and if you process
 the data with lxml:
@@ -244,6 +264,22 @@ the data with lxml:
     >>> context = XPathContext(root)
     >>> context.root
     DocumentNode(document=<lxml.etree._ElementTree object at ...>)
-    >>> context.item
-    ElementNode(elem=<Element root at ...>)
+    >>> context.item is context.root
+    True
+    >>> context.document is context.root
+    True
+
+Provide the option *fragment* with value `True` for processing an XML root element
+as a fragment. In this case a dummy document is not created and the context document
+is set to `None`:
 
+.. doctest::
+
+    >>> root = ElementTree.XML('<root><child1/><child2/><child3/></root>')
+    >>> context = XPathContext(root, fragment=True)
+    >>> context.root
+    ElementNode(elem=<Element 'root' at ...>)
+    >>> context.item is context.root
+    True
+    >>> context.document is None
+    True

{elementpath-4.1.5 → elementpath-4.2.0}/doc/conf.py

@@ -25,13 +25,13 @@ sys.path.insert(0, os.path.abspath('..'))
 # -- Project information -----------------------------------------------------
 
 project = 'elementpath'
-copyright = '2018-2023, SISSA (International School for Advanced Studies)'
+copyright = '2018-2024, SISSA (International School for Advanced Studies)'
 author = 'Davide Brunato'
 
 # The short X.Y version
-version = '4.1'
+version = '4.2'
 # The full version, including alpha/beta/rc tags
-release = '4.1.5'
+release = '4.2.0'
 
 # -- General configuration ---------------------------------------------------
 

elementpath-4.2.0/doc/requirements.txt

@@ -0,0 +1,2 @@
+Sphinx==7.2.6
+readthedocs-sphinx-search==0.3.2

{elementpath-4.1.5 → elementpath-4.2.0}/elementpath/__init__.py

@@ -7,10 +7,10 @@
 #
 # @author Davide Brunato <brunato@sissa.it>
 #
-__version__ = '4.1.5'
+__version__ = '4.2.0'
 __author__ = "Davide Brunato"
 __contact__ = "brunato@sissa.it"
-__copyright__ = "Copyright 2018-2023, SISSA"
+__copyright__ = "Copyright 2018-2024, SISSA"
 __license__ = "MIT"
 __status__ = "Production/Stable"
 

{elementpath-4.1.5 → elementpath-4.2.0}/elementpath/compare.py

@@ -308,11 +308,11 @@ def deep_compare(obj1: Any,
 
                     elif isinstance(value1, float):
                         if math.isnan(value1):
-                            if not math.isnan(value2):  # type: ignore[arg-type]
+                            if not math.isnan(value2):
                                 return -1
                         elif math.isinf(value1):
                             if value1 != value2:
-                                return -1 if value1 < value2 else 1  # type: ignore[operator]
+                                return -1 if value1 < value2 else 1
                         elif isinstance(value2, Decimal):
                             if value1 != float(value2):
                                 return -1 if value1 < float(value2) else 1
@@ -326,7 +326,7 @@ def deep_compare(obj1: Any,
                             return -1
                         elif math.isinf(value2):
                             if value1 != value2:
-                                return -1 if value1 < value2 else 1  # type: ignore[operator]
+                                return -1 if value1 < value2 else 1
                         elif isinstance(value1, Decimal):
                             if value2 != float(value1):
                                 return -1 if float(value1) < value2 else 1
@@ -341,7 +341,7 @@ def deep_compare(obj1: Any,
                         if result:
                             return result
                     elif value1 != value2:
-                        return -1 if value1 < value2 else 1  # type: ignore[operator]
+                        return -1 if value1 < value2 else 1
 
                 except TypeError as err:
                     raise xpath_error('XPTY0004', message_or_error=err, token=token)

{elementpath-4.1.5 → elementpath-4.2.0}/elementpath/datatypes/atomic_types.py

@@ -68,7 +68,7 @@ class AtomicTypeMeta(ABCMeta):
 
         return cls
 
-    def validate(cls, value: object) -> None:
+    def validate(cls: Type[Any], value: object) -> None:
         if isinstance(value, cls):
             return
         elif isinstance(value, str):
@@ -77,7 +77,7 @@ class AtomicTypeMeta(ABCMeta):
         else:
             raise cls.invalid_type(value)
 
-    def is_valid(cls, value: object) -> bool:
+    def is_valid(cls: Type[Any], value: object) -> bool:
         try:
             cls.validate(value)
         except (TypeError, ValueError):
@@ -85,12 +85,12 @@ class AtomicTypeMeta(ABCMeta):
         else:
             return True
 
-    def invalid_type(cls, value: object) -> TypeError:
+    def invalid_type(cls: Type[Any], value: object) -> TypeError:
         if cls.name:
             return TypeError('invalid type {!r} for xs:{}'.format(type(value), cls.name))
         return TypeError('invalid type {!r} for {!r}'.format(type(value), cls))
 
-    def invalid_value(cls, value: object) -> ValueError:
+    def invalid_value(cls: Type[Any], value: object) -> ValueError:
         if cls.name:
             return ValueError('invalid value {!r} for xs:{}'.format(value, cls.name))
         return ValueError('invalid value {!r} for {!r}'.format(value, cls))

{elementpath-4.1.5 → elementpath-4.2.0}/elementpath/helpers.py

@@ -12,6 +12,7 @@ import math
 from calendar import isleap, leapdays
 from decimal import Decimal
 from operator import attrgetter
+from urllib.parse import urlsplit
 from typing import Any, Iterator, List, Match, Optional, Union, SupportsFloat
 
 ###
@@ -79,7 +80,7 @@ def adjust_day(year: int, month: int, day: int) -> int:
 
 def days_from_common_era(year: int) -> int:
     """
-    Returns the number of days from from 0001-01-01 to the provided year. For a
+    Returns the number of days from 0001-01-01 to the provided year. For a
     common era year the days are counted until the last day of December, for a
     BCE year the days are counted down from the end to the 1st of January.
     """
@@ -103,7 +104,7 @@ def months2days(year: int, month: int, months_delta: int) -> int:
     relative to the year and the month passed as arguments.
 
     :param year: the reference start year, a negative or zero value means a BCE year \
-    (0 is 1 BCE, -1 is 2 BCE, -2 is 3 BCE, etc).
+    (0 is 1 BCE, -1 is 2 BCE, -2 is 3 BCE, etc.).
     :param month: the starting month (1-12).
     :param months_delta: the number of months, if negative count backwards.
     """
@@ -278,3 +279,14 @@ def split_function_test(function_test: str) -> List[str]:
         sequence_types = [parts[2]]
 
     return sequence_types
+
+
+def is_absolute_uri(uri: str) -> bool:
+    try:
+        parts = urlsplit(uri.strip())
+    except ValueError:
+        return False
+    else:
+        return parts.scheme == 'urn' or \
+            parts.scheme != '' and parts.netloc != '' or \
+            parts.path.startswith('/')

elementpath-4.2.0/elementpath/protocols.py

@@ -0,0 +1,178 @@
+#
+# Copyright (c), 2021, SISSA (International School for Advanced Studies).
+# All rights reserved.
+# This file is distributed under the terms of the MIT License.
+# See the file 'LICENSE' in the root directory of the present
+# distribution, or http://opensource.org/licenses/MIT.
+#
+# @author Davide Brunato <brunato@sissa.it>
+#
+"""
+Define type hints protocols for XPath related objects.
+"""
+from typing import overload, Any, Dict, Iterator, Iterable, List, Literal, \
+    Optional, Protocol, Sized, Hashable, Union, TypeVar, runtime_checkable
+
+_T = TypeVar("_T")
+
+
+@runtime_checkable
+class ElementProtocol(Iterable['ElementProtocol'], Sized, Hashable, Protocol):
+    def find(
+        self, path: str, namespaces: Optional[Dict[str, str]] = ...
+    ) -> Optional['ElementProtocol']: ...
+    def iter(self, tag: Optional[str] = ...) -> Iterator['ElementProtocol']: ...
+    @overload
+    def get(self, key: str, default: None = ...) -> Optional[str]: ...
+    # noinspection PyOverloads
+    @overload
+    def get(self, key: str, default: _T) -> Union[str, _T]: ...
+    tag: str
+    attrib: Dict[str, Any]
+    text: Optional[str]
+    tail: Optional[str]
+
+
+@runtime_checkable
+class LxmlElementProtocol(ElementProtocol, Protocol):
+    def getroottree(self) -> 'DocumentProtocol': ...
+    def getnext(self) -> Optional['LxmlElementProtocol']: ...
+    def getparent(self) -> Optional['LxmlElementProtocol']: ...
+    def getprevious(self) -> Optional['LxmlElementProtocol']: ...
+    def itersiblings(self, tag: Optional[str] = ..., preceding: bool = False,
+                     *tags: str) -> Iterable['LxmlElementProtocol']: ...
+    nsmap: Dict[Optional[str], str]
+
+
+@runtime_checkable
+class DocumentProtocol(Iterable[ElementProtocol], Hashable, Protocol):
+    def getroot(self) -> Optional[ElementProtocol]: ...
+    def parse(self, source: Any, *args: Any, **kwargs: Any) -> 'DocumentProtocol': ...
+    def iter(self, tag: Optional[str] = ...) -> Iterator[ElementProtocol]: ...
+
+
+@runtime_checkable
+class XsdValidatorProtocol(Protocol):
+    def is_matching(self, name: Optional[str],
+                    default_namespace: Optional[str] = None) -> bool: ...
+    xsd_version: Literal['1.0', '1.1']
+    name: Optional[str]
+    maps: 'GlobalMapsProtocol'
+
+
+@runtime_checkable
+class XsdSchemaProtocol(XsdValidatorProtocol, ElementProtocol, Protocol):
+    tag: Literal['{http://www.w3.org/2001/XMLSchema}schema']
+    attrib: Dict[str, 'XsdAttributeProtocol']
+    text: None
+
+
+XMLSchemaProtocol = XsdSchemaProtocol  # for backward compatibility
+
+
+@runtime_checkable
+class XsdComponentProtocol(XsdValidatorProtocol, Protocol):
+    parent: Optional['XsdComponentProtocol']
+
+
+@runtime_checkable
+class XsdTypeProtocol(XsdComponentProtocol, Protocol):
+    def is_simple(self) -> bool:
+        """Returns `True` if it's a simpleType instance, `False` if it's a complexType."""
+        ...
+
+    def is_empty(self) -> bool:
+        """
+        Returns `True` if it's a simpleType instance or a complexType with empty content,
+        `False` otherwise.
+        """
+        ...
+
+    def has_simple_content(self) -> bool:
+        """
+        Returns `True` if it's a simpleType instance or a complexType with simple content,
+        `False` otherwise.
+        """
+        ...
+
+    def has_mixed_content(self) -> bool:
+        """
+        Returns `True` if it's a complexType with mixed content, `False` otherwise.
+        """
+        ...
+
+    def is_element_only(self) -> bool:
+        """
+        Returns `True` if it's a complexType with element-only content, `False` otherwise.
+        """
+        ...
+
+    def is_key(self) -> bool:
+        """Returns `True` if it's a simpleType derived from xs:ID, `False` otherwise."""
+        ...
+
+    def is_qname(self) -> bool:
+        """Returns `True` if it's a simpleType derived from xs:QName, `False` otherwise."""
+        ...
+
+    def is_notation(self) -> bool:
+        """Returns `True` if it's a simpleType derived from xs:NOTATION, `False` otherwise."""
+        ...
+
+    def is_valid(self, obj: Any, *args: Any, **kwargs: Any) -> bool:
+        """
+        Validates an XML object node using the XSD type. The argument *obj* is an element
+        for complex type nodes or a text value for simple type nodes. Returns `True` if
+        the argument is valid, `False` otherwise.
+        """
+        ...
+
+    def validate(self, obj: Any, *args: Any, **kwargs: Any) -> None:
+        """
+        Validates an XML object node using the XSD type. The argument *obj* is an element
+        for complex type nodes or a text value for simple type nodes. Raises a `ValueError`
+        compatible exception (a `ValueError` or a subclass of it) if the argument is not valid.
+        """
+        ...
+
+    def decode(self, obj: Any, *args: Any, **kwargs: Any) -> Any:
+        """
+        Decodes an XML object node using the XSD type. The argument *obj* is an element
+        for complex type nodes or a text value for simple type nodes. Raises a `ValueError`
+        or a `TypeError` compatible exception if the argument it's not valid.
+        """
+        ...
+
+    root_type: 'XsdTypeProtocol'
+    """
+    The type at base of the definition of the XSD type. For a special type is the type
+    itself. For an atomic type is the primitive type. For a list is the primitive type
+    of the item. For a union is the base union type. For a complex type is xs:anyType.
+    """
+
+
+@runtime_checkable
+class XsdAttributeProtocol(XsdComponentProtocol, Protocol):
+    type: Optional[XsdTypeProtocol]
+    ref: Optional['XsdAttributeProtocol']
+
+
+@runtime_checkable
+class XsdElementProtocol(XsdComponentProtocol, ElementProtocol, Protocol):
+    type: Optional[XsdTypeProtocol]
+    ref: Optional['XsdElementProtocol']
+    attrib: Dict[str, XsdAttributeProtocol]
+    text: None
+
+
+class GlobalMapsProtocol(Protocol):
+    types: Dict[str, XsdTypeProtocol]
+    attributes: Dict[str, XsdAttributeProtocol]
+    elements: Dict[str, XsdElementProtocol]
+    substitution_groups: Dict[str, List[XsdElementProtocol]]
+
+
+__all__ = ['ElementProtocol', 'LxmlElementProtocol', 'DocumentProtocol',
+           'XsdValidatorProtocol', 'XsdSchemaProtocol', 'XsdComponentProtocol',
+           'XsdTypeProtocol', 'XsdElementProtocol', 'XsdAttributeProtocol',
+           'GlobalMapsProtocol', 'XMLSchemaProtocol']

{elementpath-4.1.5 → elementpath-4.2.0}/elementpath/tdop.py

@@ -398,7 +398,7 @@ class ParserMeta(ABCMeta):
     literals_pattern: Pattern[str]
     name_pattern: Pattern[str]
     tokenizer: Optional[Pattern[str]]
-    symbol_table: Dict[str, Token[Any]]
+    symbol_table: MutableMapping[str, Type[Any]]
 
     def __new__(mcs, name: str, bases: Tuple[Type[Any], ...], namespace: Dict[str, Any]) \
             -> 'ParserMeta':
@@ -437,14 +437,12 @@ class Parser(Generic[TK_co], metaclass=ParserMeta):
     Parser class for implementing a Top-Down Operator Precedence parser.
 
     :cvar symbol_table: a dictionary that stores the token classes defined for the language.
-    :type symbol_table: dict
     :cvar token_base_class: the base class for creating language's token classes.
-    :type token_base_class: Token
     :cvar tokenizer: the language tokenizer compiled regexp.
     """
     token_base_class = Token
     tokenizer: Optional[Pattern[str]] = None
-    symbol_table: MutableMapping[str, Type[TK_co]] = {}
+    symbol_table: Dict[str, Type[TK_co]] = {}
 
     _start_token: TK_co
     source: str
@@ -667,6 +665,8 @@ class Parser(Generic[TK_co], metaclass=ParserMeta):
         :param kwargs: Optional attributes/methods for the token class.
         :return: A token class.
         """
+        token_class: Type[TK_co]
+
         if isinstance(symbol, str):
             if ' ' in symbol:
                 raise ValueError("%r: a symbol can't contain whitespaces" % symbol)