| Name | pyroute2 JSON |
| Version |
0.9.4
JSON |
| download |
| home_page | None |
| Summary | Python Netlink library |
| upload_time | 2025-07-29 14:35:27 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
Pyroute2
========
Pyroute2 is a pure Python networking framework. The core requires only Python
stdlib, no 3rd party libraries. The library was started as an RTNL protocol
implementation, so the name is **pyroute2**, but now it supports several
protocols, including non-netlink. Here are some supported netlink families
and protocols:
* **dhcp** --- dynamic host configuration protocol for IPv4
* **9p2000** --- Plan9 file system protocol
Netlink:
* **rtnl**, network settings --- addresses, routes, traffic controls
* **nfnetlink** --- netfilter API
* **ipq** --- simplest userspace packet filtering, iptables QUEUE target
* **devlink** --- manage and monitor devlink-enabled hardware
* **generic** --- generic netlink families
* **uevent** --- same uevent messages as in udev
Netfilter API:
* **ipset** --- IP sets
* **nftables** --- packet filtering
* **nfct** --- connection tracking
Generic netlink:
* **ethtool** --- low-level network interface setup
* **wireguard** --- VPN setup
* **nl80211** --- wireless functions API (basic support)
* **taskstats** --- extended process statistics
* **acpi_events** --- ACPI events monitoring
* **thermal_events** --- thermal events monitoring
* **VFS_DQUOT** --- disk quota events monitoring
On the low level the library provides socket objects with an
extended API. The additional functionality aims to:
* Help to open/bind netlink sockets
* Discover generic netlink protocols and multicast groups
* Construct, encode and decode netlink and PF_ROUTE messages
Supported systems
-----------------
Pyroute2 runs natively on Linux and emulates some limited subset
of RTNL netlink API on BSD systems on top of PF_ROUTE notifications
and standard system tools.
Other platforms are not supported.
IPRoute -- synchronous RTNL API
-------------------------------
Low-level **IPRoute** utility --- Linux network configuration, this
class is almost a 1-to-1 RTNL mapping. There are no implicit
interface lookups and so on.
Get notifications about network settings changes:
.. code-block:: python
from pyroute2 import IPRoute
with IPRoute() as ipr:
ipr.bind() # <--- start listening for RTNL broadcasts
for message in ipr.get(): # receive the broadcasts
print(message)
More examples:
.. code-block:: python
from socket import AF_INET
from pyroute2 import IPRoute
# get access to the netlink socket
ipr = IPRoute()
# no monitoring here -- thus no bind()
# print interfaces
for link in ipr.get_links():
print(link)
# create VETH pair and move v0p1 to netns 'test'
ipr.link('add', ifname='v0p0', peer='v0p1', kind='veth')
# wait for the devices:
peer, veth = ipr.poll(
ipr.link, 'dump', timeout=5, ifname=lambda x: x in ('v0p0', 'v0p1')
)
ipr.link('set', index=peer['index'], net_ns_fd='test')
# bring v0p0 up and add an address
ipr.link('set', index=veth['index'], state='up')
ipr.addr('add', index=veth['index'], address='10.0.0.1', prefixlen=24)
# release Netlink socket
ip.close()
AsyncIPRoute -- asynchronous RTNL API
-------------------------------------
While `IPRoute` provides a synchronous RTNL API, it is actually build
around the asyncio-based core.
The same example as above can look like that:
.. code-block:: python
import asyncio
from pyroute2 import AsyncIPRoute
async def main():
# get access to the netlink socket
ipr = AsyncIPRoute()
# print interfaces
async for link in await ipr.get_links():
print(link)
# create VETH pair and move v0p1 to netns 'test'
await ipr.link('add', ifname='v0p0', peer='v0p1', kind='veth')
# wait for the devices:
peer, veth = await ipr.poll(
ipr.link, 'dump', timeout=5, ifname=lambda x: x in ('v0p0', 'v0p1')
)
await ipr.link('set', index=peer['index'], net_ns_fd='test')
...
ipr.close()
asyncio.run(main())
Please notice that `.close()` is synchronous in any case.
Network namespace management
----------------------------
.. code-block:: python
from pyroute2 import netns
# create netns
netns.create('test')
# list
print(netns.listnetns())
# remove netns
netns.remove('test')
Create **veth** interfaces pair and move to **netns**:
.. code-block:: python
from pyroute2 import IPRoute
with IPRoute() as ipr:
# create interface pair
ipr.link('add', ifname='v0p0', kind='veth', peer='v0p1')
# wait for the peer
(peer,) = ipr.poll(ipr.link, 'dump', timeout=5, ifname='v0p1')
# move the peer to the 'test' netns:
ipr.link('set', index=peer['index'], net_ns_fd='test')
List interfaces in some **netns**:
.. code-block:: python
from pyroute2 import IPRoute
with IPRoute(netns='test') as ipr:
for link in ipr.get_links():
print(link)
More details and samples see in the documentation.
NDB -- high level RTNL API
--------------------------
Key features:
* Data integrity
* Transactions with commit/rollback changes
* State synchronization
* Multiple sources, including netns and remote systems
A "Hello world" example:
.. code-block:: python
from pyroute2 import NDB
with NDB() as ndb:
with ndb.interfaces['eth0'] as eth0:
# set one parameter
eth0.set(state='down')
eth0.commit() # make sure that the interface is down
# or multiple parameters at once
eth0.set(ifname='hello_world!', state='up')
eth0.commit() # rename, bring up and wait for success
# --> <-- here you can be sure that the interface is up & renamed
Installation
------------
Using pypi:
.. code-block:: bash
pip install pyroute2
Using git:
.. code-block:: bash
pip install git+https://github.com/svinota/pyroute2.git
Using source, requires make and nox
.. code-block:: bash
git clone https://github.com/svinota/pyroute2.git
cd pyroute2
make install
Requirements
------------
Python >= 3.9
Links
-----
* home: https://pyroute2.org/
* source: https://github.com/svinota/pyroute2
* bugs: https://github.com/svinota/pyroute2/issues
* pypi: https://pypi.python.org/pypi/pyroute2
* docs: http://docs.pyroute2.org/
Raw data
{
"_id": null,
"home_page": null,
"name": "pyroute2",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Peter Saveliev <peter@svinota.eu>",
"download_url": "https://files.pythonhosted.org/packages/b0/5e/fc64e211cce0078555c6db98aaf14348aed527565f3c4876913a290a5b2c/pyroute2-0.9.4.tar.gz",
"platform": null,
"description": "Pyroute2\n========\n\nPyroute2 is a pure Python networking framework. The core requires only Python\nstdlib, no 3rd party libraries. The library was started as an RTNL protocol\nimplementation, so the name is **pyroute2**, but now it supports several\nprotocols, including non-netlink. Here are some supported netlink families\nand protocols:\n\n* **dhcp** --- dynamic host configuration protocol for IPv4\n* **9p2000** --- Plan9 file system protocol\n\nNetlink:\n\n* **rtnl**, network settings --- addresses, routes, traffic controls\n* **nfnetlink** --- netfilter API\n* **ipq** --- simplest userspace packet filtering, iptables QUEUE target\n* **devlink** --- manage and monitor devlink-enabled hardware\n* **generic** --- generic netlink families\n* **uevent** --- same uevent messages as in udev\n\nNetfilter API:\n\n* **ipset** --- IP sets\n* **nftables** --- packet filtering\n* **nfct** --- connection tracking\n\nGeneric netlink:\n\n* **ethtool** --- low-level network interface setup\n* **wireguard** --- VPN setup\n* **nl80211** --- wireless functions API (basic support)\n* **taskstats** --- extended process statistics\n* **acpi_events** --- ACPI events monitoring\n* **thermal_events** --- thermal events monitoring\n* **VFS_DQUOT** --- disk quota events monitoring\n\nOn the low level the library provides socket objects with an\nextended API. The additional functionality aims to:\n\n* Help to open/bind netlink sockets\n* Discover generic netlink protocols and multicast groups\n* Construct, encode and decode netlink and PF_ROUTE messages\n\nSupported systems\n-----------------\n\nPyroute2 runs natively on Linux and emulates some limited subset\nof RTNL netlink API on BSD systems on top of PF_ROUTE notifications\nand standard system tools.\n\nOther platforms are not supported.\n\nIPRoute -- synchronous RTNL API\n-------------------------------\n\nLow-level **IPRoute** utility --- Linux network configuration, this\nclass is almost a 1-to-1 RTNL mapping. There are no implicit\ninterface lookups and so on.\n\nGet notifications about network settings changes:\n\n.. code-block:: python\n\n from pyroute2 import IPRoute\n\n with IPRoute() as ipr:\n ipr.bind() # <--- start listening for RTNL broadcasts\n for message in ipr.get(): # receive the broadcasts\n print(message)\n\nMore examples:\n\n.. code-block:: python\n\n from socket import AF_INET\n from pyroute2 import IPRoute\n\n # get access to the netlink socket\n ipr = IPRoute()\n # no monitoring here -- thus no bind()\n\n # print interfaces\n for link in ipr.get_links():\n print(link)\n\n # create VETH pair and move v0p1 to netns 'test'\n ipr.link('add', ifname='v0p0', peer='v0p1', kind='veth')\n # wait for the devices:\n peer, veth = ipr.poll(\n ipr.link, 'dump', timeout=5, ifname=lambda x: x in ('v0p0', 'v0p1')\n )\n ipr.link('set', index=peer['index'], net_ns_fd='test')\n\n # bring v0p0 up and add an address\n ipr.link('set', index=veth['index'], state='up')\n ipr.addr('add', index=veth['index'], address='10.0.0.1', prefixlen=24)\n\n # release Netlink socket\n ip.close()\n\nAsyncIPRoute -- asynchronous RTNL API\n-------------------------------------\n\nWhile `IPRoute` provides a synchronous RTNL API, it is actually build\naround the asyncio-based core.\n\nThe same example as above can look like that:\n\n.. code-block:: python\n\n import asyncio\n\n from pyroute2 import AsyncIPRoute\n\n async def main():\n # get access to the netlink socket\n ipr = AsyncIPRoute()\n\n # print interfaces\n async for link in await ipr.get_links():\n print(link)\n\n # create VETH pair and move v0p1 to netns 'test'\n await ipr.link('add', ifname='v0p0', peer='v0p1', kind='veth')\n\n # wait for the devices:\n peer, veth = await ipr.poll(\n ipr.link, 'dump', timeout=5, ifname=lambda x: x in ('v0p0', 'v0p1')\n )\n await ipr.link('set', index=peer['index'], net_ns_fd='test')\n ...\n ipr.close()\n\n asyncio.run(main())\n\nPlease notice that `.close()` is synchronous in any case.\n\nNetwork namespace management\n----------------------------\n\n.. code-block:: python\n\n from pyroute2 import netns\n # create netns\n netns.create('test')\n # list\n print(netns.listnetns())\n # remove netns\n netns.remove('test')\n\nCreate **veth** interfaces pair and move to **netns**:\n\n.. code-block:: python\n\n from pyroute2 import IPRoute\n\n with IPRoute() as ipr:\n\n # create interface pair\n ipr.link('add', ifname='v0p0', kind='veth', peer='v0p1')\n\n # wait for the peer\n (peer,) = ipr.poll(ipr.link, 'dump', timeout=5, ifname='v0p1')\n\n # move the peer to the 'test' netns:\n ipr.link('set', index=peer['index'], net_ns_fd='test')\n\nList interfaces in some **netns**:\n\n.. code-block:: python\n\n from pyroute2 import IPRoute\n\n with IPRoute(netns='test') as ipr:\n for link in ipr.get_links():\n print(link)\n\nMore details and samples see in the documentation.\n\nNDB -- high level RTNL API\n--------------------------\n\nKey features:\n\n* Data integrity\n* Transactions with commit/rollback changes\n* State synchronization\n* Multiple sources, including netns and remote systems\n\nA \"Hello world\" example:\n\n.. code-block:: python\n\n from pyroute2 import NDB\n\n with NDB() as ndb:\n with ndb.interfaces['eth0'] as eth0:\n # set one parameter\n eth0.set(state='down')\n eth0.commit() # make sure that the interface is down\n # or multiple parameters at once\n eth0.set(ifname='hello_world!', state='up')\n eth0.commit() # rename, bring up and wait for success\n # --> <-- here you can be sure that the interface is up & renamed\n\nInstallation\n------------\n\nUsing pypi:\n\n.. code-block:: bash\n\n pip install pyroute2\n\nUsing git:\n\n.. code-block:: bash\n\n pip install git+https://github.com/svinota/pyroute2.git\n\nUsing source, requires make and nox\n\n.. code-block:: bash\n\n git clone https://github.com/svinota/pyroute2.git\n cd pyroute2\n make install\n\nRequirements\n------------\n\nPython >= 3.9\n\nLinks\n-----\n\n* home: https://pyroute2.org/\n* source: https://github.com/svinota/pyroute2\n* bugs: https://github.com/svinota/pyroute2/issues\n* pypi: https://pypi.python.org/pypi/pyroute2\n* docs: http://docs.pyroute2.org/\n",
"bugtrack_url": null,
"license": null,
"summary": "Python Netlink library",
"version": "0.9.4",
"project_urls": {
"Homepage": "https://github.com/svinota/pyroute2"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e289c011b555ccde0e5846ad3bb5a091fd0fcac997156406a9ad107f81cf91c9",
"md5": "2ea4f1635491c182efc7f9db27762911",
"sha256": "4e12437d18f6f42912cbd3f870edf06896183a78fd0c8126ba7a72a81f28d6cf"
},
"downloads": -1,
"filename": "pyroute2-0.9.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2ea4f1635491c182efc7f9db27762911",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 467555,
"upload_time": "2025-07-29T14:35:23",
"upload_time_iso_8601": "2025-07-29T14:35:23.880064Z",
"url": "https://files.pythonhosted.org/packages/e2/89/c011b555ccde0e5846ad3bb5a091fd0fcac997156406a9ad107f81cf91c9/pyroute2-0.9.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b05efc64e211cce0078555c6db98aaf14348aed527565f3c4876913a290a5b2c",
"md5": "225d6899da226df8899efcff2557204a",
"sha256": "3cbccbe1af0c2b2aeae81b327e0e91aa94c81ab19f851e74b26bef70202f3070"
},
"downloads": -1,
"filename": "pyroute2-0.9.4.tar.gz",
"has_sig": false,
"md5_digest": "225d6899da226df8899efcff2557204a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 463980,
"upload_time": "2025-07-29T14:35:27",
"upload_time_iso_8601": "2025-07-29T14:35:27.866323Z",
"url": "https://files.pythonhosted.org/packages/b0/5e/fc64e211cce0078555c6db98aaf14348aed527565f3c4876913a290a5b2c/pyroute2-0.9.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-29 14:35:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "svinota",
"github_project": "pyroute2",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pyroute2"
}
