Skip to main content

Nautobot API client library

Project description



pynautobot

Python API client library for Nautobot.

pynautobot was initially developed as a fork of pynetbox. pynetbox was originally developed by Zach Moody at DigitalOcean and the NetBox Community.

The complete documentation for pynautobot can be found at Read the Docs.

Questions? Comments? Join us in the #nautobot Slack channel on Network to Code!

Installation

You can install via pip or poetry

Using pip

$ pip install pynautobot
...

Using poetry

$ git clone https://github.com/nautobot/pynautobot.git
...
$ pip install poetry
...
$ poetry shell
Virtual environment already activated: /home/user/pynautobot/.venv
$ poetry install
...

Quick Start

A short introduction is provided here; the full documention for pynautobot is at Read the Docs.

To begin, import pynautobot and instantiate an Api object, passing the url and token.

import pynautobot
nautobot = pynautobot.api(
    url="http://localhost:8000",
    token="d6f4e314a5b5fefd164995169f28ae32d987704f",
)

The Api object provides access to the Apps in Nautobot. The Apps provide access to the Models and the field data stored in Nautobot. Pynautobot uses the Endpoint class to represent Models. For example, here is how to access Devices stored in Nautobot:

devices = nautobot.dcim.devices
devices
<pynautobot.core.endpoint.Endpoint object at 0x7fe801e62fa0>

Jobs

Pynautobot provides a specialized Endpoint class to represent the Jobs model. This class is called JobsEndpoint. This extends the Endpoint class by adding the run method so pynautobot can be used to call/execute a job run.

  1. Run from an instance of a job.
>>> gc_backup_job = nautobot.extras.jobs.get(name="Backup Configurations")
>>> job_result = gc_backup_job.run()
>>> job_result.job_result.id
'1838f8bd-440f-434e-9f29-82b46549a31d' # <-- Job Result ID.
  1. Run with Job Inputs
job = nautobot.extras.jobs.get(name="Verify Hostnames")
job.run(data={"hostname_regex": ".*"})
  1. Run by providing the job id
>>> my_job_id = nautobot.extras.jobs.get(name="Backup Configurations").id
>>> gc_backup_job = nautobot.extras.jobs.run(job_id=my_job_id)
>>> gc_backup_job.job_result.id
'548832dc-e586-4c65-a7c1-a4e799398a3b' # <-- Job Result ID.
  1. Run by providing the job name
>>> gc_backup_job = nautobot.extras.jobs.run(job_name="Backup Configurations")
>>> gc_backup_job.job_result.id
'29e82353-c0ef-4187-9211-92fb40a74923' # <-- Job Result ID.

Queries

Pynautobot provides several ways to retrieve objects from Nautobot. Only the get() method is shown here. To continue from the example above, the Endpoint object returned will be used to get the device named hq-access-01.

switch = devices.get(name="hq-access-01")

The object returned from the get() method is an implementation of the Record class. This object provides access to the field data from Nautobot.

switch.id
'6929b68d-8f87-4470-8377-e7fdc933a2bb'
switch.name
'hq-access-01'
switch.site
hq

Threading

Pynautobot supports multithreaded calls for .filter() and .all() queries. It is highly recommended you have MAX_PAGE_SIZE in your Nautobot install set to anything except 0 or None. The default value of 1000 is usually a good value to use. To enable threading, add threading=True parameter when instantiating the Api object:

nautobot = pynautobot.api(
    url="http://localhost:8000",
    token="d6f4e314a5b5fefd164995169f28ae32d987704f",
    threading=True,
)

Versioning

Used for Nautobot Rest API versioning. Versioning can be controlled globally by setting api_version on initialization of the API class and/or for a specific request e.g (all(), filter(), get(), create() etc.) by setting an optional api_version parameter.

Global versioning

import pynautobot
nautobot = pynautobot.api(
    url="http://localhost:8000",
    token="d6f4e314a5b5fefd164995169f28ae32d987704f",
    api_version="2.1"
)

Request specific versioning

import pynautobot
nautobot = pynautobot.api(
  url="http://localhost:8000", token="d6f4e314a5b5fefd164995169f28ae32d987704f",
)
tags = nautobot.extras.tags
tags.create(name="Tag", api_version="2.0", content_types=["dcim.device"])
tags.get(api_version="2.1",)

Retry logic

By default, the client will not retry any operation. This behavior can be adjusted via the retries optional parameters. This will only affect HTTP codes: 429, 500, 502, 503, and 504.

Retries

import pynautobot
nautobot = pynautobot.api(
    url="http://localhost:8000",
    token="d6f4e314a5b5fefd164995169f28ae32d987704f",
    retries=3
)

Related projects

Please see our wiki for a list of relevant community projects.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pynautobot-2.6.5.tar.gz (33.0 kB view details)

Uploaded Source

Built Distribution

pynautobot-2.6.5-py3-none-any.whl (40.7 kB view details)

Uploaded Python 3

File details

Details for the file pynautobot-2.6.5.tar.gz.

File metadata

  • Download URL: pynautobot-2.6.5.tar.gz
  • Upload date:
  • Size: 33.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for pynautobot-2.6.5.tar.gz
Algorithm Hash digest
SHA256 2a3e844b7aa533bc3640971c12ac3b75b0e741238f4485f3f65e78f516eb58ce
MD5 affa88a438afb09de8a73e5f0425f54c
BLAKE2b-256 3d22326fa12af47ec9e2832302fc6eeccf5216dbb6167937c24cc78d69a9d998

See more details on using hashes here.

File details

Details for the file pynautobot-2.6.5-py3-none-any.whl.

File metadata

  • Download URL: pynautobot-2.6.5-py3-none-any.whl
  • Upload date:
  • Size: 40.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for pynautobot-2.6.5-py3-none-any.whl
Algorithm Hash digest
SHA256 da9a775992ab451308f7d41a4103c9f67b06a7173079ffc10632123bee53b14a
MD5 36452cbd3b2e1bd7d97bec819240a46d
BLAKE2b-256 eddb92b100b5f9c8c27936f80e9c4a311db646553a8f5dd8d7b039a20f202a1b

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page