Query

pynautobot.core.query

pynautobot.core.query.AllocationError

Bases: Exception

Allocation Exception

Used with available-ips/available-prefixes when there is no room for allocation and Nautobot returns 204 No Content.

pynautobot.core.query.ContentError

Bases: Exception

Content Exception

If the API URL does not point to a valid Nautobot API, the server may return a valid response code, but the content is not json. This exception is raised in those cases.

pynautobot.core.query.Request

Bases: object

Creates requests to the Nautobot API.

Responsible for building the URL and making the HTTP(S) requests to Nautobot's API.

Parameters:

Name	Type	Description	Default
base	str	Base URL passed in api() instantiation.	required
filters	dict	Contains key/value pairs that correlate to the filters a given endpoint accepts. In (e.g. /api/dcim/devices/?name='test'), 'name': 'test' would be in the filters dict.	None
max_workers	int	Set the maximum workers for threading in .all() and .filter() requests.	4

__init__(base, http_session, filters=None, key=None, token=None, threading=False, max_workers=4, api_version=None)

Instantiates a new Request object

Parameters:

Name	Type	Description	Default
base	string	Base URL passed in api() instantiation.	required
filters	dict	contains key/value pairs that correlate to the filters a given endpoint accepts. In (e.g. /api/dcim/devices/?name='test') 'name': 'test' would be in the filters dict.	None
key	int	database id of the item being queried.	None
api_version	str	Set to override the default Nautobot REST API Version.	None

delete(data=None)

Makes DELETE request.

Makes a DELETE request to Nautobot's API.

Parameters:

Name	Type	Description	Default
data	list	Contains a dict that will be turned into a json object and sent to the API.	None

Returns:

Name	Type	Description
bool		True if successful.

Raises:

Type	Description
RequestError	If req.ok doesn't return True.

get(add_params=None)

Makes a GET request.

Makes a GET request to Nautobot's API, and automatically recurses any paginated results.

Raises:

Type	Description
RequestError	If req.ok returns false.
ContentError	If response is not JSON.

Returns:

Type	Description
	List[Response]: List of Response objects returned from the endpoint.

get_count(*args, **kwargs)

Retrieves the number of objects matching a query in the Nautobot API.

Makes a GET request to the specified endpoint with a limited response (limit=1) and extracts the "count" field from the response to determine the total number of objects that would be returned by a full query with the same parameters.

Parameters:

Name	Type	Description	Default
*args		Additional positional arguments to be passed to the Nautobot API endpoint.	()
**kwargs		Additional keyword arguments to be passed to the Nautobot API endpoint.	{}

Raises:

Type	Description
RequestError	If the request fails (i.e., req.ok returns False).
ContentError	If the response cannot be deserialized from JSON.

Returns:

Name	Type	Description
int	int	The total number of objects that would match the provided query.

get_openapi()

Gets the OpenAPI Spec

get_status()

Gets the status from /api/status/ endpoint in Nautobot.

Returns:

Name	Type	Description
dict		Dictionary as returned by Nautobot.

Raises:

Type	Description
RequestError	If request is not successful.

get_version()

Gets the API version of Nautobot.

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

Raises:

Type	Description
RequestError	If req.ok returns false.

Returns:

Name	Type	Description
str		Version number as a string. Empty string if version is not present in the headers.

normalize_url(url)

Builds a url for POST actions.

options()

Retrieves allowed HTTP methods for a Nautobot API endpoint.

Makes an OPTIONS request to determine the allowed HTTP methods supported by a specific Nautobot API endpoint.

Raises:

Type	Description
RequestError	If the request fails (i.e., req.ok returns False).
ContentError	If the response cannot be deserialized from JSON.

Returns:

Name	Type	Description
dict	dict	The deserialized JSON response from the Nautobot API, containing information about allowed methods.

patch(data)

Makes a PATCH request to the Nautobot API.

Parameters:

Name	Type	Description	Default
data	dict	(dict) The data to be sent in the PATCH request body. It will be serialized to JSON before sending.	required

Raises:

Type	Description
RequestError	If the request fails (i.e., req.ok returns False).
ContentError	If the response cannot be deserialized from JSON.

Returns:

Name	Type	Description
dict	dict	The deserialized JSON response from the Nautobot API.

post(data)

Makes a POST request to the Nautobot API.

Parameters:

Name	Type	Description	Default
data	dict	(dict) The data to be sent in the POST request body. It will be serialized to JSON before sending.	required

Raises:

Type	Description
RequestError	If the request fails (i.e., req.ok returns False).
AllocationError	If the status code is 204 (No Content), indicating no available resources for allocation (e.g., available IPs or prefixes).
ContentError	If the response cannot be deserialized from JSON.

Returns:

Name	Type	Description
dict	dict	The deserialized JSON response from the Nautobot API.

put(data)

Makes a PUT request to the Nautobot API.

Parameters:

Name	Type	Description	Default
data	dict	(dict) The data to be sent in the PUT request body. It will be serialized to JSON before sending.	required

Raises:

Type	Description
RequestError	If the request fails (i.e., req.ok returns False).
ContentError	If the response cannot be deserialized from JSON.

Returns:

Name	Type	Description
dict	dict	The deserialized JSON response from the Nautobot API.

pynautobot.core.query.RequestError

Bases: Exception

Basic Request Exception

More detailed exception that returns the original requests object for inspection. Along with some attributes with specific details from the requests object. If return is JSON we decode and add it to the message.

Examples:

>>> try:
...     nb.dcim.devices.create(name="destined-for-failure")
... except pynautobot.RequestError as e:
...     print(e.error)

pynautobot.core.query.RequestErrorFromException

Bases: Exception

RequestErrorFromException is raised from exception.

pynautobot.core.query.calc_pages(limit, count)

Calculate number of pages required for full results set.