Python API¶
Database Primitives¶
Models¶
-
class
nsot.models.
Assignment
(*args, **kwargs)[source]¶ DB object for assignment of addresses to interfaces (on devices).
This is used to enforce constraints at the relationship level for addition of new address assignments.
-
class
nsot.models.
Attribute
(*args, **kwargs)[source]¶ Represents a flexible attribute for Resource objects.
-
class
nsot.models.
Change
(*args, **kwargs)[source]¶ Record of all changes in NSoT.
-
diff
¶ Return the diff of the JSON representation of the cached copy of a Resource with its current instance
-
-
class
nsot.models.
Circuit
(*args, **kwargs)[source]¶ Represents two network Interfaces that are connected
-
addresses
¶ Return addresses associated with this circuit.
-
devices
¶ Return devices associated with this circuit.
-
interface_for
(device)[source]¶ Given a Device object, return the interface attached to this Circuit which belongs to that Device. If both ends of the Circuit are attached to the Device, the A-side is returned.
If neither ends of this Circuit are attached to Device, then None is returned
-
interfaces
¶ Return interfaces associated with this circuit.
-
-
class
nsot.models.
Device
(*args, **kwargs)[source]¶ Represents a network device.
-
circuits
¶ All circuits related to this Device.
-
-
class
nsot.models.
Interface
(*args, **kwargs)[source]¶ A network interface.
-
assign_address
(cidr)[source]¶ Assign an address to this interface.
Must have prefix of /32 (IPv4) or /128 (IPv6).
Parameters: cidr – IPv4/v6 CIDR host address or Network object
-
circuit
¶ Return the Circuit I am associated with
-
networks
¶ Return all the parent Networks for my addresses.
-
-
class
nsot.models.
Network
(*args, **kwargs)[source]¶ Represents a subnet or IP address.
-
get_next_address
(num=None, strict=False, as_objects=True)[source]¶ Return a list of the next available addresses.
If no addresses are available, an empty list will be returned.
Parameters: - num – The number of addresses desired
- as_objects – Whether to return IPNetwork objects or strings
-
get_next_network
(prefix_length, num=None, strict=False, as_objects=True)[source]¶ Return a list of the next available networks.
If no networks are available, an empty list will be returned.
Parameters: - prefix_length – The prefix length of networks
- num – The number of networks desired
- as_objects – Whether to return IPNetwork objects or strings
- strict – Whether to return networks for strict allocation
Returns: list(IPNetwork)
-
-
class
nsot.models.
Protocol
(*args, **kwargs)[source]¶ Representation of a routing protocol
-
clean_interface
(value)[source]¶ Ensure that the interface is bound to the same device this Protocol is bound to.
-
-
class
nsot.models.
ProtocolType
(*args, **kwargs)[source]¶ Representation of protocol types (e.g. bgp, is-is, ospf, etc.)
Fields¶
-
class
nsot.fields.
BinaryIPAddressField
(*args, **kwargs)[source]¶ IP Address field that stores values as varbinary.
Validators¶
Validators for validating object fields.
Exceptions¶
-
exception
nsot.exc.
ModelError
(detail=None, code=None)[source]¶ Base class for NSoT Model Exceptions.
HTTP 401 error.
-
nsot.exc.
DjangoValidationError
¶ alias of
ValidationError
REST API Primitives¶
Views¶
-
class
nsot.api.views.
AttributeViewSet
(**kwargs)[source]¶ API endpoint that allows Attributes to be viewed or edited.
-
serializer_class
¶ alias of
AttributeSerializer
-
-
class
nsot.api.views.
BaseNsotViewSet
(**kwargs)[source]¶ Default viewset for Nsot objects with the following defaults:
- Objects are designed to be nested under site resources, but can also be top-level resources.
-
get_natural_key_kwargs
(filter_value)[source]¶ This method should take value and return a dictionary containing the natural key fields used to filter results.
This is called internally by
self.get_object()
if a subclass has defined anatural_key
.Parameters: filter_value – Value to be used to filter by natural_key
-
get_object
()[source]¶ Enhanced default to support looking up objects for:
- Natural key lookups for resource objects (e.g. Device.hostname)
- Inject of
site
into filter lookup ifsite_pk
is set.
Currently this does NOT filter the queryset, which should not be a problem as we were never using .get_object() before. See the FIXME comments for more context.
-
list
(request, site_pk=None, queryset=None, *args, **kwargs)[source]¶ List objects optionally filtered by site.
-
natural_key
= None¶ Natural key for the resource. If not defined, defaults to pk-only.
-
class
nsot.api.views.
ChangeViewSet
(**kwargs)[source]¶ Read-only API endpoint that allows Changes to be viewed.
All Create/Update/Delete events are logged as a Change. A Change includes information such as the change time, user, and the full resource after modification. Changes are immutable and can only be removed by deleting the entire Site.
-
serializer_class
¶ alias of
ChangeSerializer
-
-
class
nsot.api.views.
CircuitViewSet
(**kwargs)[source]¶ API endpoint that allows Circuits to be viewed or edited.
-
addresses
(request, pk=None, site_pk=None, *args, **kwargs)[source]¶ Return a list of addresses for the interfaces on this Circuit.
-
bulk_update
(request, *args, **kwargs)[source]¶ Workaround for bulk update of objects with unique constraint.
At this time this is only required by the Circuit object, which is why it is only defined here.
Credit: https://github.com/miki725/django-rest-framework-bulk/issues/30 Source: http://bit.ly/2HcyNnG
-
devices
(request, pk=None, site_pk=None, *args, **kwargs)[source]¶ Return a list of devices for this Circuit.
-
filter_class
¶ alias of
CircuitFilter
-
interfaces
(request, pk=None, site_pk=None, *args, **kwargs)[source]¶ Return a list of interfaces for this Circuit.
-
serializer_class
¶ alias of
CircuitSerializer
-
-
class
nsot.api.views.
DeviceViewSet
(**kwargs)[source]¶ API endpoint that allows Devices to be viewed or edited.
-
circuits
(request, pk=None, site_pk=None, *args, **kwargs)[source]¶ Return a list of Circuits for this Device
-
filter_class
¶ alias of
DeviceFilter
-
interfaces
(request, pk=None, site_pk=None, *args, **kwargs)[source]¶ Return all interfaces for this Device.
-
serializer_class
¶ alias of
DeviceSerializer
-
-
class
nsot.api.views.
InterfaceViewSet
(**kwargs)[source]¶ API endpoint that allows Interfaces to be viewed or edited.
-
addresses
(request, pk=None, site_pk=None, *args, **kwargs)[source]¶ Return a list of addresses for this Interface.
-
ancestors
(request, pk=None, site_pk=None, *args, **kwargs)[source]¶ Return all the ancestors of this Interface.
-
assignments
(request, pk=None, site_pk=None, *args, **kwargs)[source]¶ Return a list of information about my assigned addresses.
-
children
(request, pk=None, site_pk=None, *args, **kwargs)[source]¶ Return all the immediate children of this Interface.
-
circuit
(request, pk=None, site_pk=None, *args, **kwargs)[source]¶ Return the Circuit I am associated with
-
descendants
(request, pk=None, site_pk=None, *args, **kwargs)[source]¶ Return all the descendants of this Interface.
-
filter_class
¶ alias of
InterfaceFilter
-
networks
(request, pk=None, site_pk=None, *args, **kwargs)[source]¶ Return all the containing Networks for my assigned addresses.
-
parent
(request, pk=None, site_pk=None, *args, **kwargs)[source]¶ Return the parent of this Interface.
-
root
(request, pk=None, site_pk=None, *args, **kwargs)[source]¶ Return the root of the tree this Interface is part of.
-
serializer_class
¶ alias of
InterfaceSerializer
-
-
class
nsot.api.views.
NetworkViewSet
(**kwargs)[source]¶ API endpoint that allows Networks to be viewed or edited.
-
ancestors
(request, pk=None, site_pk=None, *args, **kwargs)[source]¶ Return ancestors of this Network.
-
assignments
(request, pk=None, site_pk=None, *args, **kwargs)[source]¶ Return the interface assignments for this Network.
-
children
(request, pk=None, site_pk=None, *args, **kwargs)[source]¶ Return the immediate children of this Network.
-
closest_parent
(request, pk=None, site_pk=None, *args, **kwargs)[source]¶ Return the closest matching parent of this Network even if it doesn’t exist in the database.
-
descendants
(request, pk=None, site_pk=None, *args, **kwargs)[source]¶ Return descendants of this Network.
-
descendents
(request, pk=None, site_pk=None, *args, **kwargs)[source]¶ Return descendants of this Network.
Deprecated since version 1.1.
This endpoint is pending deprecation. Use the
descendants
endpoint instead.
-
filter_class
¶ alias of
NetworkFilter
-
next_address
(request, pk=None, site_pk=None, *args, **kwargs)[source]¶ Return next available IPs from this Network.
-
next_network
(request, pk=None, site_pk=None, *args, **kwargs)[source]¶ Return next available networks from this Network.
-
query
(request, site_pk=None, *args, **kwargs)[source]¶ Override base query to inherit filtering by query params.
-
root
(request, pk=None, site_pk=None, *args, **kwargs)[source]¶ Return the parent of all ancestors for this Network.
-
serializer_class
¶ alias of
NetworkSerializer
-
-
class
nsot.api.views.
NsotBulkUpdateModelMixin
[source]¶ The default mixin isn’t using super() so multiple-inheritance breaks. This fixes it for our use-case.
-
class
nsot.api.views.
NsotViewSet
(**kwargs)[source]¶ Generic mutable viewset that logs all change events and includes support for bulk creation of objects.
-
get_success_headers
(data)[source]¶ Overload default to include relative request PATH.
Parameters: data – Dict of validated serializer data
-
perform_create
(serializer)[source]¶ Support bulk create.
Parameters: serializer – Serializer instance
-
-
class
nsot.api.views.
ProtocolTypeViewSet
(**kwargs)[source]¶ API endpoint that allows ProtocolTypes to be viewed or edited.
-
filter_class
¶ alias of
ProtocolTypeFilter
-
serializer_class
¶ alias of
ProtocolTypeSerializer
-
-
class
nsot.api.views.
ProtocolViewSet
(**kwargs)[source]¶ API endpoint that allows Protocols to be viewed or edited.
-
filter_class
¶ alias of
ProtocolFilter
-
serializer_class
¶ alias of
ProtocolSerializer
-
-
class
nsot.api.views.
ResourceViewSet
(**kwargs)[source]¶ Resource views that include set query list endpoints.
-
class
nsot.api.views.
SiteViewSet
(**kwargs)[source]¶ API endpoint that allows Sites to be viewed or edited.
-
class
nsot.api.views.
UserPkInfo
(user, pk)¶ Namedtuple for retrieving pk and user object of current user.
-
pk
¶ Alias for field number 1
-
user
¶ Alias for field number 0
-
Serializers¶
-
class
nsot.api.serializers.
AttributeCreateSerializer
(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶ Used for POST on Attributes.
-
class
nsot.api.serializers.
AttributeSerializer
(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶ Used for GET, DELETE on Attributes.
-
class
nsot.api.serializers.
AttributeUpdateSerializer
(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶ Used for PUT, PATCH, on Attributes.
Currently because Attributes have only one required field (name), and it may not be updated, there is not much functional difference between PUT and PATCH.
-
class
nsot.api.serializers.
AuthTokenSerializer
(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶ AuthToken authentication serializer to validate username/secret_key inputs.
-
class
nsot.api.serializers.
ChangeSerializer
(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶ Used for displaying Change events.
-
class
nsot.api.serializers.
CircuitCreateSerializer
(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶ Used for POST on Circuits.
-
class
nsot.api.serializers.
CircuitPartialUpdateSerializer
(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶ Used for PATCH on Circuits.
-
class
nsot.api.serializers.
CircuitSerializer
(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶ Used for GET, DELETE on Circuits
-
class
nsot.api.serializers.
CircuitUpdateSerializer
(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶ Used for PUT on Circuits.
-
class
nsot.api.serializers.
DeviceCreateSerializer
(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶ Used for POST on Devices.
-
class
nsot.api.serializers.
DevicePartialUpdateSerializer
(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶ Used for PATCH on Devices.
-
class
nsot.api.serializers.
DeviceSerializer
(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶ Used for GET, DELETE on Devices.
-
class
nsot.api.serializers.
DeviceUpdateSerializer
(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶ Used for PUT on Devices.
-
class
nsot.api.serializers.
InterfaceCreateSerializer
(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶ Used for POST on Interfaces.
-
class
nsot.api.serializers.
InterfacePartialUpdateSerializer
(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶ Used for PATCH on Interfaces.
-
class
nsot.api.serializers.
InterfaceSerializer
(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶ Used for GET, DELETE on Interfaces.
-
class
nsot.api.serializers.
InterfaceUpdateSerializer
(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶ Used for PUT on Interfaces.
-
class
nsot.api.serializers.
JSONDataField
(read_only=False, write_only=False, required=None, default=<class rest_framework.fields.empty>, initial=<class rest_framework.fields.empty>, source=None, label=None, help_text=None, style=None, error_messages=None, validators=None, allow_null=False)[source]¶ Base field used to represent attributes as JSON <->
field_type
.It is an error if
field_type
is not defined in a subclass.
-
class
nsot.api.serializers.
JSONDictField
(read_only=False, write_only=False, required=None, default=<class rest_framework.fields.empty>, initial=<class rest_framework.fields.empty>, source=None, label=None, help_text=None, style=None, error_messages=None, validators=None, allow_null=False)[source]¶ Field used to represent attributes as JSON <-> Dict.
-
field_type
¶ alias of
dict
-
-
class
nsot.api.serializers.
JSONListField
(read_only=False, write_only=False, required=None, default=<class rest_framework.fields.empty>, initial=<class rest_framework.fields.empty>, source=None, label=None, help_text=None, style=None, error_messages=None, validators=None, allow_null=False)[source]¶ Field used to represent attributes as JSON <-> List.
-
field_type
¶ alias of
list
-
-
class
nsot.api.serializers.
MACAddressField
(read_only=False, write_only=False, required=None, default=<class rest_framework.fields.empty>, initial=<class rest_framework.fields.empty>, source=None, label=None, help_text=None, style=None, error_messages=None, validators=None, allow_null=False)[source]¶ Field used to validate MAC address objects as integer or string.
-
class
nsot.api.serializers.
NaturalKeyRelatedField
(slug_field=None, **kwargs)[source]¶ Field that takes either a primary key or a natural key.
-
class
nsot.api.serializers.
NetworkCreateSerializer
(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶ Used for POST on Networks.
-
class
nsot.api.serializers.
NetworkPartialUpdateSerializer
(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶ Used for PATCH on Networks.
-
class
nsot.api.serializers.
NetworkSerializer
(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶ Used for GET, DELETE on Networks.
-
class
nsot.api.serializers.
NetworkUpdateSerializer
(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶ Used for PUT on Networks.
-
class
nsot.api.serializers.
NsotSerializer
(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶ Base serializer that logs change events.
-
class
nsot.api.serializers.
ProtocolCreateSerializer
(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶ Used for POST on Protocols.
-
class
nsot.api.serializers.
ProtocolPartialUpdateSerializer
(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶ Used for PATCH on Protocols.
-
class
nsot.api.serializers.
ProtocolSerializer
(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶ Used for GET, DELETE on Protocols
-
class
nsot.api.serializers.
ProtocolTypeSerializer
(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶ Used for all CRUD operations on ProtocolTypes.
-
class
nsot.api.serializers.
ProtocolUpdateSerializer
(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶ Used for PUT on Protocols.
-
class
nsot.api.serializers.
ResourceSerializer
(instance=None, data=<class rest_framework.fields.empty>, **kwargs)[source]¶ For any object that can have attributes.
-
class
nsot.api.serializers.
UserSerializer
(*args, **kwargs)[source]¶ UserProxy model serializer that takes optional with_secret_key argument that controls whether the secret_key for the user should be displayed.
Filters¶
-
class
nsot.api.filters.
CircuitFilter
(data=None, queryset=None, prefix=None, strict=None, request=None)[source]¶ Filter for Circuit objects.
-
class
nsot.api.filters.
DeviceFilter
(data=None, queryset=None, prefix=None, strict=None, request=None)[source]¶ Filter for Device objects.
-
class
nsot.api.filters.
InterfaceFilter
(data=None, queryset=None, prefix=None, strict=None, request=None)[source]¶ Filter for Interface objects.
Includes a custom override for filtering on mac_address because this is not a Django built-in field.
-
class
nsot.api.filters.
NetworkFilter
(data=None, queryset=None, prefix=None, strict=None, request=None)[source]¶ Filter for Network objects.
-
class
nsot.api.filters.
ProtocolFilter
(data=None, queryset=None, prefix=None, strict=None, request=None)[source]¶ Filter for Protocol objects.
-
class
nsot.api.filters.
ProtocolTypeFilter
(data=None, queryset=None, prefix=None, strict=None, request=None)[source]¶ Filter for ProtocolType (non-resource) objects.
Utilities¶
Utilities used across the project.
-
nsot.util.
qpbool
(arg)[source]¶ Convert “truthy” strings into Booleans.
>>> qpbool('true') True
Parameters: arg – Truthy string
-
nsot.util.
normalize_auth_header
(header)[source]¶ Normalize a header name into WSGI-compatible format.
>>> normalize_auth_header('X-NSoT-Email') 'HTTP_X_NSOT_EMAIL'
Parameters: header – Header name
-
nsot.util.
generate_secret_key
()[source]¶ Return a secret key suitable for use w/ Fernet.
>>> generate_secret_key() '1BpuqeM5d5pi-U2vIsqeQ8YnTrXRRUAfqV-hu6eQ5Gw='
-
nsot.util.
get_field_attr
(model, field_name, attr_name)[source]¶ Return the specified attribute value from a model field.
This is used for field overrides in API serializers to retrieve the
verbose_name
andhelp_text
model field attributes so they don’t need to be duplicated in code.Example:
>>> get_field_attr(models.Interface, 'parent', 'help_text') 'Unique ID of the parent Interface.'
Parameters: - model – Model class
- field_name – Model field name
- attr_name – Model field attribute name
-
class
nsot.util.
SetQuery
(action, name, value)¶ -
action
¶ Alias for field number 0
-
name
¶ Alias for field number 1
-
value
¶ Alias for field number 2
-
-
nsot.util.
parse_set_query
(query)[source]¶ Parse a representation of set operations for attribute/value pairs into (action, name, value) and return a list of
SetQuery
objects.Computes left-to-right evaluation, where the first character indicates the set operation:
- “+” indicates a union
- “-” indicates a difference
- no marker indicates an intersection
For example:
>>> parse_set_query('+owner=team-networking') [SetQuery(action='union', name='owner', value='team-networking')] >>> parse_set_query('foo=bar') [SetQuery(action='intersection', name='foo', value='bar')] >>> parse_set_query('foo=bar -owner=team-networking') [SetQuery(action='intersection', name='foo', value='bar'), SetQuery(action='difference', name='owner', value='team-networking')]
Parameters: query – Set query string
-
nsot.util.
generate_settings
(config_template=None)[source]¶ Used to emit a generated configuration from
config_template
.Parameters: config_template – Config template
-
nsot.util.
initialize_app
(config)[source]¶ Actions to be performed prior to creating the Application object.
Parameters: config – Config object
-
nsot.util.
cidr_to_dict
(cidr)[source]¶ Take a cidr and return it as a dictionary.
>>> cidr_to_dict('192.168.0.0/16') {'network_address': '192.168.0.0', 'prefix_length': 16}
Parameters: cidr – IPv4/IPv6 CIDR string
-
nsot.util.
slugify
(s)[source]¶ Slugify a string.
This works in a less-agressive manner than Django’s slugify, which simply drops most drops most non-alphanumeric characters and lowercases the entire string. It would likely to cause uniqueness conflicts for things like interface names, such as Eth1/2/3 and Eth12/3, which would slugify to be the same.
>>> slugify('switch-foo01:Ethernet1/2') 'switch-foo01:Ethernet1_2'
Parameters: s – String to slugify
-
nsot.util.
slugify_interface
(interface=None, device_hostname=None, name=None, **kwargs)[source]¶ Return a slug (natural key) representation of an Interface.
If
interface
is not provided,device_hostname
andname
are required. If all are provided,interface
will take precedence.Parameters: - interface – Interface dict
- device_hostname – Device hostname
- name – Interface name
Return type: str