Skip to main content
CommunityCloudEnterprise

Advanced Usage

Threading​

PyNetBox supports multithreaded calls for .filter() and .all() queries to significantly improve performance when fetching large datasets.

NetBox Configuration Required

It is highly recommended you have MAX_PAGE_SIZE in your NetBox installation set to anything except 0 or None. The default value of 1000 is usually a good value to use.

Enabling Threading​

Enable threading globally by passing threading=True to the API initialization:

import pynetbox

nb = pynetbox.api(
    'http://netbox.example.com',
    token='your-token',
    threading=True
)

# Now all .all() and .filter() calls will use threading
devices = nb.dcim.devices.all()  # Fetches pages in parallel

How It Works​

When threading is enabled:

  • PyNetBox fetches multiple pages of results in parallel
  • Significantly faster for large result sets
  • Especially useful for .all() queries that span many pages
  • Works automatically with pagination

Example​

import pynetbox
import time

nb = pynetbox.api('http://netbox.example.com', token='your-token')

# Without threading
start = time.time()
devices = list(nb.dcim.devices.all())
print(f"Without threading: {time.time() - start:.2f}s")

# With threading
nb_threaded = pynetbox.api(
    'http://netbox.example.com',
    token='your-token',
    threading=True
)
start = time.time()
devices = list(nb_threaded.dcim.devices.all())
print(f"With threading: {time.time() - start:.2f}s")

Filter Validation​

NetBox doesn't validate filters passed to GET API endpoints (.get() and .filter()). If a filter is incorrect, NetBox silently returns the entire database table content, which can be slow and unexpected.

PyNetBox can validate filter parameters against NetBox's OpenAPI specification before making the request, raising an exception if a parameter is invalid.

Enabling Strict Filters Globally​

import pynetbox

nb = pynetbox.api(
    'http://netbox.example.com',
    token='your-token',
    strict_filters=True  # Enable validation globally
)

# This will raise ParameterValidationError
try:
    devices = nb.dcim.devices.filter(non_existing_filter='value')
except pynetbox.core.query.ParameterValidationError as e:
    print(f"Invalid filter: {e}")

Per-Request Validation​

You can also enable or disable validation on a per-request basis:

nb = pynetbox.api('http://netbox.example.com', token='your-token')

# Enable for one request (when not globally enabled)
try:
    devices = nb.dcim.devices.filter(
        non_existing_filter='aaaa',
        strict_filters=True
    )
except pynetbox.core.query.ParameterValidationError as e:
    print(f"Invalid filter: {e}")

# Disable for one request (when globally enabled)
nb_strict = pynetbox.api(
    'http://netbox.example.com',
    token='your-token',
    strict_filters=True
)
# This won't raise an exception, but returns entire table
devices = nb_strict.dcim.devices.filter(
    non_existing_filter='aaaa',
    strict_filters=False
)

Benefits of Strict Filters​

  • Catch typos early: Find misspelled filter names before making requests
  • Prevent full table scans: Avoid accidentally fetching entire tables
  • Better error messages: Get clear feedback about invalid parameters
  • Development aid: Helpful during development to ensure correct filter usage

Example​

import pynetbox

nb = pynetbox.api(
    'http://netbox.example.com',
    token='your-token',
    strict_filters=True
)

# Valid filter - works fine
devices = nb.dcim.devices.filter(site='datacenter1')

# Invalid filter - raises exception
try:
    devices = nb.dcim.devices.filter(iste='datacenter1')  # Typo: 'iste' instead of 'site'
except pynetbox.core.query.ParameterValidationError as e:
    print(f"Error: {e}")
    # Error: 'iste' is not a valid filter parameter for dcim.devices

Custom Sessions​

Custom sessions can be used to modify the default HTTP behavior. Below are a few examples, most of them from here.

Headers​

To set a custom header on all requests. These headers are automatically merged with headers pynetbox sets itself.

Example:

