==============
sysrepo-python
==============
Python CFFI bindings to sysrepo_.
.. _libyang: https://github.com/CESNET/libyang
.. _sysrepo: https://github.com/sysrepo/sysrepo
|pypi-project|__ |python-versions|__ |build-status|__ |license|__ |code-style|__
__ https://pypi.org/project/sysrepo
__ https://github.com/sysrepo/sysrepo-python/actions
__ https://github.com/sysrepo/sysrepo-python/actions
__ https://github.com/sysrepo/sysrepo-python/blob/master/LICENSE
__ https://github.com/psf/black
.. |pypi-project| image:: https://img.shields.io/pypi/v/sysrepo.svg
.. |python-versions| image:: https://img.shields.io/pypi/pyversions/sysrepo.svg
.. |build-status| image:: https://github.com/sysrepo/sysrepo-python/workflows/CI/badge.svg
.. |license| image:: https://img.shields.io/github/license/sysrepo/sysrepo-python.svg
.. |code-style| image:: https://img.shields.io/badge/code%20style-black-000000.svg
Installation
============
.. code-block:: bash
pip install sysrepo
This assumes that ``libsysrepo.so`` is installed on the system and that
``sysrepo.h`` is available in the system include dirs.
Since sysrepo_ depends on libyang_, the latter needs to be installed on the
system as well.
You need the following system dependencies installed:
- Python development headers
- GCC
- Python CFFI module
On a Debian/Ubuntu system:
.. code-block:: bash
apt-get install python3-dev gcc python3-cffi
Compatibility
-------------
The current version requires at least C `sysrepo 2.2.0`__.
The last version of the bindings that works with C `sysrepo 1.x`__ is v0.7.0__.
__ https://github.com/sysrepo/sysrepo/commit/8c48a7a50eb2
__ https://github.com/sysrepo/sysrepo/tree/libyang1
__ https://pypi.org/project/sysrepo/0.7.0/
Compilation Flags
-----------------
If sysrepo_ headers and libraries are installed in a non-standard location, you
can export the ``SYSREPO_HEADERS`` and ``SYSREPO_LIBRARIES`` variables.
Additionally, for finer control, you may use ``SYSREPO_EXTRA_CFLAGS`` and
``SYSREPO_EXTRA_LDFLAGS``:
.. code-block:: bash
SYSREPO_HEADERS=/home/build/opt/sr/include \
SYSREPO_LIBRARIES=/home/build/opt/sr/lib \
SYSREPO_EXTRA_CFLAGS="-O3" \
SYSREPO_EXTRA_LDFLAGS="-Wl,-rpath=/opt/sr/lib" \
pip install sysrepo
.. note::
This Python package depends on libyang_ CFFI bindings, if it is not installed
yet and libyang_ headers and libraries are also installed in a non-standard
location, you must export additional variables. See the "Compilation Flags"
section here: https://pypi.org/project/libyang/.
Examples
========
Module Config Replacement
-------------------------
.. code-block:: python
with sysrepo.SysrepoConnection() as conn:
with conn.start_session() as sess:
sess.replace_config({"system": {"hostname": "foobar"}}, "my-module")
Operational Data Request
------------------------
.. code-block:: python
with sysrepo.SysrepoConnection() as conn:
with conn.start_session("operational") as sess:
data = sess.get_data("/my-module:status")
RPC Call
--------
.. code-block:: python
with sysrepo.SysrepoConnection() as conn:
with conn.start_session() as sess:
out = sess.rpc_send("/my-module:my-rpc", {"input-param": 42})
Subscription
------------
.. code-block:: python
with sysrepo.SysrepoConnection() as conn:
with conn.start_session() as sess:
sess.subscribe_module_change("my-module", None, module_change_cb)
sess.subscribe_oper_data_request(
"my-module", "/my-module:status", oper_data_cb)
sess.subscribe_rpc_call("/my-module:my-rpc", my_rpc_cb)
See the ``examples/`` folder for more details.
Differences With ``libsysrepo.so`` C API
========================================
This project has been created with Python users in mind. In order to get a more
pythonic API there are significant divergences with the C API.
Supported Features
------------------
- Connection handling (``sr_connect()``, ``sr_disconnect()``)
- YANG modules management (``sr_install_module()``, ``sr_remove_module()``)
- libyang context retrieval (``sr_get_context()`` wrapped using the `libyang
CFFI bindings`__).
- Session management (``sr_session_start()``, ``sr_session_stop()``,
``sr_session_switch_ds()``, ``sr_session_get_ds()``, ``sr_unsubscribe()``)
- Module change subscriptions (``sr_module_change_subscribe()`` also with
async_ callbacks, ``sr_get_changes_iter()``).
- Operational data subscriptions (``sr_oper_get_items_subscribe()`` also with
async_ callbacks).
- RPC/action call subscriptions (``sr_rpc_subscribe_tree()`` also with async_
callbacks).
- Notifications subscriptions (``sr_event_notif_subscribe_tree()`` also with
async_ callbacks).
- Notification dispatch (``sr_event_notif_send_tree()``).
- RPC/action calling (``sr_rpc_send_tree()``)
- Datastore edition (``sr_set_item_str()``, ``sr_delete_item()``,
``sr_edit_batch()``, ``sr_validate()``, ``sr_apply_changes()``,
``sr_discard_changes()``, ``sr_replace_config()``)
- Get data (``sr_get_data()``, ``sr_get_item()``, ``sr_get_items()``)
- Module locking (``sr_*lock*``)
__ https://pypi.org/project/libyang/
.. _async: https://docs.python.org/3/library/asyncio-task.html#coroutine
Not Yet Supported Features
--------------------------
All other features are not yet supported by sysrepo-python. The most notable
are:
- Module management (``sr_*_module_*``)
Contributing
============
This is an open source project and all contributions are welcome.
See the `CONTRIBUTING.rst`__ file for more details.
__ https://github.com/sysrepo/sysrepo-python/blob/master/CONTRIBUTING.rst
Raw data
{
"_id": null,
"home_page": "https://www.6wind.com/",
"name": "sysrepo",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "sysrepo,libyang,cffi",
"author": "Robin Jarry",
"author_email": "robin.jarry@6wind.com",
"download_url": "https://files.pythonhosted.org/packages/95/04/a61e3a152fdfe02d2f36010b5678d95f04f16ccfaf7704e345828a5fb841/sysrepo-1.7.2.tar.gz",
"platform": null,
"description": "==============\nsysrepo-python\n==============\n\nPython CFFI bindings to sysrepo_.\n\n.. _libyang: https://github.com/CESNET/libyang\n.. _sysrepo: https://github.com/sysrepo/sysrepo\n\n|pypi-project|__ |python-versions|__ |build-status|__ |license|__ |code-style|__\n\n__ https://pypi.org/project/sysrepo\n__ https://github.com/sysrepo/sysrepo-python/actions\n__ https://github.com/sysrepo/sysrepo-python/actions\n__ https://github.com/sysrepo/sysrepo-python/blob/master/LICENSE\n__ https://github.com/psf/black\n\n.. |pypi-project| image:: https://img.shields.io/pypi/v/sysrepo.svg\n.. |python-versions| image:: https://img.shields.io/pypi/pyversions/sysrepo.svg\n.. |build-status| image:: https://github.com/sysrepo/sysrepo-python/workflows/CI/badge.svg\n.. |license| image:: https://img.shields.io/github/license/sysrepo/sysrepo-python.svg\n.. |code-style| image:: https://img.shields.io/badge/code%20style-black-000000.svg\n\nInstallation\n============\n\n.. code-block:: bash\n\n pip install sysrepo\n\nThis assumes that ``libsysrepo.so`` is installed on the system and that\n``sysrepo.h`` is available in the system include dirs.\n\nSince sysrepo_ depends on libyang_, the latter needs to be installed on the\nsystem as well.\n\nYou need the following system dependencies installed:\n\n- Python development headers\n- GCC\n- Python CFFI module\n\nOn a Debian/Ubuntu system:\n\n.. code-block:: bash\n\n apt-get install python3-dev gcc python3-cffi\n\nCompatibility\n-------------\n\nThe current version requires at least C `sysrepo 2.2.0`__.\n\nThe last version of the bindings that works with C `sysrepo 1.x`__ is v0.7.0__.\n\n__ https://github.com/sysrepo/sysrepo/commit/8c48a7a50eb2\n__ https://github.com/sysrepo/sysrepo/tree/libyang1\n__ https://pypi.org/project/sysrepo/0.7.0/\n\nCompilation Flags\n-----------------\n\nIf sysrepo_ headers and libraries are installed in a non-standard location, you\ncan export the ``SYSREPO_HEADERS`` and ``SYSREPO_LIBRARIES`` variables.\nAdditionally, for finer control, you may use ``SYSREPO_EXTRA_CFLAGS`` and\n``SYSREPO_EXTRA_LDFLAGS``:\n\n.. code-block:: bash\n\n SYSREPO_HEADERS=/home/build/opt/sr/include \\\n SYSREPO_LIBRARIES=/home/build/opt/sr/lib \\\n SYSREPO_EXTRA_CFLAGS=\"-O3\" \\\n SYSREPO_EXTRA_LDFLAGS=\"-Wl,-rpath=/opt/sr/lib\" \\\n pip install sysrepo\n\n.. note::\n\n This Python package depends on libyang_ CFFI bindings, if it is not installed\n yet and libyang_ headers and libraries are also installed in a non-standard\n location, you must export additional variables. See the \"Compilation Flags\"\n section here: https://pypi.org/project/libyang/.\n\nExamples\n========\n\nModule Config Replacement\n-------------------------\n\n.. code-block:: python\n\n with sysrepo.SysrepoConnection() as conn:\n with conn.start_session() as sess:\n sess.replace_config({\"system\": {\"hostname\": \"foobar\"}}, \"my-module\")\n\nOperational Data Request\n------------------------\n\n.. code-block:: python\n\n with sysrepo.SysrepoConnection() as conn:\n with conn.start_session(\"operational\") as sess:\n data = sess.get_data(\"/my-module:status\")\n\nRPC Call\n--------\n\n.. code-block:: python\n\n with sysrepo.SysrepoConnection() as conn:\n with conn.start_session() as sess:\n out = sess.rpc_send(\"/my-module:my-rpc\", {\"input-param\": 42})\n\nSubscription\n------------\n\n.. code-block:: python\n\n with sysrepo.SysrepoConnection() as conn:\n with conn.start_session() as sess:\n sess.subscribe_module_change(\"my-module\", None, module_change_cb)\n sess.subscribe_oper_data_request(\n \"my-module\", \"/my-module:status\", oper_data_cb)\n sess.subscribe_rpc_call(\"/my-module:my-rpc\", my_rpc_cb)\n\nSee the ``examples/`` folder for more details.\n\nDifferences With ``libsysrepo.so`` C API\n========================================\n\nThis project has been created with Python users in mind. In order to get a more\npythonic API there are significant divergences with the C API.\n\nSupported Features\n------------------\n\n- Connection handling (``sr_connect()``, ``sr_disconnect()``)\n- YANG modules management (``sr_install_module()``, ``sr_remove_module()``)\n- libyang context retrieval (``sr_get_context()`` wrapped using the `libyang\n CFFI bindings`__).\n- Session management (``sr_session_start()``, ``sr_session_stop()``,\n ``sr_session_switch_ds()``, ``sr_session_get_ds()``, ``sr_unsubscribe()``)\n- Module change subscriptions (``sr_module_change_subscribe()`` also with\n async_ callbacks, ``sr_get_changes_iter()``).\n- Operational data subscriptions (``sr_oper_get_items_subscribe()`` also with\n async_ callbacks).\n- RPC/action call subscriptions (``sr_rpc_subscribe_tree()`` also with async_\n callbacks).\n- Notifications subscriptions (``sr_event_notif_subscribe_tree()`` also with\n async_ callbacks).\n- Notification dispatch (``sr_event_notif_send_tree()``).\n- RPC/action calling (``sr_rpc_send_tree()``)\n- Datastore edition (``sr_set_item_str()``, ``sr_delete_item()``,\n ``sr_edit_batch()``, ``sr_validate()``, ``sr_apply_changes()``,\n ``sr_discard_changes()``, ``sr_replace_config()``)\n- Get data (``sr_get_data()``, ``sr_get_item()``, ``sr_get_items()``)\n- Module locking (``sr_*lock*``)\n\n__ https://pypi.org/project/libyang/\n.. _async: https://docs.python.org/3/library/asyncio-task.html#coroutine\n\nNot Yet Supported Features\n--------------------------\n\nAll other features are not yet supported by sysrepo-python. The most notable\nare:\n\n- Module management (``sr_*_module_*``)\n\nContributing\n============\n\nThis is an open source project and all contributions are welcome.\n\nSee the `CONTRIBUTING.rst`__ file for more details.\n\n__ https://github.com/sysrepo/sysrepo-python/blob/master/CONTRIBUTING.rst\n",
"bugtrack_url": null,
"license": "BSD 3 clause",
"summary": "Sysrepo CFFI bindings",
"version": "1.7.2",
"project_urls": {
"Homepage": "https://www.6wind.com/"
},
"split_keywords": [
"sysrepo",
"libyang",
"cffi"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9504a61e3a152fdfe02d2f36010b5678d95f04f16ccfaf7704e345828a5fb841",
"md5": "4ac80cb8c0c9a3bb7193eaef873eadb3",
"sha256": "fb646ea9a3c7e3c78c5bf1d0d532770aa3ed87c54df9147d36d6ebb1e4d05cdc"
},
"downloads": -1,
"filename": "sysrepo-1.7.2.tar.gz",
"has_sig": false,
"md5_digest": "4ac80cb8c0c9a3bb7193eaef873eadb3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 39893,
"upload_time": "2024-02-01T20:20:59",
"upload_time_iso_8601": "2024-02-01T20:20:59.480741Z",
"url": "https://files.pythonhosted.org/packages/95/04/a61e3a152fdfe02d2f36010b5678d95f04f16ccfaf7704e345828a5fb841/sysrepo-1.7.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-01 20:20:59",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "sysrepo"
}