Housekeeping: Update Invoke Commands to work as other repos

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.

Run from an instance of a job.

>>> gc_backup_job = nautobot.extras.jobs.all()[14]
>>> job_result = gc_backup_job.run()
>>> job_result.result.id
'1838f8bd-440f-434e-9f29-82b46549a31d' # <-- Job Result ID.

Run with Job Inputs

job = nautobot.extras.jobs.all()[7]
job.run(data={"hostname_regex": ".*"})

Run by providing the job id

>>> gc_backup_job = nautobot.extras.jobs.run(class_path=nautobot.extras.jobs.all()[14].id)
>>> gc_backup_job.result.id
'548832dc-e586-4c65-a7c1-a4e799398a3b' # <-- 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.

Nautobot version	REST API version(s)
1.0	1.0
1.1	1.1
1.2	1.2
1.3	1.2 (default), 1.3 (if requested)

	@property
	def version(self):
	"""Gets the API version of Nautobot.

	Can be used to check the Nautobot API version if there are
	version-dependent features or syntaxes in the API.

	:Returns: Version number as a string.
	:Example:

	>>> import pynautobot
	>>> nb = pynautobot.api(
	... 'http://localhost:8000',
	... token='d6f4e314a5b5fefd164995169f28ae32d987704f'
	... )
	>>> nb.version
	'1.0'
	>>>
	"""
	version = Request(
	base=self.base_url, http_session=self.http_session, api_version=self.api_version
	).get_version()
	return version

	def openapi(self):
	"""Returns the OpenAPI spec.

	Quick helper function to pull down the entire OpenAPI spec.

	:Returns: dict
	:Example:

	>>> import pynautobot
	>>> nb = pynautobot.api(
	... 'http://localhost:8000',
	... token='d6f4e314a5b5fefd164995169f28ae32d987704f'
	... )
	>>> nb.openapi()
	{...}
	>>>
	"""
	return Request(base=self.base_url, http_session=self.http_session, api_version=self.api_version,).get_openapi()

	def status(self):
	"""Gets the status information from Nautobot.

	Available in Nautobot 2.10.0 or newer.

	:Returns: Dictionary as returned by Nautobot.
	:Raises: :py:class:`.RequestError` if the request is not successful.
	:Example:

	>>> pprint.pprint(nb.status())
	{'django-version': '3.1.3',
	'installed-apps': {'cacheops': '5.0.1',
	'debug_toolbar': '3.1.1',
	'django_filters': '2.4.0',
	'django_prometheus': '2.1.0',
	'django_rq': '2.4.0',
	'django_tables2': '2.3.3',
	'drf_yasg': '1.20.0',
	'mptt': '0.11.0',
	'rest_framework': '3.12.2',
	'taggit': '1.3.0',
	'timezone_field': '4.0'},
	'nautobot-version': '1.0.0',
	'plugins': {},
	'python-version': '3.7.3',
	'rq-workers-running': 1}
	>>>
	"""
	status = Request(
	base=self.base_url, token=self.token, http_session=self.http_session, api_version=self.api_version,
	).get_status()
	return status

	def get_openapi(self):
	""" Gets the OpenAPI Spec """
	headers = {
	"Content-Type": "application/json;",
	}

	if self.api_version:
	headers["accept"] = f"application/json; version={self.api_version}"

	req = self.http_session.get("{}docs/?format=openapi".format(self.normalize_url(self.base)), headers=headers,)
	if req.ok:
	return req.json()
	else:
	raise RequestError(req)

	def get_version(self):
	"""Gets the API version of Nautobot.

	Issues a GET request to the base URL to read the API version from the
	response headers.

	:Raises: RequestError if req.ok returns false.
	:Returns: Version number as a string. Empty string if version is not
	present in the headers.
	"""
	headers = {"Content-Type": "application/json;"}
	if self.api_version:
	headers["accept"] = f"application/json; version={self.api_version}"

	req = self.http_session.get(self.normalize_url(self.base), headers=headers,)

	if req.ok:
	return req.headers.get("API-Version", "")
	else:
	raise RequestError(req)

	def get_status(self):
	"""Gets the status from /api/status/ endpoint in Nautobot.

	:Returns: Dictionary as returned by Nautobot.
	:Raises: RequestError if request is not successful.
	"""
	headers = {"Content-Type": "application/json;"}
	if self.token:
	headers["authorization"] = "Token {}".format(self.token)

	if self.api_version:
	headers["accept"] = f"application/json; version={self.api_version}"

	req = self.http_session.get("{}status/".format(self.normalize_url(self.base)), headers=headers,)
	if req.ok:
	return req.json()
	else:
	raise RequestError(req)

nautobot / pynautobot Goto Github PK

pynautobot's Introduction

pynautobot

Installation

Using pip

Using poetry

Quick Start

Jobs

Queries

Threading

Versioning

Retry logic

Related projects

pynautobot's People

Contributors

Stargazers

Watchers

Forkers

pynautobot's Issues

Reproducer:

Current result

Expected result

Versions

Problem statement

Proposal

Environment

Steps to Reproduce

Expected Behavior

Observed Behavior

Environment

Steps to Reproduce

Expected Behavior

Tasks

Proposal

Justfication

Re-producable using:

Example

Links to code

Recommend Projects

Recommend Topics

Recommend Org