def save(self):
"""Saves changes to an existing object.
Runs self.serialize() and checks that it doesn't match
self._compare(). If not create a Request object and run .put()
:returns: True if PUT request was successful.
:example:
>>> x = nb.dcim.devices.get(name='test1-a3-tor1b')
>>> x.serial
u''
>>> x.serial = '1234'
>>> x.save()
True
>>>
"""
if self.id:
if not self._compare():
req = Request(key=self.id,
base=self.endpoint_meta.get('url'),
token=self.api_kwargs.get('token'),
session_key=self.api_kwargs.get('session_key'),
version=self.api_kwargs.get('version'),
ssl_verify=self.api_kwargs.get('ssl_verify'))
if req.put(self.serialize()):
return True
else:
return False
def all(self):
"""Queries the 'ListView' of a given endpoint.
Returns all objects from an endpoint.
:Returns: List of instantiated objects.
:Examples:
>>> nb.dcim.devices.all()
[test1-a3-oobsw2, test1-a3-oobsw3, test1-a3-oobsw4]
>>>
"""
req = Request(
base='{}/'.format(self.url),
token=self.token,
session_key=self.session_key,
version=self.version,
ssl_verify=self.ssl_verify,
)
ret_kwargs = dict(
api_kwargs=self.api_kwargs,
endpoint_meta=self.meta,
)
return [
self.return_obj(i, **ret_kwargs)
for i in req.get()
]
def filter(self, *args, **kwargs):
r"""Queries the 'ListView' of a given endpoint.
Takes named arguments that match the usable filters on a
given endpoint. If an argument is passed then it's used as a
freeform search argument if the endpoint supports it.
:arg str,optional \*args: Freeform search string that's
accepted on given endpoint.
:arg str,optional \**kwargs: Any search argument the
endpoint accepts can be added as a keyword arg.
:Returns: A list of instantiated objects.
:Examples:
To return a list of objects matching a named argument filter.
>>> nb.dcim.devices.filter(role='leaf-switch')
[test1-a3-tor1b, test1-a3-tor1c, test1-a3-tor1d, test1-a3-tor2a]
>>>
Using a freeform query along with a named argument.
>>> nb.dcim.devices.filter('a3', role='leaf-switch')
[test1-a3-tor1b, test1-a3-tor1c, test1-a3-tor1d, test1-a3-tor2a]
>>>
Chaining multiple named arguments.
>>> nb.dcim.devices.filter(role='leaf-switch', status=True)
[test1-leaf2]
>>>
Passing a list as a named argument adds multiple filters of the
same value.
>>> nb.dcim.devices.filter(role=['leaf-switch', 'spine-switch'])
[test1-a3-spine1, test1-a3-spine2, test1-a3-leaf1]
>>>
"""
if len(args) > 0:
kwargs.update({'q': args[0]})
req = Request(
filters=kwargs,
base=self.url,
token=self.token,
session_key=self.session_key,
version=self.version,
ssl_verify=self.ssl_verify,
)
ret_kwargs = dict(
api_kwargs=self.api_kwargs,
endpoint_meta=self.meta,
)
ret = [self.return_obj(i, **ret_kwargs) for i in req.get()]
return ret
def get(self, *args, **kwargs):
r"""Queries the DetailsView of a given endpoint.
:arg int,optional key: id for the item to be
retrieved.
:arg str,optional \**kwargs: Accepts the same keyword args as
filter(). Any search argeter the endpoint accepts can
be added as a keyword arg.
:returns: A single instantiated objects.
:raises ValueError: if kwarg search return more than one value.
:Examples:
Referencing with a kwarg that only returns one value.
>>> nb.dcim.devices.get(name='test1-a3-tor1b')
test1-a3-tor1b
>>>
Referencing with an id.
>>> nb.dcim.devices.get(1)
test1-edge1
>>>
"""
try:
key = args[0]
except IndexError:
key = None
if not key:
filter_lookup = self.filter(**kwargs)
if len(filter_lookup) == 1:
return filter_lookup[0]
if len(filter_lookup) == 0:
return None
else:
raise ValueError('get() returned more than one result.')
req = Request(
key=key,
base=self.url,
token=self.token,
session_key=self.session_key,
version=self.version,
ssl_verify=self.ssl_verify,
)
ret_kwargs = dict(
api_kwargs=self.api_kwargs,
endpoint_meta=self.meta,
)
return self.return_obj(req.get(), **ret_kwargs)
def _create(self, data):
"""Base create method
Used in .create() and .bulk_create()
"""
req = Request(
base=self.url,
token=self.token,
session_key=self.session_key,
version=self.version,
)
post = req.post(data)
if post:
return post['id']
else:
return False
def full_details(self):
"""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
"""
if self.url:
req = Request(base=self.url,
version=self.api_kwargs.get('version'))
self._parse_values(req.get())
self.has_details = True
return True
return False
def create(self, *args, **kwargs):
r"""Creates an object on an endpoint.
Allows for the creation of new objects on an endpoint. Named
arguments are converted to json properties, and a single object
is created. NetBox's bulk creation capabilities can be used by
passing a list of dictionaries as the first argument.
.. note:
Any positional arguments will supercede named ones.
:arg list \*args: A list of dictionaries containing the
properties of the objects to be created.
:arg str \**kwargs: key/value strings representing
properties on a json object.
:returns: A response from NetBox as a dictionary or list of
dictionaries.
:Examples:
Creating an object on the `devices` endpoint you can lookup a
device_role's name with:
>>> netbox.dcim.devices.create(
... name='test',
... device_role=1,
... )
>>>
Use bulk creation by passing a list of dictionaries:
>>> nb.dcim.devices.create([
... {
... "name": "test1-core3",
... "device_role": 3,
... "site": 1,
... "device_type": 1,
... "status": 1
... },
... {
... "name": "test1-core4",
... "device_role": 3,
... "site": 1,
... "device_type": 1,
... "status": 1
... }
... ])
"""
return Request(
base=self.url,
token=self.token,
session_key=self.session_key,
version=self.version,
ssl_verify=self.ssl_verify,
).post(args[0] if len(args) > 0 else kwargs)
def list(self):
"""The view operation for a detail endpoint
Returns the response from NetBox for a detail endpoint.
:returns: A dictionary or list of dictionaries its retrieved
from NetBox.
"""
return Request(**self.request_kwargs).get()
def delete(self):
"""Deletes an existing object.
:returns: True if DELETE operation was successful.
:example:
>>> x = nb.dcim.devices.get(name='test1-a3-tor1b')
>>> x.delete()
True
>>>
"""
req = Request(key=self.id,
base=self.endpoint_meta.get('url'),
token=self.api_kwargs.get('token'),
session_key=self.api_kwargs.get('session_key'),
version=self.api_kwargs.get('version'))
if req.delete():
return True
else:
return False
def create(self, data={}):
"""The write operation for a detail endpoint.
Creates objects on a detail endpoint in NetBox.
:arg dict/list,optional data: A dictionary containing the
key/value pair of the items you're creating on the parent
object. Defaults to empty dict which will create a single
item with default values.
:returns: A dictionary or list of dictionaries its created in
NetBox.
"""
return Request(**self.request_kwargs).post(data)
def list(self, **kwargs):
r"""The view operation for a detail endpoint
Returns the response from NetBox for a detail endpoint.
:args \**kwargs: key/value pairs that get converted into url
parameters when passed to the endpoint.
E.g. ``.list(method='get_facts')`` would be converted to
``.../?method=get_facts``.
:returns: A dictionary or list of dictionaries its retrieved
from NetBox.
"""
if kwargs:
self.request_kwargs['base'] = '{}{}'.format(
self.url, url_param_builder(kwargs))
return Request(**self.request_kwargs).get()
def update(self, *args, **kwargs):
"""Updates an object on an endpoint.
:arg int,optional key: id for the item to be
updated. Can
:arg str,optional \**kwargs: Accepts the same keyword args as
filter(). Any search argeter the endpoint accepts can
be added as a keyword arg.
:returns: A single updated object.
:raises ValueError: If ID is not passed as a poitional arg, a value in a dict or as a kwarg
:Examples:
Update a device, given a device with ID of "10"
If using positional args, ID must be first
>>> nb.dcim.devices.update(10, {'name': 'mydevice'})
mydevice
>>>
Using kwargs
>>> nb.devices.update(id=10, name='mydevice')
mydevice
>>>
Using a dict
>>> nb.devices.update({'id': 10, 'name': 'mydevice'})
mydevice
>>>
"""
key = None
upd = None
if len(args) == 1:
if isinstance(args[0], dict):
if 'id' in args[0]:
key = args[0].pop('id')
upd = args[0]
elif len(args) > 1:
try:
key = int(args[0])
upd = args[1]
except ValueError:
key = None
elif 'id' in kwargs:
key = kwargs.pop('id')
upd = kwargs
if not key:
raise ValueError('No ID in provided args')
if not upd:
raise ValueError("No update data")
return Request(key=key,
base=self.url,
token=self.token,
session_key=self.session_key,
version=self.version,
ssl_verify=self.ssl_verify).patch(upd)
