{"id":23975704,"url":"https://github.com/vladimirs-git/nbforager","last_synced_at":"2025-04-13T23:57:37.257Z","repository":{"id":220638889,"uuid":"750240036","full_name":"vladimirs-git/nbforager","owner":"vladimirs-git","description":"Python package to work with Netbox using REST API","archived":false,"fork":false,"pushed_at":"2025-03-01T14:37:04.000Z","size":558,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-11T18:05:12.318Z","etag":null,"topics":["api","netbox"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vladimirs-git.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-01-30T09:03:02.000Z","updated_at":"2025-03-01T14:37:08.000Z","dependencies_parsed_at":"2024-06-08T09:35:46.069Z","dependency_job_id":"b55b1f81-d943-403c-9736-b9ac5bb49889","html_url":"https://github.com/vladimirs-git/nbforager","commit_stats":null,"previous_names":["vladimirs-git/nbforager"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladimirs-git%2Fnbforager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladimirs-git%2Fnbforager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladimirs-git%2Fnbforager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladimirs-git%2Fnbforager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vladimirs-git","download_url":"https://codeload.github.com/vladimirs-git/nbforager/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248799926,"owners_count":21163403,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","netbox"],"created_at":"2025-01-07T06:50:22.903Z","updated_at":"2025-04-13T23:57:37.228Z","avatar_url":"https://github.com/vladimirs-git.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\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 \u003e= 3.8, Netbox \u003e= v3.6.\nFully documented on `Read the Docs`_.\n\n\n----------------------------------------------------------------------------------------\n\nRequirements\n============\n\nPython \u003e=3.8,\u003c3.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)  # \u003cResponse [201]\u003e\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)  # \u003cResponse [200]\u003e\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)  # \u003cResponse [204]\u003e\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvladimirs-git%2Fnbforager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvladimirs-git%2Fnbforager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvladimirs-git%2Fnbforager/lists"}