Skip to content

Commit

Permalink
docs: Update
Browse files Browse the repository at this point in the history
  • Loading branch information
@snaselj
snaselj committed Sep 30, 2023
1 parent c949019 commit df22e51
Show file tree
Hide file tree
Showing 11 changed files with 598 additions and 557 deletions.
382 changes: 194 additions & 188 deletions docs/advanced/create.rst
View file

Large diffs are not rendered by default.

69 changes: 33 additions & 36 deletions docs/advanced/graphql.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,6 @@ to the above ``nautobot`` object upon initialization.
The :py:meth:`~pynautobot.core.graphql.GraphQLQuery.query` method is used to
perform queries against Nautobot's GraphQL endpoint.


Making a GraphQL Query
----------------------

Expand All @@ -31,87 +30,86 @@ that a query string is passed into it.
The method retuns a :py:class:`~pynautobot.core.graphql.GraphQLRecord` object
as discussed in :ref:`The GraphQLRecord Object` section.

This example demonstrates how to fetch the `id`, `name`, and `region name` for all *Sites*.
This example demonstrates how to fetch the `id`, `name`, and `parent name` for all *Locations*.

.. code-block:: python
>>> # Build a query string
>>> query = """
... query {
... sites {
... locations {
... id
... name
... region {
... parent {
... name
... }
... }
... }
... """
>>>
>>> # Make a graphql query
>>> graphql_response = nautobot.graphql.query(query=query)
>>>
>>> # Show that a GraphQLRecord is returned
GraphQLRecord(json={'data': {'sites': [{'id': '2cfbc91e-361f-4129-9db6-bc21a6f88d38', 'name': 'ams', ..., status_code=200)
>>> graphql_response
GraphQLRecord(json={'data': {'locations': [{'id': ..., status_code=200)
The next example performs the same query, but restricts it to only the ``den`` site.
The next example performs the same query, but restricts it to only the ``HQ`` location.
.. code-block:: python
>>> # Build a query string restricting only to den site
>>> # Build a query string restricting only to HQ location
>>> query = """
... query {
... sites (name: "den") {
... locations (name: "HQ") {
... id
... name
... region {
... parent {
... name
... }
... }
... }
... """
>>> graphql_response = nautobot.graphql.query(query=query)
>>> graphql_response
GraphQLRecord(json={'data': {'sites': [{'id': '45399b54-47f9-4eec-86e3-47352e103b1b', 'name': 'den', 'region': {'name': 'United States'}}]}}, status_code=200)
GraphQLRecord(json={'data': {'locations': [{'id': ..., 'name': 'HQ', 'parent': {'name': 'US'}}]}}, status_code=200)
.. tip::
Nautobot's `GraphQL documentation <https://nautobot.readthedocs.io/en/latest/additional-features/graphql/>`_
Nautobot's `GraphQL documentation <https://docs.nautobot.com/projects/core/en/stable/user-guide/platform-functionality/graphql/>`_
provides a summary of making queries.
Nautobot's browsable API also provides a `graphiql` interface to aid in developing query strings at `/graphql/`
Making a GraphQL Query with Variables
-------------------------------------
The :py:meth:`~pynautobot.core.graphql.GraphQLQuery.query` method supports using variables in the query string by passing in an optional ``variables`` argument.
This argument is a dictionary, with the `key` being the variable name, and the `value` being the value to use for the variable in the query string.
This example is the same as the previous one, except the site name is now derived using variables.
This example is the same as the previous one, except the location name is now derived using variables.
.. code-block:: python
>>> # Create a variables dictionary
>>> variables = {"site_name": "den"}
>>> variables = {"location_name": "HQ"}
>>>
>>> # Create a query string that takes variables
>>> query = """
... query ($site_name:String!) {
... sites (name: $site_name) {
... query ($location_name:String!) {
... locations (name: [$location_name]) {
... id
... name
... region {
... parent {
... name
... }
... }
... }
... """
>>>
>>> # Use the query method with variables
>>> graphql_response = nautobot.graphql.query(query=query, variables=variables)
>>> graphql_response
GraphQLRecord(json={'data': {'sites': [{'id': '45399b54-47f9-4eec-86e3-47352e103b1b', 'name': 'den', 'region': {'name': 'United States'}}]}}, status_code=200)
GraphQLRecord(json={'data': {'locations': [{'id': ..., 'name': 'HQ', 'parent': {'name': 'US'}}]}}, status_code=200)
The GraphQLRecord Object
------------------------
Expand All @@ -122,13 +120,13 @@ This example shows accessing data from the previous query.
.. code-block:: python
>>> variables = {"site_name": "den"}
>>> variables = {"location_name": "HQ"}
>>> query = """
... query ($site_name:String!) {
... sites (name: $site_name) {
... query ($location_name:String!) {
... locations (name: [$location_name]) {
... id
... name
... region {
... parent {
... name
... }
... }
Expand All @@ -138,21 +136,20 @@ This example shows accessing data from the previous query.
>>> graphql_response.json
{
'data': {
'sites': [
'locations': [
{
'id': '45399b54-47f9-4eec-86e3-47352e103b1b',
'name': 'den',
'region': {
'name': 'United States'
'id': ...,
'name': 'HQ',
'parent': {
'name': 'US'
}
}
]
}
}
>>> # Get the name of the first site
>>> graphql_response.json["data"]["sites"][0]["name"]
'den'
>>> # Get the name of the first location
>>> graphql_response.json["data"]["locations"][0]["name"]
'HQ'
Saving Changes
--------------
Expand Down
103 changes: 48 additions & 55 deletions docs/advanced/read.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,6 @@ for retrieving :py:class:`~pynautobot.core.response.Record` objects from Nautobo
* The :py:meth:`~pynautobot.core.endpoint.Endpoint.filter` method will return a list of Records.
* The :py:meth:`~pynautobot.core.endpoint.Endpoint.all` method will return all Records for the Model.


Using the Get Method
--------------------

Expand All @@ -19,15 +18,15 @@ which is the ID for most objects.

.. code-block:: python
>>> dev = nautobot.dcim.devices.get('2302f2a1-2ed4-4ac9-a43a-285c95190071')
>>> dev.name
>>> device = nautobot.dcim.devices.get('2302f2a1-2ed4-4ac9-a43a-285c95190071')
>>> device.name
'hq-access-01'
>>> dev.status
>>> device.status
Active
>>> dev.device_type
>>> device.device_type
c9300-48
>>> dev.device_role
Access
>>> device.role
<pynautobot.core.response.Record ('Active') at ...>
.. note::
If an entry with the specified value for the PK does not exist,
Expand All @@ -39,14 +38,13 @@ If multiple Records are matched, then a ``ValueError`` is raised.

.. code-block:: python
>>> dev = nautobot.dcim.devices.get(model="CSR1000V")
>>> device = nautobot.dcim.devices.get(device_type="c9300-48")
Traceback (most recent call last):
...
ValueError: get() returned more than one result.
Check that the kwarg(s) passed are valid for this endpoint
or use filter() or all() instead.
Using the Filter Method
-----------------------
Expand All @@ -60,7 +58,6 @@ This method also supports:
* filtering based on custom fields
* filtering with lookup expressions
Basic Usage
^^^^^^^^^^^
Expand All @@ -72,50 +69,51 @@ but will return all matches using :py:meth:`~pynautobot.core.endpoint.Endpoint.f
.. code-block:: python
>>> # Get all CSR1000V devices
>>> devices = nautobot.dcim.devices.filter(model="CSR1000V")
>>> # Get all c9300-48 devices
>>> devices = nautobot.dcim.devices.filter(device_type="c9300-48")
>>>
>>> # Show a list of Records are returned
>>> devices
[jcy-bb-01.infra.ntc.com, jcy-rtr-01.infra.ntc.com, jcy-rtr-02.infra.ntc.com]
>>> # Show accessing data from the first CSR1000V device
>>> dev1 = devices[0]
>>> dev1.name
'jcy-bb-01.infra.ntc.com'
>>> dev1.status
Active
>>> pprint(devices)
[<pynautobot.models.dcim.Devices ('hq-access-01') at ...>,
<pynautobot.models.dcim.Devices ('hq-access-02') at ...>,
<pynautobot.models.dcim.Devices ('hq-access-03') at ...>,
<pynautobot.models.dcim.Devices ('hq-access-04') at ...>]
>>>
>>> # Show accessing data from the first c9300-48 device
>>> device1 = devices[0]
>>> device1.name
'hq-access-01'
>>> device1.status
<pynautobot.core.response.Record ('Active') at ...>
Filtering with OR logic
^^^^^^^^^^^^^^^^^^^^^^^
The :py:meth:`~pynautobot.core.endpoint.Endpoint.filter` method allows
using an **OR** condition by passing in a list of values to match against the field.
The example below gets all devices located in either *Site* ``hq`` or ``dc``.
The example below gets all devices located in either *Location* ``HQ`` or ``DC``.
.. code-block:: python
>>> # There are 100 devices total
>>> nautobot.dcim.devices.count()
100
>>> # There are 20 dc devices
>>> dev_dc_site = nautobot.dcim.devices.filter(site="dc")
>>> len(dev_dc_site)
>>>
>>> # There are 20 DC devices
>>> dev_dc_location = nautobot.dcim.devices.filter(location="DC")
>>> len(dev_dc_location)
20
>>> # There are 5 hq devices
>>> dev_hq_site = nautobot.dcim.devices.filter(site="hq")
>>> len(dev_hq_site)
>>>
>>> # There are 5 HQ devices
>>> dev_hq_location = nautobot.dcim.devices.filter(location="HQ")
>>> len(dev_hq_location)
5
# The filter method will grab all devices in both sites
>>> dev_hq_dc_sites = nautobot.dcim.devices.filter(site=["hq", "dc"])
>>> len(dev_all_sites)
>>>
# The filter method will grab all devices in both locations
>>> dev_hq_dc_locations = nautobot.dcim.devices.filter(location=["HQ", "DC"])
>>> len(dev_hq_dc_locations)
25
Filtering based on a Custom Field
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Expand All @@ -129,13 +127,13 @@ by passing the ``cf_owner`` keyword argument.
>>> devices = nautobot.dcim.devices.filter(cf_owner="John Smith")
>>> devices
[switch0, switch1]
[<pynautobot.models.dcim.Devices ('switch0') at ...>,
<pynautobot.models.dcim.Devices ('switch1') at ...>]
>>>
>>> # Show device has an owner of "John Smith"
>>> devices[0].custom_fields["owner"]
'John Smith'
Filtering with Lookup Expressions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Expand All @@ -151,19 +149,18 @@ There are several expressions that can be used; they generally cover things like
* case insensitivity

The example below shows how use negation with *__n*.
From the previous examples, there are 100 devices total, and 25 are located in either the `dc` or `hq` site.
Using ``site__n`` to get the negation of these sites returns 75 devices.
From the previous examples, there are 100 devices total, and 25 are located in either the `DC` or `HQ` location.
Using ``location__n`` to get the negation of these locations returns 75 devices.

.. code-block::
>>> devices = nautobot.dcim.devices.filter(site__n=["hq", "dc"])
>>> devices = nautobot.dcim.devices.filter(location__n=["HQ", "DC"])
>>> len(devices)
75
>>> # Show the device is not in either hq or dc site
>>> devices[0].site
branch1
>>>
>>> # Show the device is not in either HQ or DC location
>>> devices[0].location
<pynautobot.core.response.Record ('branch1') at 0x7f650006df50>
Using the All Method
--------------------
Expand All @@ -176,15 +173,11 @@ This will return a list of all :py:class:`~pynautobot.core.response.Record` obje
>>> devices = nautobot.dcim.devices.all()
>>> len(devices)
100
>>> dev1 = devices[0]
>>> dev1.name
>>> device1 = devices[0]
>>> device1.name
'hq-access-01'
>>> dev1.status
>>> device1.status
Active
.. tip::
Both ``filter`` and ``all`` can use threading by passing
in ``use_threading=True`` when instantiating the ``api`` object.

The following two pages cover interacting with the returned :py:class:`~pynautobot.core.response.Record` objects.
The next page covers additional Update operations, which is followed by a discussion of other features and methods.
Loading

0 comments on commit df22e51

Please sign in to comment.