nautobot 2.0.4__py3-none-any.whl → 2.1.0b1__py3-none-any.whl

nautobot/docs/user-guide/platform-functionality/relationship.md

@@ -1,158 +0,0 @@
-# Relationships
-
-Sometimes it is desirable to create a new kind of relationship between one (or more) objects in your source of truth to reflect business logic or other relationships that may be useful to you but that haven't been defined. This is where the Relationships feature comes in: like defining custom fields to hold attributes specific to your use cases, relationships define specific links between objects that might be specific to your network or data.
-
-To create a relationship, from the top-level navigation menu select **Extensibility > Data Management > Relationships**
-
-!!! tip
-    Because relationship information can be included in the REST API and in GraphQL, when defining a relationship, you must provide a `key` that contains underscores rather than dashes (`my_relationship_key`, not `my-relationship-key`), as some features would not work optimally if dashes are included in the key. If not explicitly specified, the `key` attribute is derived from the `label` attribute (unique for all Relationship instances).
-
-## Relationship Types
-
-* **Many-to-many** - where both sides of the relationship connection can be connected to multiple objects. For example, VLANs can be connected to multiple devices and devices will have multiple VLANs.
-* **One-to-many** - where one side of the connection can only have one object. For example, where a controller has many supplicants like FEX and parent switch. A FEX can be uplinked to one parent switch (in most cases), but the parent switch can have many FEX.
-* **One-to-one** - where there can be only one object on either side of the relationship. For example, an IP address serving as a router-id for a device. Each device has at most one router-id, and each IP address can be a router-id for at most one device.
-
-+++ 1.2.0
-    Additionally, there are two _symmetric_ relationship types that can be used when defining a relationship between objects of the same type. These relationship types treat the two _sides_ of a relationship as interchangeable (much like the A/Z sides of a circuit, or the endpoints of a cable) rather than distinguishing between the _source_ and _destination_ of a relationship as the non-symmetric relationship types above do.
-
-    * **Symmetric Many-to-many** - as in Many-to-many, but acting more as an _undirected graph_ of similar objects. For example, this could be used to define a set of devices participating in a routing topology, where each device has some number of peers and there's no distinction between _source_ and _destination_ peers.
-    * **Symmetric One-to-one** - as in One-to-one, but defining a relationship between exactly two objects of the same type. For example, a HSRP/VRRP pair of redundant devices, where each device has exactly one peer device.
-
-!!! note
-    A symmetric many-to-many relationship can be, but is not necessarily, a _complete graph_ or _full mesh_. For example, in the routing topology example above, if Device _A_ and Device _B_ are peers, and Device _B_ and Device _C_ are peers, this does not automatically imply a relationship between Devices _A_ and _C_ -- they **might or might not** also be peers, depending on how you define and populate the specific associations for this relationship.
-
-## Required Relationships
-
-+++ 1.5.0
-
-Relationships can be marked as being required. By default, relationships are not marked as being required.
-
-To mark a relationship as being required, select "Source objects MUST implement this relationship" or conversely "Destination objects MUST implement this relationship" from the "Required on" field when editing or creating a relationship:
-
-* If "Destination objects MUST implement this relationship" is selected, objects of the type selected in "Destination Type" will enforce this relationship when they are created or edited.
-* If "Source objects MUST implement this relationship" is selected, objects of the type selected in "Source Type" will enforce this relationship when they are created or edited.
-
-Required relationships are enforced in the following scenarios:
-
-* Creating or editing an object via the API or the UI
-* Bulk creating objects via the API
-* Bulk editing objects via the API or the UI
-
-## Relationship Filters
-
-Filters can be defined to restrict the type or selection of objects for either side of the connection.
-
-An important note is that the filters have to be defined in **FilterSet** rather than QuerySet format. In practice this means that you can use any of the filters that are valid in the REST API for a given object type, but cannot necessarily use complex nested attribute lookups (such as `interfaces__ip_addresses__mask_length` on a Device, for example).
-
-As an example, let's create a relationship between Circuits and Devices.
-In our situation we only would terminate Circuits on Devices with the Device Role of `edge`.
-
-To prevent the Circuit Relationship from showing up on any other Device, use a JSON filter to limit the Relationship to only Devices with a Role named `Edge`:
-
-```json
-{
-    "role": [
-        "Edge"
-    ]
-}
-```
-
-!!! note
-    There are a few ways to tell what attributes are available to filter on for a given object.
-    In the case of the _Device_ object used in the example, the user could:
-
-    - look at the code `nautobot/dcim/filters.py` -> `DeviceFilterSet` class (available options there include `manufacturer_id`, `manufacturer`, etc)
-    - check the filter options available in the REST API: `https://<server-name>/api/docs`, and in this case checking the `dcim_devices_list` API endpoint for the parameter names
-
-For context, here is an image of the entire Relationship:
-
-![Image of Relationship with json filter](../../img/relationship_w_json_filter.png)
-
-Now, the Circuit Relationship field will show up on a Device with an `edge` role:
-
-![Image of Edge Device Relationships](../../img/edge_dev_circuit_relationship.png)
-
-The Circuit Relationship field will _not_ show up on a Device with a role `leaf`:
-
-![Image of Leaf Device Relationships](../../img/leaf_dev_no_circuit_relationship.png)
-
-## Relationship Labels
-
-Relationship connections can be labeled with a friendly name so that when they are displayed in the GUI, they will have a more descriptive or friendly name.
-From the Devices/Circuits example above, you might label the relationship so that on the Device side the connection appears as 'Terminated Circuits' and on the Circuit side the connection appears as 'Terminating Devices'.
-
-### Options
-
-It's also possible to hide the relationship from either side of the connection.
-
-## Creating New Relationships
-
-Relationships can be added through the UI under Extensibility > Relationships
-
-Each relationship must have a Name, Slug, Type, Source Object(s), and Destination Object(s). Optionally, Source Labels, Source Filters, Destination Labels, and Destination Filters may be configured.
-
-Once a new relationship is added, the Relationship configuration section will appear under that device in the UI edit screen. Once a specific instance relationship has been configured for the object, that new relationship will appear under the Relationship section heading when viewing the object.
-
-When creating a relationship, if "Move to Advanced tab" is checked, this relationship won't appear on the object's main detail tab in the UI, but will appear in the "Advanced" tab. This is useful when the requirement is to hide this relationship from the main detail tab when, for instance, it is only required for machine-to-machine communication and not user consumption.
-
-## REST API
-
-Relationships are fully supported by the API.
-
-### Adding a new type of Relationship
-
-The API endpoint for relationship creation is `/extras/relationships/`
-
-From our many to many example above, we would use the following data to create the relationship.
-
-```json
-{
-    "name": "Device VLANs",
-    "type": "many-to-many",
-    "source_type": "ipam.vlan",
-    "destination_type": "dcim.device"
-}
-```
-
-### Configuring the Relationship between Objects
-
-#### Via Object Endpoints
-
-+++ 1.4.0
-
-To get object relationships and associations from the REST API, you can query any object endpoint with the `?include=relationships` query parameter included, for example `GET /api/dcim/devices/f472bb77-7f56-4e79-ac25-2dc73eb63924/?include=relationships`. The API response will include a nested dictionary of relationships and associations applicable to the object(s) retrieved.
-
-Similarly, you can update the relationship associations for a given object via an HTTP `POST` or `PATCH` request, generally by including the nested key `["relationships"][<relationship_key>]["source"|"destination"|"peer"]["objects"]` with a list of objects to associate.
-
-For more details on this feature, refer to the [REST API documentation](./rest-api/overview.md).
-
-#### Via Relationship-Associations Endpoint
-
-Alternatively, relationship associations may be configured by sending a request to `/extras/relationship-associations/` like the following:
-
-Here we specify the IDs of each object. We specify the UUID of each object in their respective fields.
-
-```json
-{
-    "relationship": "bff38197-26ed-4bbd-b637-3e688acf361c",
-    "source_type": "ipam.vlan",
-    "source_id": "89588629-2d70-45ce-9e20-f6b159b41b0c",
-    "destination_type": "dcim.device",
-    "destination_id": "6e8e72da-ce6e-468d-90f9-b4473d449db7"
-}
-```
-
-In the relationship field, you may specify a dictionary of object attributes instead:
-
-```json
-{
-    "relationship": {
-        "key": "device_vlans"
-    },
-    "source_type": "ipam.vlan",
-    "source_id": "89588629-2d70-45ce-9e20-f6b159b41b0c",
-    "destination_type": "dcim.device",
-    "destination_id": "6e8e72da-ce6e-468d-90f9-b4473d449db7"
-}
-```

