***********
elementpath
***********
.. image:: https://img.shields.io/pypi/v/elementpath.svg
:target: https://pypi.python.org/pypi/elementpath/
.. image:: https://img.shields.io/pypi/pyversions/elementpath.svg
:target: https://pypi.python.org/pypi/elementpath/
.. image:: https://img.shields.io/pypi/implementation/elementpath.svg
:target: https://pypi.python.org/pypi/elementpath/
.. image:: https://img.shields.io/badge/License-MIT-blue.svg
:alt: MIT License
:target: https://lbesson.mit-license.org/
.. image:: https://img.shields.io/pypi/dm/elementpath.svg
:target: https://pypi.python.org/pypi/elementpath/
.. elementpath-introduction
The proposal of this package is to provide XPath 1.0, 2.0, 3.0 and 3.1
selectors for ElementTree XML data structures, both for the standard
ElementTree library and for the `lxml.etree <http://lxml.de>`_ library.
For `lxml.etree <http://lxml.de>`_ this package can be useful for providing
XPath 2.0/3.0/3.1 selectors, because `lxml.etree <http://lxml.de>`_ already
has it's own implementation of XPath 1.0.
Installation and usage
======================
You can install the package with *pip* in a Python 3.8+ environment::
pip install elementpath
For using it import the package and apply the selectors on ElementTree nodes:
.. code-block:: pycon
>>> import elementpath
>>> from xml.etree import ElementTree
>>> root = ElementTree.XML('<A><B1/><B2><C1/><C2/><C3/></B2></A>')
>>> elementpath.select(root, '/A/B2/*')
[<Element 'C1' at ...>, <Element 'C2' at ...>, <Element 'C3' at ...>]
The *select* API provides the standard XPath result format that is a list or an elementary
datatype's value. If you want only to iterate over results you can use the generator function
*iter_select* that accepts the same arguments of *select*.
The selectors API works also using XML data trees based on the `lxml.etree <http://lxml.de>`_
library:
.. code-block:: pycon
>>> import elementpath
>>> import lxml.etree as etree
>>> root = etree.XML('<A><B1/><B2><C1/><C2/><C3/></B2></A>')
>>> elementpath.select(root, '/A/B2/*')
[<Element C1 at ...>, <Element C2 at ...>, <Element C3 at ...>]
When you need to apply the same XPath expression to several XML data you can also use the
*Selector* class, creating an instance and then using it to apply the path on distinct XML
data:
.. code-block:: pycon
>>> import elementpath
>>> import lxml.etree as etree
>>> selector = elementpath.Selector('/A/*/*')
>>> root = etree.XML('<A><B1/><B2><C1/><C2/><C3/></B2></A>')
>>> selector.select(root)
[<Element C1 at ...>, <Element C2 at ...>, <Element C3 at ...>]
>>> root = etree.XML('<A><B1><C0/></B1><B2><C1/><C2/><C3/></B2></A>')
>>> selector.select(root)
[<Element C0 at ...>, <Element C1 at ...>, <Element C2 at ...>, <Element C3 at ...>]
Public API classes and functions are described into the
`elementpath manual on the "Read the Docs" site <http://elementpath.readthedocs.io/en/latest/>`_.
For default the XPath 2.0 is used. If you need XPath 1.0 parser provide the *parser* argument:
.. code-block:: pycon
>>> from elementpath import select, XPath1Parser
>>> from xml.etree import ElementTree
>>> root = ElementTree.XML('<A><B1/><B2><C1/><C2/><C3/></B2></A>')
>>> select(root, '/A/B2/*', parser=XPath1Parser)
[<Element 'C1' at ...>, <Element 'C2' at ...>, <Element 'C3' at ...>]
For XPath 3.0/3.1 import the parser from *elementpath.xpath3* subpackage, that is not loaded
for default:
.. code-block:: pycon
>>> from elementpath.xpath3 import XPath3Parser
>>> select(root, 'math:atan(1.0e0)', parser=XPath3Parser)
0.7853981633974483
Note: *XPath3Parser* is an alias of *XPath31Parser*.
If you need only XPath 3.0 you can also use a more specific subpackage,
avoiding the loading of XPath 3.1 implementation:
.. code-block:: pycon
>>> from elementpath.xpath30 import XPath30Parser
>>> select(root, 'math:atan(1.0e0)', parser=XPath30Parser)
0.7853981633974483
Contributing
============
You can contribute to this package reporting bugs, using the issue tracker or by a pull request.
In case you open an issue please try to provide a test or test data for reproducing the wrong
behaviour. The provided testing code shall be added to the tests of the package.
The XPath parsers are based on an implementation of the Pratt's Top Down Operator Precedence parser.
The implemented parser includes some lookup-ahead features, helpers for registering tokens and for
extending language implementations. Also the token class has been generalized using a `MutableSequence`
as base class. See *tdop.py* for the basic internal classes and *xpath1_parser.py* for extensions
and for a basic usage of the parser.
If you like you can use the basic parser and tokens provided by the *tdop.py* module to
implement other types of parsers (I think it could be also a funny exercise!).
License
=======
This software 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/sissaschool/elementpath",
"name": "elementpath",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "XPath, XPath2, XPath3, XPath31, Pratt-parser, ElementTree, lxml",
"author": "Davide Brunato",
"author_email": "brunato@sissa.it",
"download_url": "https://files.pythonhosted.org/packages/00/85/1c6b109252ae6d295c762f3c9f49409203cbb09ec5d34fb088f90d8dbed7/elementpath-4.6.0.tar.gz",
"platform": null,
"description": "***********\nelementpath\n***********\n\n.. image:: https://img.shields.io/pypi/v/elementpath.svg\n :target: https://pypi.python.org/pypi/elementpath/\n.. image:: https://img.shields.io/pypi/pyversions/elementpath.svg\n :target: https://pypi.python.org/pypi/elementpath/\n.. image:: https://img.shields.io/pypi/implementation/elementpath.svg\n :target: https://pypi.python.org/pypi/elementpath/\n.. image:: https://img.shields.io/badge/License-MIT-blue.svg\n :alt: MIT License\n :target: https://lbesson.mit-license.org/\n.. image:: https://img.shields.io/pypi/dm/elementpath.svg\n :target: https://pypi.python.org/pypi/elementpath/\n\n.. elementpath-introduction\n\nThe proposal of this package is to provide XPath 1.0, 2.0, 3.0 and 3.1\nselectors for ElementTree XML data structures, both for the standard\nElementTree library and for the `lxml.etree <http://lxml.de>`_ library.\n\nFor `lxml.etree <http://lxml.de>`_ this package can be useful for providing\nXPath 2.0/3.0/3.1 selectors, because `lxml.etree <http://lxml.de>`_ already\nhas it's own implementation of XPath 1.0.\n\n\nInstallation and usage\n======================\n\nYou can install the package with *pip* in a Python 3.8+ environment::\n\n pip install elementpath\n\nFor using it import the package and apply the selectors on ElementTree nodes:\n\n.. code-block:: pycon\n\n >>> import elementpath\n >>> from xml.etree import ElementTree\n >>> root = ElementTree.XML('<A><B1/><B2><C1/><C2/><C3/></B2></A>')\n >>> elementpath.select(root, '/A/B2/*')\n [<Element 'C1' at ...>, <Element 'C2' at ...>, <Element 'C3' at ...>]\n\nThe *select* API provides the standard XPath result format that is a list or an elementary\ndatatype's value. If you want only to iterate over results you can use the generator function\n*iter_select* that accepts the same arguments of *select*.\n\nThe selectors API works also using XML data trees based on the `lxml.etree <http://lxml.de>`_\nlibrary:\n\n.. code-block:: pycon\n\n >>> import elementpath\n >>> import lxml.etree as etree\n >>> root = etree.XML('<A><B1/><B2><C1/><C2/><C3/></B2></A>')\n >>> elementpath.select(root, '/A/B2/*')\n [<Element C1 at ...>, <Element C2 at ...>, <Element C3 at ...>]\n\nWhen you need to apply the same XPath expression to several XML data you can also use the\n*Selector* class, creating an instance and then using it to apply the path on distinct XML\ndata:\n\n.. code-block:: pycon\n\n >>> import elementpath\n >>> import lxml.etree as etree\n >>> selector = elementpath.Selector('/A/*/*')\n >>> root = etree.XML('<A><B1/><B2><C1/><C2/><C3/></B2></A>')\n >>> selector.select(root)\n [<Element C1 at ...>, <Element C2 at ...>, <Element C3 at ...>]\n >>> root = etree.XML('<A><B1><C0/></B1><B2><C1/><C2/><C3/></B2></A>')\n >>> selector.select(root)\n [<Element C0 at ...>, <Element C1 at ...>, <Element C2 at ...>, <Element C3 at ...>]\n\nPublic API classes and functions are described into the\n`elementpath manual on the \"Read the Docs\" site <http://elementpath.readthedocs.io/en/latest/>`_.\n\nFor default the XPath 2.0 is used. If you need XPath 1.0 parser provide the *parser* argument:\n\n.. code-block:: pycon\n\n >>> from elementpath import select, XPath1Parser\n >>> from xml.etree import ElementTree\n >>> root = ElementTree.XML('<A><B1/><B2><C1/><C2/><C3/></B2></A>')\n >>> select(root, '/A/B2/*', parser=XPath1Parser)\n [<Element 'C1' at ...>, <Element 'C2' at ...>, <Element 'C3' at ...>]\n\nFor XPath 3.0/3.1 import the parser from *elementpath.xpath3* subpackage, that is not loaded\nfor default:\n\n.. code-block:: pycon\n\n >>> from elementpath.xpath3 import XPath3Parser\n >>> select(root, 'math:atan(1.0e0)', parser=XPath3Parser)\n 0.7853981633974483\n\nNote: *XPath3Parser* is an alias of *XPath31Parser*.\n\nIf you need only XPath 3.0 you can also use a more specific subpackage,\navoiding the loading of XPath 3.1 implementation:\n\n.. code-block:: pycon\n\n >>> from elementpath.xpath30 import XPath30Parser\n >>> select(root, 'math:atan(1.0e0)', parser=XPath30Parser)\n 0.7853981633974483\n\n\nContributing\n============\n\nYou can contribute to this package reporting bugs, using the issue tracker or by a pull request.\nIn case you open an issue please try to provide a test or test data for reproducing the wrong\nbehaviour. The provided testing code shall be added to the tests of the package.\n\nThe XPath parsers are based on an implementation of the Pratt's Top Down Operator Precedence parser.\nThe implemented parser includes some lookup-ahead features, helpers for registering tokens and for\nextending language implementations. Also the token class has been generalized using a `MutableSequence`\nas base class. See *tdop.py* for the basic internal classes and *xpath1_parser.py* for extensions\nand for a basic usage of the parser.\n\nIf you like you can use the basic parser and tokens provided by the *tdop.py* module to\nimplement other types of parsers (I think it could be also a funny exercise!).\n\n\nLicense\n=======\n\nThis software is distributed under the terms of the MIT License.\nSee the file 'LICENSE' in the root directory of the present\ndistribution, or http://opensource.org/licenses/MIT.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "XPath 1.0/2.0/3.0/3.1 parsers and selectors for ElementTree and lxml",
"version": "4.6.0",
"project_urls": {
"Homepage": "https://github.com/sissaschool/elementpath"
},
"split_keywords": [
"xpath",
" xpath2",
" xpath3",
" xpath31",
" pratt-parser",
" elementtree",
" lxml"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d3c3aa6261a4fd79ceded4d0cdc24a3a28635cbd5e750cbdc1b9fe1521da56d2",
"md5": "8c3a1eb5c7d92ade8db44682517b3d94",
"sha256": "e578677f19ccc6ff374c4477c687c547ecbaf7b478d98abb951b7b4b45260a17"
},
"downloads": -1,
"filename": "elementpath-4.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8c3a1eb5c7d92ade8db44682517b3d94",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 239815,
"upload_time": "2024-10-27T21:52:58",
"upload_time_iso_8601": "2024-10-27T21:52:58.886240Z",
"url": "https://files.pythonhosted.org/packages/d3/c3/aa6261a4fd79ceded4d0cdc24a3a28635cbd5e750cbdc1b9fe1521da56d2/elementpath-4.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "00851c6b109252ae6d295c762f3c9f49409203cbb09ec5d34fb088f90d8dbed7",
"md5": "5daa60d0bf6ad2598d2bf5a1b35d6fd0",
"sha256": "ba46bf07f66774927727ade55022b6c435fac06b2523cb3cd7689a1884d33468"
},
"downloads": -1,
"filename": "elementpath-4.6.0.tar.gz",
"has_sig": false,
"md5_digest": "5daa60d0bf6ad2598d2bf5a1b35d6fd0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 355931,
"upload_time": "2024-10-27T21:53:02",
"upload_time_iso_8601": "2024-10-27T21:53:02.187583Z",
"url": "https://files.pythonhosted.org/packages/00/85/1c6b109252ae6d295c762f3c9f49409203cbb09ec5d34fb088f90d8dbed7/elementpath-4.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-27 21:53:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sissaschool",
"github_project": "elementpath",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "elementpath"
}
JSON
