==============
libyang-python
==============
Python CFFI bindings to libyang__.
__ https://github.com/CESNET/libyang/
|pypi-project|__ |python-versions|__ |build-status|__ |license|__ |code-style|__
__ https://pypi.org/project/libyang
__ https://github.com/CESNET/libyang-python/actions
__ https://github.com/CESNET/libyang-python/actions
__ https://github.com/CESNET/libyang-python/blob/master/LICENSE
__ https://github.com/psf/black
.. |pypi-project| image:: https://img.shields.io/pypi/v/libyang.svg
.. |python-versions| image:: https://img.shields.io/pypi/pyversions/libyang.svg
.. |build-status| image:: https://github.com/CESNET/libyang-python/workflows/CI/badge.svg
.. |license| image:: https://img.shields.io/github/license/CESNET/libyang-python.svg
.. |code-style| image:: https://img.shields.io/badge/code%20style-black-000000.svg
Installation
============
::
pip install libyang
This assumes ``libyang.so`` is installed in the system and that ``libyang.h`` is
available in the system include dirs.
You need the following system dependencies installed:
- Python development headers
- GCC
- FFI development headers
On a Debian/Ubuntu system::
sudo apt-get install python3-dev gcc python3-cffi
Compatibility
-------------
The current version requires at least C `libyang 2.25`__.
The last version of the bindings that works with C `libyang 1.x`__ is v1.7.0__.
__ https://github.com/CESNET/libyang/commit/d2f1608b348f
__ https://github.com/CESNET/libyang/tree/libyang1
__ https://pypi.org/project/libyang/1.7.0/
Compilation Flags
-----------------
If libyang headers and libraries are installed in a non-standard location, you
can specify them with the ``LIBYANG_HEADERS`` and ``LIBYANG_LIBRARIES``
variables. Additionally, for finer control, you may use ``LIBYANG_EXTRA_CFLAGS``
and ``LIBYANG_EXTRA_LDFLAGS``::
LIBYANG_HEADERS=/home/build/opt/ly/include \
LIBYANG_LIBRARIES=/home/build/opt/ly/lib \
LIBYANG_EXTRA_CFLAGS="-O3" \
LIBYANG_EXTRA_LDFLAGS="-rpath=/opt/ly/lib" \
pip install libyang
Examples
========
Schema Introspection
--------------------
.. code-block:: pycon
>>> import libyang
>>> ctx = libyang.Context('/usr/local/share/yang/modules')
>>> module = ctx.load_module('ietf-system')
>>> print(module)
module: ietf-system
+--rw system
| +--rw contact? string
| +--rw hostname? ietf-inet-types:domain-name
| +--rw location? string
| +--rw clock
| | +--rw (timezone)?
| | +--:(timezone-utc-offset)
| | +--rw timezone-utc-offset? int16
| +--rw dns-resolver
| +--rw search* ietf-inet-types:domain-name
| +--rw server* [name]
| | +--rw name string
| | +--rw (transport)
| | +--:(udp-and-tcp)
| | +--rw udp-and-tcp
| | +--rw address ietf-inet-types:ip-address
| +--rw options
| +--rw timeout? uint8 <5>
| +--rw attempts? uint8 <2>
+--ro system-state
+--ro platform
| +--ro os-name? string
| +--ro os-release? string
| +--ro os-version? string
| +--ro machine? string
+--ro clock
+--ro current-datetime? ietf-yang-types:date-and-time
+--ro boot-datetime? ietf-yang-types:date-and-time
rpcs:
+---x set-current-datetime
| +---- input
| +---w current-datetime ietf-yang-types:date-and-time
+---x system-restart
+---x system-shutdown
>>> xpath = '/ietf-system:system/ietf-system:dns-resolver/ietf-system:server'
>>> dnsserver = next(ctx.find_path(xpath))
>>> dnsserver
<libyang.schema.SList: server [name]>
>>> print(dnsserver.description())
List of the DNS servers that the resolver should query.
When the resolver is invoked by a calling application, it
sends the query to the first name server in this list. If
no response has been received within 'timeout' seconds,
the resolver continues with the next server in the list.
If no response is received from any server, the resolver
continues with the first server again. When the resolver
has traversed the list 'attempts' times without receiving
any response, it gives up and returns an error to the
calling application.
Implementations MAY limit the number of entries in this
list.
>>> dnsserver.ordered()
True
>>> for node in dnsserver:
... print(repr(node))
...
<libyang.schema.SLeaf: name string>
<libyang.schema.SContainer: udp-and-tcp>
>>> ctx.destroy()
>>>
Data Tree
---------
.. code-block:: pycon
>>> import libyang
>>> ctx = libyang.Context()
>>> module = ctx.parse_module_str('''
... module example {
... namespace "urn:example";
... prefix "ex";
... container data {
... list interface {
... key name;
... leaf name {
... type string;
... }
... leaf address {
... type string;
... }
... }
... leaf hostname {
... type string;
... }
... }
... }
... ''')
>>> print(module.print_mem('tree'))
module: example
+--rw data
+--rw interface* [name]
| +--rw name string
| +--rw address? string
+--rw hostname? string
>>> node = module.parse_data_dict({
... 'data': {
... 'hostname': 'foobar',
... 'interface': [
... {'name': 'eth0', 'address': '1.2.3.4/24'},
... {'name': 'lo', 'address': '127.0.0.1'},
... ],
... },
... })
>>> print(node.print_mem('xml', pretty=True))
<data xmlns="urn:example">
<interface>
<name>eth0</name>
<address>1.2.3.4/24</address>
</interface>
<interface>
<name>lo</name>
<address>127.0.0.1</address>
</interface>
<hostname>foobar</hostname>
</data>
>>> node.print_dict()
{'data': {'interface': [{'name': 'eth0', 'address': '1.2.3.4/24'}, {'name':
'lo', 'address': '127.0.0.1'}], 'hostname': 'foobar'}}
>>> node.free()
>>> ctx.destroy()
>>>
See the ``tests`` folder for more examples.
Contributing
============
This is an open source project and all contributions are welcome.
Issues
------
Please create new issues for any bug you discover at
https://github.com/CESNET/libyang-python/issues/new. It is not necessary to file
a bug if you are preparing a patch.
Pull Requests
-------------
Here are the steps for submitting a change in the code base:
#. Fork the repository: https://github.com/CESNET/libyang-python/fork
#. Clone your own fork into your development machine::
git clone https://github.com/<you>/libyang-python
#. Create a new branch named after what your are working on::
git checkout -b my-topic -t origin/master
#. Edit the code and call ``make format`` to ensure your modifications comply
with the `coding style`__.
__ https://black.readthedocs.io/en/stable/the_black_code_style.html
Your contribution must be licensed under the `MIT License`__ . At least one
copyright notice is expected in new files.
__ https://spdx.org/licenses/MIT.html
#. If you are adding a new feature or fixing a bug, please consider adding or
updating unit tests.
#. Before creating commits, run ``make lint`` and ``make tests`` to check if
your changes do not break anything. You can also run ``make`` which will run
both.
#. Once you are happy with your work, you can create a commit (or several
commits). Follow these general rules:
- Address only one issue/topic per commit.
- Describe your changes in imperative mood, e.g. *"make xyzzy do frotz"*
instead of *"[This patch] makes xyzzy do frotz"* or *"[I] changed xyzzy to
do frotz"*, as if you are giving orders to the codebase to change its
behaviour.
- Limit the first line (title) of the commit message to 60 characters.
- Use a short prefix for the commit title for readability with ``git log
--oneline``. Do not use the `fix:` nor `feature:` prefixes. See recent
commits for inspiration.
- Only use lower case letters for the commit title except when quoting
symbols or known acronyms.
- Use the body of the commit message to actually explain what your patch
does and why it is useful. Even if your patch is a one line fix, the
description is not limited in length and may span over multiple
paragraphs. Use proper English syntax, grammar and punctuation.
- If you are fixing an issue, use appropriate ``Closes: <URL>`` or
``Fixes: <URL>`` trailers.
- If you are fixing a regression introduced by another commit, add a
``Fixes: <COMMIT_ID> ("<TITLE>")`` trailer.
- When in doubt, follow the format and layout of the recent existing
commits.
- The following trailers are accepted in commits. If you are using multiple
trailers in a commit, it's preferred to also order them according to this
list.
* ``Closes: <URL>``: close the referenced issue or pull request.
* ``Fixes: <SHA> ("<TITLE>")``: reference the commit that introduced
a regression.
* ``Link: <URL>``: any useful link to provide context for your commit.
* ``Suggested-by``
* ``Requested-by``
* ``Reported-by``
* ``Co-authored-by``
* ``Tested-by``
* ``Reviewed-by``
* ``Acked-by``
* ``Signed-off-by``: Compulsory!
There is a great reference for commit messages in the `Linux kernel
documentation`__.
__ https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes
IMPORTANT: you must sign-off your work using ``git commit --signoff``. Follow
the `Linux kernel developer's certificate of origin`__ for more details. All
contributions are made under the MIT license. If you do not want to disclose
your real name, you may sign-off using a pseudonym. Here is an example::
Signed-off-by: Robin Jarry <robin@jarry.cc>
__ https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin
#. Push your topic branch in your forked repository::
git push origin my-topic
You should get a message from Github explaining how to create a new pull
request.
#. Wait for a reviewer to merge your work. If minor adjustments are requested,
use ``git commit --fixup $sha1`` to make it obvious what commit you are
adjusting. If bigger changes are needed, make them in new separate commits.
Once the reviewer is happy, please use ``git rebase --autosquash`` to amend
the commits with their small fixups (if any), and ``git push --force`` on
your topic branch.
Thank you in advance for your contributions!
Raw data
{
"_id": null,
"home_page": "https://github.com/CESNET/libyang-python",
"name": "libyang",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "libyang, cffi",
"author": "Robin Jarry",
"author_email": "robin@jarry.cc",
"download_url": "https://files.pythonhosted.org/packages/91/2e/ff13ee16c874d232d5d3fdff83f629cbc9ac47f9aaf2b59256b6a1bdbc16/libyang-3.0.1.tar.gz",
"platform": null,
"description": "==============\nlibyang-python\n==============\n\nPython CFFI bindings to libyang__.\n\n__ https://github.com/CESNET/libyang/\n\n|pypi-project|__ |python-versions|__ |build-status|__ |license|__ |code-style|__\n\n__ https://pypi.org/project/libyang\n__ https://github.com/CESNET/libyang-python/actions\n__ https://github.com/CESNET/libyang-python/actions\n__ https://github.com/CESNET/libyang-python/blob/master/LICENSE\n__ https://github.com/psf/black\n\n.. |pypi-project| image:: https://img.shields.io/pypi/v/libyang.svg\n.. |python-versions| image:: https://img.shields.io/pypi/pyversions/libyang.svg\n.. |build-status| image:: https://github.com/CESNET/libyang-python/workflows/CI/badge.svg\n.. |license| image:: https://img.shields.io/github/license/CESNET/libyang-python.svg\n.. |code-style| image:: https://img.shields.io/badge/code%20style-black-000000.svg\n\nInstallation\n============\n\n::\n\n pip install libyang\n\nThis assumes ``libyang.so`` is installed in the system and that ``libyang.h`` is\navailable in the system include dirs.\n\nYou need the following system dependencies installed:\n\n- Python development headers\n- GCC\n- FFI development headers\n\nOn a Debian/Ubuntu system::\n\n sudo apt-get install python3-dev gcc python3-cffi\n\nCompatibility\n-------------\n\nThe current version requires at least C `libyang 2.25`__.\n\nThe last version of the bindings that works with C `libyang 1.x`__ is v1.7.0__.\n\n__ https://github.com/CESNET/libyang/commit/d2f1608b348f\n__ https://github.com/CESNET/libyang/tree/libyang1\n__ https://pypi.org/project/libyang/1.7.0/\n\nCompilation Flags\n-----------------\n\nIf libyang headers and libraries are installed in a non-standard location, you\ncan specify them with the ``LIBYANG_HEADERS`` and ``LIBYANG_LIBRARIES``\nvariables. Additionally, for finer control, you may use ``LIBYANG_EXTRA_CFLAGS``\nand ``LIBYANG_EXTRA_LDFLAGS``::\n\n LIBYANG_HEADERS=/home/build/opt/ly/include \\\n LIBYANG_LIBRARIES=/home/build/opt/ly/lib \\\n LIBYANG_EXTRA_CFLAGS=\"-O3\" \\\n LIBYANG_EXTRA_LDFLAGS=\"-rpath=/opt/ly/lib\" \\\n pip install libyang\n\nExamples\n========\n\nSchema Introspection\n--------------------\n\n.. code-block:: pycon\n\n >>> import libyang\n >>> ctx = libyang.Context('/usr/local/share/yang/modules')\n >>> module = ctx.load_module('ietf-system')\n >>> print(module)\n module: ietf-system\n +--rw system\n | +--rw contact? string\n | +--rw hostname? ietf-inet-types:domain-name\n | +--rw location? string\n | +--rw clock\n | | +--rw (timezone)?\n | | +--:(timezone-utc-offset)\n | | +--rw timezone-utc-offset? int16\n | +--rw dns-resolver\n | +--rw search* ietf-inet-types:domain-name\n | +--rw server* [name]\n | | +--rw name string\n | | +--rw (transport)\n | | +--:(udp-and-tcp)\n | | +--rw udp-and-tcp\n | | +--rw address ietf-inet-types:ip-address\n | +--rw options\n | +--rw timeout? uint8 <5>\n | +--rw attempts? uint8 <2>\n +--ro system-state\n +--ro platform\n | +--ro os-name? string\n | +--ro os-release? string\n | +--ro os-version? string\n | +--ro machine? string\n +--ro clock\n +--ro current-datetime? ietf-yang-types:date-and-time\n +--ro boot-datetime? ietf-yang-types:date-and-time\n\n rpcs:\n +---x set-current-datetime\n | +---- input\n | +---w current-datetime ietf-yang-types:date-and-time\n +---x system-restart\n +---x system-shutdown\n\n >>> xpath = '/ietf-system:system/ietf-system:dns-resolver/ietf-system:server'\n >>> dnsserver = next(ctx.find_path(xpath))\n >>> dnsserver\n <libyang.schema.SList: server [name]>\n >>> print(dnsserver.description())\n List of the DNS servers that the resolver should query.\n\n When the resolver is invoked by a calling application, it\n sends the query to the first name server in this list. If\n no response has been received within 'timeout' seconds,\n the resolver continues with the next server in the list.\n If no response is received from any server, the resolver\n continues with the first server again. When the resolver\n has traversed the list 'attempts' times without receiving\n any response, it gives up and returns an error to the\n calling application.\n\n Implementations MAY limit the number of entries in this\n list.\n >>> dnsserver.ordered()\n True\n >>> for node in dnsserver:\n ... print(repr(node))\n ...\n <libyang.schema.SLeaf: name string>\n <libyang.schema.SContainer: udp-and-tcp>\n >>> ctx.destroy()\n >>>\n\nData Tree\n---------\n\n.. code-block:: pycon\n\n >>> import libyang\n >>> ctx = libyang.Context()\n >>> module = ctx.parse_module_str('''\n ... module example {\n ... namespace \"urn:example\";\n ... prefix \"ex\";\n ... container data {\n ... list interface {\n ... key name;\n ... leaf name {\n ... type string;\n ... }\n ... leaf address {\n ... type string;\n ... }\n ... }\n ... leaf hostname {\n ... type string;\n ... }\n ... }\n ... }\n ... ''')\n >>> print(module.print_mem('tree'))\n module: example\n +--rw data\n +--rw interface* [name]\n | +--rw name string\n | +--rw address? string\n +--rw hostname? string\n >>> node = module.parse_data_dict({\n ... 'data': {\n ... 'hostname': 'foobar',\n ... 'interface': [\n ... {'name': 'eth0', 'address': '1.2.3.4/24'},\n ... {'name': 'lo', 'address': '127.0.0.1'},\n ... ],\n ... },\n ... })\n >>> print(node.print_mem('xml', pretty=True))\n <data xmlns=\"urn:example\">\n <interface>\n <name>eth0</name>\n <address>1.2.3.4/24</address>\n </interface>\n <interface>\n <name>lo</name>\n <address>127.0.0.1</address>\n </interface>\n <hostname>foobar</hostname>\n </data>\n >>> node.print_dict()\n {'data': {'interface': [{'name': 'eth0', 'address': '1.2.3.4/24'}, {'name':\n 'lo', 'address': '127.0.0.1'}], 'hostname': 'foobar'}}\n >>> node.free()\n >>> ctx.destroy()\n >>>\n\nSee the ``tests`` folder for more examples.\n\nContributing\n============\n\nThis is an open source project and all contributions are welcome.\n\nIssues\n------\n\nPlease create new issues for any bug you discover at\nhttps://github.com/CESNET/libyang-python/issues/new. It is not necessary to file\na bug if you are preparing a patch.\n\nPull Requests\n-------------\n\nHere are the steps for submitting a change in the code base:\n\n#. Fork the repository: https://github.com/CESNET/libyang-python/fork\n\n#. Clone your own fork into your development machine::\n\n git clone https://github.com/<you>/libyang-python\n\n#. Create a new branch named after what your are working on::\n\n git checkout -b my-topic -t origin/master\n\n#. Edit the code and call ``make format`` to ensure your modifications comply\n with the `coding style`__.\n\n __ https://black.readthedocs.io/en/stable/the_black_code_style.html\n\n Your contribution must be licensed under the `MIT License`__ . At least one\n copyright notice is expected in new files.\n\n __ https://spdx.org/licenses/MIT.html\n\n#. If you are adding a new feature or fixing a bug, please consider adding or\n updating unit tests.\n\n#. Before creating commits, run ``make lint`` and ``make tests`` to check if\n your changes do not break anything. You can also run ``make`` which will run\n both.\n\n#. Once you are happy with your work, you can create a commit (or several\n commits). Follow these general rules:\n\n - Address only one issue/topic per commit.\n - Describe your changes in imperative mood, e.g. *\"make xyzzy do frotz\"*\n instead of *\"[This patch] makes xyzzy do frotz\"* or *\"[I] changed xyzzy to\n do frotz\"*, as if you are giving orders to the codebase to change its\n behaviour.\n - Limit the first line (title) of the commit message to 60 characters.\n - Use a short prefix for the commit title for readability with ``git log\n --oneline``. Do not use the `fix:` nor `feature:` prefixes. See recent\n commits for inspiration.\n - Only use lower case letters for the commit title except when quoting\n symbols or known acronyms.\n - Use the body of the commit message to actually explain what your patch\n does and why it is useful. Even if your patch is a one line fix, the\n description is not limited in length and may span over multiple\n paragraphs. Use proper English syntax, grammar and punctuation.\n - If you are fixing an issue, use appropriate ``Closes: <URL>`` or\n ``Fixes: <URL>`` trailers.\n - If you are fixing a regression introduced by another commit, add a\n ``Fixes: <COMMIT_ID> (\"<TITLE>\")`` trailer.\n - When in doubt, follow the format and layout of the recent existing\n commits.\n - The following trailers are accepted in commits. If you are using multiple\n trailers in a commit, it's preferred to also order them according to this\n list.\n\n * ``Closes: <URL>``: close the referenced issue or pull request.\n * ``Fixes: <SHA> (\"<TITLE>\")``: reference the commit that introduced\n a regression.\n * ``Link: <URL>``: any useful link to provide context for your commit.\n * ``Suggested-by``\n * ``Requested-by``\n * ``Reported-by``\n * ``Co-authored-by``\n * ``Tested-by``\n * ``Reviewed-by``\n * ``Acked-by``\n * ``Signed-off-by``: Compulsory!\n\n There is a great reference for commit messages in the `Linux kernel\n documentation`__.\n\n __ https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes\n\n IMPORTANT: you must sign-off your work using ``git commit --signoff``. Follow\n the `Linux kernel developer's certificate of origin`__ for more details. All\n contributions are made under the MIT license. If you do not want to disclose\n your real name, you may sign-off using a pseudonym. Here is an example::\n\n Signed-off-by: Robin Jarry <robin@jarry.cc>\n\n __ https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin\n\n#. Push your topic branch in your forked repository::\n\n git push origin my-topic\n\n You should get a message from Github explaining how to create a new pull\n request.\n\n#. Wait for a reviewer to merge your work. If minor adjustments are requested,\n use ``git commit --fixup $sha1`` to make it obvious what commit you are\n adjusting. If bigger changes are needed, make them in new separate commits.\n Once the reviewer is happy, please use ``git rebase --autosquash`` to amend\n the commits with their small fixups (if any), and ``git push --force`` on\n your topic branch.\n\nThank you in advance for your contributions!\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "CFFI bindings to libyang",
"version": "3.0.1",
"project_urls": {
"Homepage": "https://github.com/CESNET/libyang-python"
},
"split_keywords": [
"libyang",
" cffi"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "912eff13ee16c874d232d5d3fdff83f629cbc9ac47f9aaf2b59256b6a1bdbc16",
"md5": "46332891cac852441b523f7e71a507f7",
"sha256": "57f8b234131fb073518313351288194e535d74cc8fdff7f0ff7e31c0ab33e663"
},
"downloads": -1,
"filename": "libyang-3.0.1.tar.gz",
"has_sig": false,
"md5_digest": "46332891cac852441b523f7e71a507f7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 61723,
"upload_time": "2024-04-25T09:44:51",
"upload_time_iso_8601": "2024-04-25T09:44:51.027141Z",
"url": "https://files.pythonhosted.org/packages/91/2e/ff13ee16c874d232d5d3fdff83f629cbc9ac47f9aaf2b59256b6a1bdbc16/libyang-3.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-25 09:44:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "CESNET",
"github_project": "libyang-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "libyang"
}
JSON