nautobot/docs/user-guide/platform-functionality/rest-api/authentication.md

@@ -1,67 +0,0 @@
-# REST API Authentication
-
-The Nautobot REST API primarily employs token-based authentication. For convenience, cookie-based authentication can also be used when navigating the browseable API.
-
-See the documentation on the [token model](../users/token.md).
-
-## Authenticating to the API
-
-An authentication token is attached to a request by setting the `Authorization` header to the string `Token` followed by a space and the user's token:
-
-```bash
-curl -H "Authorization: Token $TOKEN" \
--H "Accept: application/json; indent=4" \
-http://nautobot/api/dcim/locations/
-```
-
-```json
-{
-    "count": 10,
-    "next": null,
-    "previous": null,
-    "results": [...]
-}
-```
-
-A token is not required for read-only operations which have been exempted from permissions enforcement (using the [`EXEMPT_VIEW_PERMISSIONS`](../../administration/configuration/optional-settings.md#exempt_view_permissions) configuration parameter). However, if a token _is_ required but not present in a request, the API will return a 403 (Forbidden) response:
-
-```bash
-curl http://nautobot/api/dcim/locations/
-```
-
-```json
-{
-    "detail": "Authentication credentials were not provided."
-}
-```
-
-## Initial Token Provisioning
-
-+++ 1.3.0
-
-Ideally, each user should provision his or her own REST API token(s) via the web UI. However, you may encounter where a token must be created by a user via the REST API itself. Nautobot provides a special endpoint to provision tokens using a valid username and password combination.
-
-To provision a token via the REST API, make a `POST` request to the `/api/users/tokens/` endpoint:
-
-```bash
-curl -X POST \
--H "Content-Type: application/json" \
--H "Accept: application/json; indent=4" \
--u "hankhill:I<3C3H8" \
-https://nautobot/api/users/tokens/
-```
-
-Note that we are _not_ passing an existing REST API token with this request. If the supplied credentials are valid, a new REST API token will be automatically created for the user. Note that the key will be automatically generated, and write ability will be enabled.
-
-```json
-{
-    "id": "e87e6ee9-1ab2-46c6-ad7f-3d4697c33d13",
-    "url": "https://nautobot/api/users/tokens/e87e6ee9-1ab2-46c6-ad7f-3d4697c33d13/",
-    "display": "3c9cb9 (hankhill)",
-    "created": "2021-06-11T20:09:13.339367Z",
-    "expires": null,
-    "key": "9fc9b897abec9ada2da6aec9dbc34596293c9cb9",
-    "write_enabled": true,
-    "description": ""
-}
-```

nautobot/docs/user-guide/platform-functionality/rest-api/filtering.md

@@ -1,142 +0,0 @@
-# REST API Filtering
-
-## Filtering Objects
-
-The objects returned by an API list endpoint can be filtered by attaching one or more query parameters to the request URL. For example, `GET /api/dcim/locations/?status=active` will return only locations with a status of "active."
-
-Multiple parameters can be joined to further narrow results. For example, `GET /api/dcim/locations/?status=active&parent=europe&location_type=country` will return only active "country" type locations in Europe.
-
-Generally, passing multiple values for a single parameter will result in a logical OR operation. For example, `GET /api/dcim/locations/?parent=north-america&parent=south-america&location_type=country` will return "country" type locations in North America _or_ South America. However, a logical AND operation will be used in instances where a field may have multiple values, such as tags. For example, `GET /api/dcim/locations/?tag=foo&tag=bar` will return only locations which have both the "foo" _and_ "bar" tags applied.
-
-+/- 1.4.0
-    If [STRICT_FILTERING](../../administration/configuration/optional-settings.md#strict_filtering) is True (its default value), unrecognized filter parameters now result in a 400 Bad Request response instead of being silently ignored.
-
-### Filtering by Choice Field
-
-Some models have fields which are limited to specific choices, such as the `type` field on the Interface model. To find all available choices for this field, make an authenticated `OPTIONS` request to the model's list endpoint, and use `jq` to extract the relevant parameters:
-
-```no-highlight
-curl -s -X OPTIONS \
--H "Authorization: Token $TOKEN" \
--H "Content-Type: application/json" \
-http://nautobot/api/dcim/interfaces/ | jq ".actions.POST.type.choices"
-```
-
-Example output:
-
-```json
-[
-  {
-    "value": "virtual",
-    "display": "Virtual"
-  },
-  {
-    "value": "bridge",
-    "display": "Bridge"
-  },
-  {
-    "value": "lag",
-    "display": "Link Aggregation Group (LAG)"
-  },
-  {
-    "value": "100base-tx",
-    "display": "100BASE-TX (10/100ME)"
-  },
-  {
-    "value": "1000base-t",
-    "display": "1000BASE-T (1GE)"
-  },
-...
-```
-
-!!! note
-    The above works only if the API token used to authenticate the request has permission to make a `POST` request to this endpoint.
-
-### Filtering by Custom Field
-
-To filter results by a custom field value, prepend `cf_` to the custom field key. For example, the following query will return only locations where a custom field with key `foo` is equal to 123:
-
-```no-highlight
-GET /api/dcim/locations/?cf_foo=123
-```
-
-!!! note
-    For custom field filters, due to historical details of implementation, only a single filter value can be specified when matching a given field. In other words, in the above example, you could _not_ add `&cf_foo=456` to the query in order to get all locations where custom field `foo` is 123 _or_ 456; instead you would need to run two separate queries. This restriction does not apply to custom field filters using lookup expressions (next section) and will likely be changed in a future major version of Nautobot.
-
-Custom fields can be mixed with built-in fields to further narrow results. When creating a custom string field, the type of filtering selected (loose versus exact) determines whether partial or full matching is used.
-
-+++ 1.4.0
-    Custom fields can use the lookup expressions listed in the next section by prepending `cf_` to the custom field `name` (not the `slug`) followed by the required lookup type (see below).
-
-+/- 2.0.0
-    Custom field filters are now based on the custom field `key` string.
-
-## Lookup Expressions
-
-Certain model fields (including, in Nautobot 1.4.0 and later, custom fields of type `text`, `url`, `select`, `integer`, and `date`) also support filtering using additional lookup expressions. This allows
-for negation and other context-specific filtering.
-
-These lookup expressions can be applied by adding a suffix to the desired field's name, e.g. `mac_address__n`. In this case, the filter expression is for negation and it is separated by two underscores. Below are the lookup expressions that are supported across different field types.
-
-### Numeric Fields
-
-Numeric-based fields (ASN, VLAN ID, etc.) support these lookup expressions:
-
-- `n` - not equal to (negation)
-- `lt` - less than
-- `lte` - less than or equal
-- `gt` - greater than
-- `gte` - greater than or equal
-
-### String Fields
-
-String-based (char) fields (Name, Address, etc.) support these lookup expressions:
-
-- `n` - not equal to (negation)
-- `ic` - case-insensitive contains
-- `nic` - negated case-insensitive contains
-- `isw` - case-insensitive starts-with
-- `nisw` - negated case-insensitive starts-with
-- `iew` - case-insensitive ends-with
-- `niew` - negated case-insensitive ends-with
-- `ie` - case-insensitive exact match
-- `nie` - negated case-insensitive exact match
-
-+++ 1.3.0
-    - `re` - case-sensitive regular expression match
-    - `nre` - negated case-sensitive regular expression match
-    - `ire` - case-insensitive regular expression match
-    - `nire` - negated case-insensitive regular expression match
-
-### Foreign Keys & Other Fields
-
-Certain other fields, namely foreign key relationships support just the negation
-expression: `n`.
-
-### Network and Host Fields
-
-There are [Custom Lookups](https://docs.djangoproject.com/en/3.2/howto/custom-lookups/) built for the `VarbinaryIPField` field types. While
-the `VarbinaryIPField` is applied to fields for network, host, and broadcast, the below filters only apply to network and host. The design
-makes an assumption that there is in fact a broadcast (of type `VarbinaryIPField`) and prefix_length (of type `Integer`) within the same
-model. This assumption is used to understand the relevant scope of the network in question and is important to note when extending the
-Nautobot core or plugin data model.
-
-- `**` `exact` - An exact match of an IP or network address, e.g. `host__exact="10.0.0.1"`
-- `**` `iexact` - An exact match of an IP or network address, e.g. `host__iexact="10.0.0.1"`
-- `**` `startswith` - Determine if IP or network starts with the value provided, e.g. `host__startswith="10.0.0."`
-- `**` `istartswith` - Determine if IP or network starts with the value provided, e.g. `host__istartswith="10.0.0."`
-- `**` `endswith` - Determine if IP or network ends with the value provided, e.g. `host__endswith="0.1"`
-- `**` `iendswith` - Determine if IP or network ends with the value provided, e.g. `host__iendswith="0.1"`
-- `**` `regex` - Determine if IP or network matches the pattern provided, e.g. `host__regex=r"10\.(.*)\.1`
-- `**` `iregex` - Determine if IP or network matches the pattern provided, e.g. `host__iregex=r"10\.(.*)\.1`
-- `net_contained` - Given a network, determine which networks are contained within the provided e.g. `network__net_contained="192.0.0.0/8"` would include 192.168.0.0/24 in the result
-- `net_contained_or_equal` - Given a network, determine which networks are contained or is within the provided e.g. `network__net_contained_or_equal="192.0.0.0/8"` would include 192.168.0.0/24 and 192.0.0.0/8 in the result
-- `net_contains` - Given a network, determine which networks contain the provided network e.g. `network__net_contains="192.168.0.0/16"` would include 192.0.0.0/8 in the result
-- `net_contains_or_equals` - Given a network, determine which networks contain or is the provided network e.g. `network__net_contains="192.168.0.0/16"` would include 192.0.0.0/8 and 192.168.0.0/16 in the result
-- `net_equals` - Given a network, determine which which networks are an exact match. e.g. `network__net_equals="192.168.0.0/16"` would include only 192.168.0.0/16 in the result
-- `net_host` - Determine which networks are parent of the provided IP, e.g. `host__net_host="10.0.0.1"` would include 10.0.0.1/32 and 10.0.0.0/24 in the result
-- `net_host_contained` - Given a network, select IPs whose host address (regardless of its subnet mask) falls within that network , e.g. `host__net_host_contained="10.0.0.0/24"` would include hosts 10.0.0.1/8 and 10.0.0.254/32 in the result
-- `net_in` - Given a list of networks, select addresses (regardless of their subnet masks) within those networks, e.g. `host__net_in=["10.0.0.0/24", "2001:db8::/64"]` would include hosts 10.0.0.1/16 and 2001:db8::1/65 in the result
-- `family` - Given an IP address family of 4 or 6, provide hosts or networks that are that IP version type, e.g. `host__family=6` would include 2001:db8::1 in the result
-
-> Note: The fields denoted with `**` are only supported in the MySQL dialect (and not Postgresql) at the current time.