import pynetbox
import requests
session = requests.Session()
session.headers = {"mycustomheader": "test"}
nb = pynetbox.api(
    'http://netbox.example.com',
    token='d6f4e314a5b5fefd164995169f28ae32d987704f'
)
nb.http_session = session

SSL Verification​

To disable SSL verification. See the docs.

Example:

import pynetbox
import requests
session = requests.Session()
session.verify = False
nb = pynetbox.api(
    'http://netbox.example.com',
    token='d6f4e314a5b5fefd164995169f28ae32d987704f'
)
nb.http_session = session

Timeouts​

Setting timeouts requires the use of Adapters.

Example:

from requests.adapters import HTTPAdapter

class TimeoutHTTPAdapter(HTTPAdapter):
    def __init__(self, *args, **kwargs):
        self.timeout = kwargs.get("timeout", 5)
        super().__init__(*args, **kwargs)

    def send(self, request, **kwargs):
        kwargs['timeout'] = self.timeout
        return super().send(request, **kwargs)

adapter = TimeoutHTTPAdapter()
session = requests.Session()
session.mount("http://", adapter)
session.mount("https://", adapter)

nb = pynetbox.api(
    'http://netbox.example.com',
    token='d6f4e314a5b5fefd164995169f28ae32d987704f'
)
nb.http_session = session

File Uploads (Image Attachments)​

Pynetbox supports file uploads for endpoints that accept them, such as image attachments. When you pass a file-like object (anything with a .read() method) to create(), pynetbox automatically detects it and uses multipart/form-data encoding instead of JSON.

Creating an Image Attachment​

import pynetbox

nb = pynetbox.api(
    'http://netbox.example.com',
    token='d6f4e314a5b5fefd164995169f28ae32d987704f'
)

# Attach an image to a device
with open('/path/to/image.png', 'rb') as f:
    attachment = nb.extras.image_attachments.create(
        object_type='dcim.device',
        object_id=1,
        image=f,
        name='rack-photo.png'
    )

Using io.BytesIO​

You can also use in-memory file objects:

import io
import pynetbox

nb = pynetbox.api(
    'http://netbox.example.com',
    token='d6f4e314a5b5fefd164995169f28ae32d987704f'
)

# Create image from bytes
image_data = b'...'  # Your image bytes
file_obj = io.BytesIO(image_data)
file_obj.name = 'generated-image.png'  # Optional: set filename

attachment = nb.extras.image_attachments.create(
    object_type='dcim.device',
    object_id=1,
    image=file_obj
)

Custom Filename and Content-Type​

For more control, pass a tuple instead of a file object:

with open('/path/to/image.png', 'rb') as f:
    attachment = nb.extras.image_attachments.create(
        object_type='dcim.device',
        object_id=1,
        image=('custom-name.png', f, 'image/png')
    )

The tuple format is (filename, file_object) or (filename, file_object, content_type).

Multi-Format Responses​

Some endpoints support multiple response formats. The rack elevation endpoint can return both JSON data and SVG diagrams.

Getting Rack Elevation as JSON​

By default, the elevation endpoint returns JSON data as a list of rack unit objects:

import pynetbox

nb = pynetbox.api(
    'http://netbox.example.com',
    token='d6f4e314a5b5fefd164995169f28ae32d987704f'
)

rack = nb.dcim.racks.get(123)

# Returns list of RU objects (default JSON response)
units = rack.elevation.list()
for unit in units:
    print(unit.id, unit.name)

Getting Rack Elevation as SVG​

Use the render='svg' parameter to get a graphical SVG diagram:

rack = nb.dcim.racks.get(123)

# Returns raw SVG string
svg_diagram = rack.elevation.list(render='svg')
print(svg_diagram)  # '<svg xmlns="http://www.w3.org/2000/svg">...</svg>'

# Save to file
with open('rack-elevation.svg', 'w') as f:
    f.write(svg_diagram)
Last updated on