| Name | nbforager JSON |
| Version |
0.4.1
JSON |
| download |
| home_page | https://github.com/vladimirs-git/nbforager |
| Summary | Python package designed to assist in working with the Netbox REST API. The filter parameters are identical to those in the Web UI filter form. It replaces brief data with full information, and Netbox objects are represented as a recursive multidimensional dictionary. |
| upload_time | 2024-11-13 17:49:06 |
| maintainer | None |
| docs_url | None |
| author | Vladimirs Prusakovs |
| requires_python | <4.0,>=3.8 |
| license | Apache-2.0 |
| keywords |
netbox
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
.. image:: https://img.shields.io/pypi/v/netports.svg
:target: https://pypi.python.org/pypi/netports
.. image:: https://img.shields.io/badge/Python-3.8%20%7C%203.9%20%7C%203.10%20%7C%203.11-blue.svg
:target: https://pypi.python.org/pypi/logger-color
nbforager
=========
Overview
========
Python package designed to help work with the `Netbox`_ REST API.
- `NbApi`_ Request data from Netbox using filter parameters identical to those in the Web UI filter form. Filter parameters use the ``OR`` operator.
- `NbForager`_ The REST API returns objects that contain a brief representation of related objects. NbForager replaces brief data with full and objects look like a recursive multidimensional dictionary.
- `NbParser`_ Extract typed values from a Netbox object dictionary by using a chain of keys.
Checked with Python >= 3.8, Netbox >= v3.6.
Fully documented on `Read the Docs`_.
----------------------------------------------------------------------------------------
Requirements
============
Python >=3.8,<3.12
Quickstart
==========
Install the package from pypi.org
.. code:: bash
pip install nbforager
or from github.com repository
.. code:: bash
pip install git+https://github.com/vladimirs-git/nbforager
NbForager demonstration.
Assemble Netbox objects within self as a multidimensional dictionary.
Request the main object. All nested objects also are requested.
Assemble multidimensional dictionary.
.. code:: python
from pprint import pprint
from nbforager import NbForager
HOST = "demo.netbox.dev"
TOKEN = "1234567890123456789012345678901234567890"
nbf = NbForager(host=HOST, token=TOKEN, threads=10)
# Request devices with all nested object: device-roles, tenants, tags, etc.
nbf.dcim.devices.get(nested=True)
print(f"{len(nbf.root.dcim.devices)=}")
print(f"{len(nbf.root.dcim.device_roles)=}")
print(f"{len(nbf.root.tenancy.tenants)=}")
print(f"{len(nbf.root.extras.tags)=}")
# len(nbf.root.dcim.devices)=78
# len(nbf.root.dcim.device_roles)=10
# len(nbf.root.tenancy.tenants)=5
# len(nbf.root.extras.tags)=2
# Assemble objects within self as multidimensional dictionary.
tree = nbf.join_tree()
pprint(list(tree.dcim.devices.values())[0])
# {"id": 1,
# "name": "dmi01-akron-rtr01",
# "rack": {"id": 1,
# "site": {"id": 2,
# "tenant": {"id": 5,
# "group": {"id": 1,
# "name": "Customers",
# ...
# "tenant": {"id": 5,
# "group": {"id": 1,
# "name": "Customers",
# ...
# ...
Request objects using filtering parameters. Assemble multidimensional dictionary.
.. code:: python
from pprint import pprint
from nbforager import NbForager, NbParser
HOST = "demo.netbox.dev"
TOKEN = "1234567890123456789012345678901234567890"
nbf = NbForager(host=HOST, token=TOKEN)
# Request specific devices and all sites from Netbox.
# Note that the site in the device only contains basic data and
# does not include tags, region and other extended data.
nbf.dcim.devices.get(q="PP:B")
nbf.dcim.sites.get()
device = nbf.root.dcim.devices[88]
pprint(device)
# {"id": 88,
# "name": "PP:B117",
# "site": {"display": "MDF",
# "id": 21,
# "name": "MDF",
# "slug": "ncsu-065",
# "url": "https://demo.netbox.dev/api/dcim/sites/21/"},
# ...
# Assemble objects within self as multidimensional dictionary.
# Note that the device now includes site region and all other data.
tree = nbf.join_tree()
device = tree.dcim.devices[88]
pprint(device)
# {"id": 88,
# "name": "PP:B117",
# "site": {"display": "MDF",
# "id": 21,
# "name": "MDF",
# "slug": "ncsu-065",
# "url": "https://demo.netbox.dev/api/dcim/sites/21/"
# "region": {"_depth": 2,
# "display": "North Carolina",
# "id": 40,
# "name": "North Carolina",
# "slug": "us-nc",
# "url": "https://demo.netbox.dev/api/dcim/regions/40/"},
# "tenant": {"display": "NC State University",
# "id": 13,
# "name": "NC State University",
# "slug": "nc-state",
# "url": "https://demo.netbox.dev/api/tenancy/tenants/13/"},
# ...
# ...
# Access site attribute through a device.
region = device["site"]["region"]["name"]
print(f"{region=}") # region="North Carolina"
# Use NbParser to ensure the data type if any dictionary in the chain is missing.
region = NbParser(device).str("site", "region", "name")
print(f"{region=}") # region="North Carolina"
NbApi demonstration.
Create, get, update and delete ip-addresses.
.. code:: python
from nbforager import NbApi
HOST = "demo.netbox.dev"
TOKEN = "1234567890123456789012345678901234567890"
nb = NbApi(host=HOST, token=TOKEN)
# Create 2 addresses with different methods (different outputs)
response = nb.ipam.ip_addresses.create(address="1.2.3.4/24", tags=[2], status="active")
print(response) # <Response [201]>
data = nb.ipam.ip_addresses.create_d(address="1.2.3.4/24", tags=[3], status="reserved")
print(data) # {"id": 183, "display": "1.2.3.4/24", ...
# Get all addresses
addresses = nb.ipam.ip_addresses.get()
print(len(addresses)) # 181
# Get all ip-addresses in global routing
addresses = nb.ipam.ip_addresses.get(vrf="null")
print(len(addresses)) # 30
# Get newly created ip-addresses by complex filter
# Note, you can use parameters similarly to the ``OR`` operator.
# Filter addresses in the global routing AND
# (have either the tag "bravo" OR "charlie") AND
# (have a status of either active OR reserved).
addresses = nb.ipam.ip_addresses.get(or_q=["1.2.3", "4.5.6"],
vrf="null",
or_tag=["bravo", "charlie"],
status=["active", "reserved"])
print(len(addresses)) # 2
addresses = nb.ipam.ip_addresses.get(address="1.2.3.4/24")
for address in addresses:
# Update
id_ = address["id"]
response = nb.ipam.ip_addresses.update(id=id_, description="text")
print(response) # <Response [200]>
print(nb.ipam.ip_addresses.get(id=id_)[0]["description"]) # text
# Delete
response = nb.ipam.ip_addresses.delete(id=id_)
print(response) # <Response [204]>
----------------------------------------------------------------------------------------
.. _`Netbox`: https://github.com/netbox-community/netbox
.. _`Read the Docs`: https://nbforager.readthedocs.io/en/latest/
.. _`NbApi`: https://nbforager.readthedocs.io/en/latest/api/nb_api.html#nbapi
.. _`NbForager`: https://nbforager.readthedocs.io/en/latest/foragers/nb_forager.html#nbforager
.. _`NbParser`: https://nbforager.readthedocs.io/en/latest/parser/nb_parser.html#nbparser
Raw data
{
"_id": null,
"home_page": "https://github.com/vladimirs-git/nbforager",
"name": "nbforager",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "netbox",
"author": "Vladimirs Prusakovs",
"author_email": "vladimir.prusakovs@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/8e/5a/94748f99fe5bdfd718ea49eb4735cd64e9fadc7d0c4bca3b764c7912b130/nbforager-0.4.1.tar.gz",
"platform": null,
"description": "\n.. image:: https://img.shields.io/pypi/v/netports.svg\n :target: https://pypi.python.org/pypi/netports\n.. image:: https://img.shields.io/badge/Python-3.8%20%7C%203.9%20%7C%203.10%20%7C%203.11-blue.svg\n :target: https://pypi.python.org/pypi/logger-color\n\n\nnbforager\n=========\n\n\nOverview\n========\n\nPython package designed to help work with the `Netbox`_ REST API.\n\n- `NbApi`_ Request data from Netbox using filter parameters identical to those in the Web UI filter form. Filter parameters use the ``OR`` operator.\n- `NbForager`_ The REST API returns objects that contain a brief representation of related objects. NbForager replaces brief data with full and objects look like a recursive multidimensional dictionary.\n- `NbParser`_ Extract typed values from a Netbox object dictionary by using a chain of keys.\n\nChecked with Python >= 3.8, Netbox >= v3.6.\nFully documented on `Read the Docs`_.\n\n\n----------------------------------------------------------------------------------------\n\nRequirements\n============\n\nPython >=3.8,<3.12\n\n\nQuickstart\n==========\n\nInstall the package from pypi.org\n\n.. code:: bash\n\n pip install nbforager\n\nor from github.com repository\n\n.. code:: bash\n\n pip install git+https://github.com/vladimirs-git/nbforager\n\n\nNbForager demonstration.\nAssemble Netbox objects within self as a multidimensional dictionary.\n\nRequest the main object. All nested objects also are requested.\nAssemble multidimensional dictionary.\n\n.. code:: python\n\n from pprint import pprint\n\n from nbforager import NbForager\n\n HOST = \"demo.netbox.dev\"\n TOKEN = \"1234567890123456789012345678901234567890\"\n nbf = NbForager(host=HOST, token=TOKEN, threads=10)\n\n # Request devices with all nested object: device-roles, tenants, tags, etc.\n nbf.dcim.devices.get(nested=True)\n print(f\"{len(nbf.root.dcim.devices)=}\")\n print(f\"{len(nbf.root.dcim.device_roles)=}\")\n print(f\"{len(nbf.root.tenancy.tenants)=}\")\n print(f\"{len(nbf.root.extras.tags)=}\")\n # len(nbf.root.dcim.devices)=78\n # len(nbf.root.dcim.device_roles)=10\n # len(nbf.root.tenancy.tenants)=5\n # len(nbf.root.extras.tags)=2\n\n\n # Assemble objects within self as multidimensional dictionary.\n tree = nbf.join_tree()\n pprint(list(tree.dcim.devices.values())[0])\n # {\"id\": 1,\n # \"name\": \"dmi01-akron-rtr01\",\n # \"rack\": {\"id\": 1,\n # \"site\": {\"id\": 2,\n # \"tenant\": {\"id\": 5,\n # \"group\": {\"id\": 1,\n # \"name\": \"Customers\",\n # ...\n # \"tenant\": {\"id\": 5,\n # \"group\": {\"id\": 1,\n # \"name\": \"Customers\",\n # ...\n # ...\n\nRequest objects using filtering parameters. Assemble multidimensional dictionary.\n\n.. code:: python\n\n from pprint import pprint\n\n from nbforager import NbForager, NbParser\n\n HOST = \"demo.netbox.dev\"\n TOKEN = \"1234567890123456789012345678901234567890\"\n nbf = NbForager(host=HOST, token=TOKEN)\n\n # Request specific devices and all sites from Netbox.\n # Note that the site in the device only contains basic data and\n # does not include tags, region and other extended data.\n nbf.dcim.devices.get(q=\"PP:B\")\n nbf.dcim.sites.get()\n device = nbf.root.dcim.devices[88]\n pprint(device)\n # {\"id\": 88,\n # \"name\": \"PP:B117\",\n # \"site\": {\"display\": \"MDF\",\n # \"id\": 21,\n # \"name\": \"MDF\",\n # \"slug\": \"ncsu-065\",\n # \"url\": \"https://demo.netbox.dev/api/dcim/sites/21/\"},\n # ...\n\n # Assemble objects within self as multidimensional dictionary.\n # Note that the device now includes site region and all other data.\n tree = nbf.join_tree()\n device = tree.dcim.devices[88]\n pprint(device)\n # {\"id\": 88,\n # \"name\": \"PP:B117\",\n # \"site\": {\"display\": \"MDF\",\n # \"id\": 21,\n # \"name\": \"MDF\",\n # \"slug\": \"ncsu-065\",\n # \"url\": \"https://demo.netbox.dev/api/dcim/sites/21/\"\n # \"region\": {\"_depth\": 2,\n # \"display\": \"North Carolina\",\n # \"id\": 40,\n # \"name\": \"North Carolina\",\n # \"slug\": \"us-nc\",\n # \"url\": \"https://demo.netbox.dev/api/dcim/regions/40/\"},\n # \"tenant\": {\"display\": \"NC State University\",\n # \"id\": 13,\n # \"name\": \"NC State University\",\n # \"slug\": \"nc-state\",\n # \"url\": \"https://demo.netbox.dev/api/tenancy/tenants/13/\"},\n # ...\n # ...\n\n # Access site attribute through a device.\n region = device[\"site\"][\"region\"][\"name\"]\n print(f\"{region=}\") # region=\"North Carolina\"\n\n # Use NbParser to ensure the data type if any dictionary in the chain is missing.\n region = NbParser(device).str(\"site\", \"region\", \"name\")\n print(f\"{region=}\") # region=\"North Carolina\"\n\n\nNbApi demonstration.\nCreate, get, update and delete ip-addresses.\n\n.. code:: python\n\n from nbforager import NbApi\n\n HOST = \"demo.netbox.dev\"\n TOKEN = \"1234567890123456789012345678901234567890\"\n nb = NbApi(host=HOST, token=TOKEN)\n\n # Create 2 addresses with different methods (different outputs)\n response = nb.ipam.ip_addresses.create(address=\"1.2.3.4/24\", tags=[2], status=\"active\")\n print(response) # <Response [201]>\n data = nb.ipam.ip_addresses.create_d(address=\"1.2.3.4/24\", tags=[3], status=\"reserved\")\n print(data) # {\"id\": 183, \"display\": \"1.2.3.4/24\", ...\n\n # Get all addresses\n addresses = nb.ipam.ip_addresses.get()\n print(len(addresses)) # 181\n\n # Get all ip-addresses in global routing\n addresses = nb.ipam.ip_addresses.get(vrf=\"null\")\n print(len(addresses)) # 30\n\n # Get newly created ip-addresses by complex filter\n # Note, you can use parameters similarly to the ``OR`` operator.\n # Filter addresses in the global routing AND\n # (have either the tag \"bravo\" OR \"charlie\") AND\n # (have a status of either active OR reserved).\n addresses = nb.ipam.ip_addresses.get(or_q=[\"1.2.3\", \"4.5.6\"],\n vrf=\"null\",\n or_tag=[\"bravo\", \"charlie\"],\n status=[\"active\", \"reserved\"])\n print(len(addresses)) # 2\n\n addresses = nb.ipam.ip_addresses.get(address=\"1.2.3.4/24\")\n for address in addresses:\n # Update\n id_ = address[\"id\"]\n response = nb.ipam.ip_addresses.update(id=id_, description=\"text\")\n print(response) # <Response [200]>\n print(nb.ipam.ip_addresses.get(id=id_)[0][\"description\"]) # text\n\n # Delete\n response = nb.ipam.ip_addresses.delete(id=id_)\n print(response) # <Response [204]>\n\n\n----------------------------------------------------------------------------------------\n\n.. _`Netbox`: https://github.com/netbox-community/netbox\n.. _`Read the Docs`: https://nbforager.readthedocs.io/en/latest/\n.. _`NbApi`: https://nbforager.readthedocs.io/en/latest/api/nb_api.html#nbapi\n.. _`NbForager`: https://nbforager.readthedocs.io/en/latest/foragers/nb_forager.html#nbforager\n.. _`NbParser`: https://nbforager.readthedocs.io/en/latest/parser/nb_parser.html#nbparser\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Python package designed to assist in working with the Netbox REST API. The filter parameters are identical to those in the Web UI filter form. It replaces brief data with full information, and Netbox objects are represented as a recursive multidimensional dictionary.",
"version": "0.4.1",
"project_urls": {
"Bug Tracker": "https://github.com/vladimirs-git/nbforager/issues",
"Download URL": "https://github.com/vladimirs-git/nbforager/archive/refs/tags/0.4.1.tar.gz",
"Homepage": "https://github.com/vladimirs-git/nbforager",
"Repository": "https://github.com/vladimirs-git/nbforager"
},
"split_keywords": [
"netbox"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8e5a94748f99fe5bdfd718ea49eb4735cd64e9fadc7d0c4bca3b764c7912b130",
"md5": "80bfcf362c7d91aeffcef406218711d9",
"sha256": "1fd16a96d6bf016799b0ba5bc99b8c5db044ca8579a7fc7784df217be7b1d797"
},
"downloads": -1,
"filename": "nbforager-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "80bfcf362c7d91aeffcef406218711d9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 56121,
"upload_time": "2024-11-13T17:49:06",
"upload_time_iso_8601": "2024-11-13T17:49:06.607033Z",
"url": "https://files.pythonhosted.org/packages/8e/5a/94748f99fe5bdfd718ea49eb4735cd64e9fadc7d0c4bca3b764c7912b130/nbforager-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-13 17:49:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vladimirs-git",
"github_project": "nbforager",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "nbforager"
}
