Query¶
pynautobot.core.query
¶
Defines classes and functions for making HTTP requests to the Nautobot API.
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.
__init__(message)
¶
Initialize the AllocationError object.
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.
__init__(message)
¶
Initialize the ContentError object.
pynautobot.core.query.Request
¶
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 |
4
|
__init__(base, http_session, filters=None, limit=None, offset=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 |
http_session |
Session
|
The HTTP session to use for the request. |
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
|
limit |
int
|
The pagination limit of the request. |
None
|
offset |
int
|
The pagination offset of the request. |
None
|
key |
int
|
database id of the item being queried. |
None
|
token |
str
|
The token to use for the request. |
None
|
threading |
bool
|
Whether to use threading for the request. |
False
|
max_workers |
int
|
The maximum number of workers for the request. |
4
|
api_version |
str
|
Set to override the default Nautobot REST API Version. |
None
|
concurrent_get(ret, page_size, page_offsets)
¶
Concurrently get paginated results.
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:
| 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 |
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 |
list
|
Additional positional arguments to be passed to the Nautobot API endpoint. |
()
|
**kwargs |
dict
|
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:
| Type | Description |
|---|---|
int
|
The total number of objects that would match the provided query. |
get_openapi()
¶
Gets the OpenAPI Specification.
get_status()
¶
Gets the status from /api/status/ endpoint in Nautobot.
Returns:
| 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:
| 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:
| Type | Description |
|---|---|
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:
| Type | Description |
|---|---|
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:
| Type | Description |
|---|---|
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)
__init__(message)
¶
Initialize the RequestError object.
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.