Response

class pynetbox.core.response.Record(values, api, endpoint)

Create Python objects from NetBox API responses.

Creates an object from a NetBox response passed as values. Nested dicts that represent other endpoints are also turned into Record objects. All fields are then assigned to the object’s attributes. If a missing attr is requested (e.g. requesting a field that’s only present on a full response on a Record made from a nested response) then pynetbox will make a request for the full object and return the requested value.

Examples:

Default representation of the object is usually its name:

>>> x = nb.dcim.devices.get(1)
>>> x
test1-switch1
>>>

Querying a string field:

>>> x = nb.dcim.devices.get(1)
>>> x.serial
'ABC123'
>>>

Querying a field on a nested object:

>>> x = nb.dcim.devices.get(1)
>>> x.device_type.model
'QFX5100-24Q'
>>>

Casting the object as a dictionary:

>>> from pprint import pprint
>>> pprint(dict(x))
{'asset_tag': None,
 'cluster': None,
 'comments': '',
 'config_context': {},
 'created': '2018-04-01',
 'custom_fields': {},
 'role': {'id': 1,
                 'name': 'Test Switch',
                 'slug': 'test-switch',
                 'url': 'http://localhost:8000/api/dcim/device-roles/1/'},
 'device_type': {...},
 'display_name': 'test1-switch1',
 'face': {'label': 'Rear', 'value': 1},
 'id': 1,
 'name': 'test1-switch1',
 'parent_device': None,
 'platform': {...},
 'position': 1,
 'primary_ip': {'address': '192.0.2.1/24',
                'family': 4,
                'id': 1,
                'url': 'http://localhost:8000/api/ipam/ip-addresses/1/'},
 'primary_ip4': {...},
 'primary_ip6': None,
 'rack': {'display_name': 'Test Rack',
          'id': 1,
          'name': 'Test Rack',
          'url': 'http://localhost:8000/api/dcim/racks/1/'},
 'serial': 'ABC123',
 'site': {'id': 1,
          'name': 'TEST',
          'slug': 'TEST',
          'url': 'http://localhost:8000/api/dcim/sites/1/'},
 'status': {'label': 'Active', 'value': 1},
 'tags': [],
 'tenant': None,
 'vc_position': None,
 'vc_priority': None,
 'virtual_chassis': None}
 >>>

Iterating over a Record object:

>>> for i in x:
...  print(i)
...
('id', 1)
('name', 'test1-switch1')
('display_name', 'test1-switch1')
>>>

delete()

Deletes an existing object.

Returns:

True if DELETE operation was successful.

Example:

>>> x = nb.dcim.devices.get(name='test1-a3-tor1b')
>>> x.delete()
True
>>>

full_details()

Queries the hyperlinked endpoint if ‘url’ is defined.

This method will populate the attributes from the detail endpoint when it’s called. Sets the class-level has_details attribute when it’s called to prevent being called more than once.

Returns:

True

save()

Saves changes to an existing object.

Takes a diff between the objects current state and its state at init and sends them as a dictionary to Request.patch().

Returns:

True if PATCH request was successful.

Example:

>>> x = nb.dcim.devices.get(name='test1-a3-tor1b')
>>> x.serial
''
>>> x.serial = '1234'
>>> x.save()
True
>>>

serialize(nested=False, init=False)

Serializes an object

Pulls all the attributes in an object and creates a dict that can be turned into the json that netbox is expecting.

If an attribute’s value is a Record type it’s replaced with the id field of that object.

Note

Using this to get a dictionary representation of the record is discouraged. It’s probably better to cast to dict() instead. See Record docstring for example.

Returns:

dict.

update(data)

Update an object with a dictionary.

Accepts a dict and uses it to update the record and call save(). For nested and choice fields you’d pass an int the same as if you were modifying the attribute and calling save().

Parameters:

data (dict) – Dictionary containing the k/v to update the record object with.

Returns:

True if PATCH request was successful.

Example:

>>> x = nb.dcim.devices.get(1)
>>> x.update({
...   "name": "test-switch2",
...   "serial": "ABC321",
... })
True

updates()

Compiles changes for an existing object into a dict.

Takes a diff between the objects current state and its state at init and returns them as a dictionary, which will be empty if no changes.

Returns:

dict.

Example:

>>> x = nb.dcim.devices.get(name='test1-a3-tor1b')
>>> x.serial
''
>>> x.serial = '1234'
>>> x.updates()
{'serial': '1234'}
>>>

class pynetbox.core.response.RecordSet(endpoint, request, **kwargs)

Iterator containing Record objects.

Returned by Endpoint.all() and Endpoint.filter() methods. Allows iteration of and actions to be taken on the results from the aforementioned methods. Contains Record objects.

Examples:

To see how many results are in a query by calling len():

>>> x = nb.dcim.devices.all()
>>> len(x)
123
>>>

Simple iteration of the results:

>>> devices = nb.dcim.devices.all()
>>> for device in devices:
...     print(device.name)
...
test1-leaf1
test1-leaf2
test1-leaf3
>>>

delete()

Bulk deletes objects in a RecordSet.

Allows for batch deletion of multiple objects in a RecordSet

Returns:

True if bulk DELETE operation was successful.

Examples:

Deleting offline devices on site 1:

>>> netbox.dcim.devices.filter(site_id=1, status="offline").delete()
>>>

update(**kwargs)

Updates kwargs onto all Records in the RecordSet and saves these.

Updates are only sent to the API if a value were changed, and only for the Records which were changed

Returns:

True if the update succeeded, None if no update were required

Example:

>>> result = nb.dcim.devices.filter(site_id=1).update(status='active')
True
>>>