From f388b09a67a24a1485fac4a208411bfba4931abc Mon Sep 17 00:00:00 2001 From: 8ctorres Date: Sun, 26 May 2024 11:34:52 +0200 Subject: [PATCH] Corrections in documentation about nbshell --- docs/administration/netbox-shell.md | 38 +++--------------------- docs/customization/export-templates.md | 3 +- docs/customization/reports.md | 4 +++ docs/features/configuration-rendering.md | 3 +- 4 files changed, 12 insertions(+), 36 deletions(-) diff --git a/docs/administration/netbox-shell.md b/docs/administration/netbox-shell.md index 8a62c2a3c..c8be38ce4 100644 --- a/docs/administration/netbox-shell.md +++ b/docs/administration/netbox-shell.md @@ -1,6 +1,6 @@ # The NetBox Python Shell -NetBox includes a Python management shell within which objects can be directly queried, created, modified, and deleted. To enter the shell, run the following command from a shell that has the netbox virtualenv activated: +NetBox includes a Python management shell within which objects can be directly queried, created, modified, and deleted. To enter the shell, run the following command with the appropriate Python virtual environment activated: ``` ./manage.py nbshell @@ -105,6 +105,8 @@ This approach can span multiple levels of relations. For example, the following >>> IPAddress.objects.filter(interface__device__site__region__slug="north-america") ``` +The `get()` method can be used in place of the `filter()` method if we expect this query to return only one object. This method will yield the actual object resulting from the query, instead of a QuerySet. If the query returns more than one result, it will raise an exception. + !!! note While the above query is functional, it's not very efficient. There are ways to optimize such requests, however they are out of scope for this document. For more information, see the [Django queryset method reference](https://docs.djangoproject.com/en/stable/ref/models/querysets/) documentation. @@ -143,39 +145,7 @@ To return the inverse of a filtered queryset, use `exclude()` instead of `filter 346 ``` -If the query returns only one object, the get() method can be used. This method will yield the actual object resulting from the query, instead of a QuerySet. For this to work, the query must return only one object. The syntax is identical to the filter and exclude methods. For example, we can get a device from it's asset tag: - -``` ->>> ->>> Device.objects.get(asset_tag="100079912515") - ->>> -``` - -If the query returns more than one object, a MultipleObjectsReturned exception will be thrown: - -``` ->>> Device.objects.get(role_id=13) -Traceback (most recent call last): - File "", line 1, in - File "/srv/netbox/venv/lib/python3.10/site-packages/django/db/models/manager.py", line 87, in manager_method - return getattr(self.get_queryset(), name)(*args, **kwargs) - File "/srv/netbox/venv/lib/python3.10/site-packages/django/db/models/query.py", line 640, in get - raise self.model.MultipleObjectsReturned( -dcim.models.devices.Device.MultipleObjectsReturned: get() returned more than one Device -- it returned more than 20! ->>> -``` - -Queries can all also be executed from a particular object instead of from the model itself. For instance, to get all circuits that are assigned to one site, it is easier to filter from the site itself, instead of using the "Circuit" model and building the query from there. This is particularly useful for configuration templates and export templates, since it allows to query other database objects that are related to the object that we're rendering the template for. - -``` ->>> site.circuit_terminations.all() -, ]> ->>> -``` - -The same methods (all, filter, exclude, get...) can be used in this kind of queries. - +Queries can all also be executed from a particular object instead of from the model itself. For instance, to get all circuits that are assigned to one site, it is easier to filter from the site itself, instead of using the "Circuit" model and building the query from there. This is particularly useful for configuration templates and export templates, since it allows to query other database objects that are related to the object that we're rendering the template for. The same methods (all, filter, exclude, get...) can be used in this kind of queries. !!! info The examples above are intended only to provide a cursory introduction to queryset filtering. For an exhaustive list of the available filters, please consult the [Django queryset API documentation](https://docs.djangoproject.com/en/stable/ref/models/querysets/). diff --git a/docs/customization/export-templates.md b/docs/customization/export-templates.md index 8be160011..7e027d11f 100644 --- a/docs/customization/export-templates.md +++ b/docs/customization/export-templates.md @@ -32,7 +32,8 @@ If you need to use the config context data in an export template, you'll should {% endfor %} ``` -To see all the attributes of a given object, you can use the [Netbox Shell](../administration/netbox-shell.md). It supports autocompletion and allows one to see all of the methods and attributes a given object type has. All of them can be called from within a Jinja template. Using queries from one object to another, one can navigate pretty much the entire Netbox object model. For instance, from an export template for sites, one can get the devices that are in that site, the circuits that are connected to those devices, the providers that serve those circuits... etc, so an export template is not limited to just the model that it's being called from. In fact, the same result can be achieved in different ways, depending on which model you start from. +!!! info + To see all the attributes of a given object, you can use the [NetBox Shell](../administration/netbox-shell.md). It supports autocompletion and allows one to see all of the methods and attributes a given object type has. All of them can be called from within a Jinja template. The `as_attachment` attribute of an export template controls its behavior when rendered. If true, the rendered content will be returned to the user as a downloadable file. If false, it will be displayed within the browser. (This may be handy e.g. for generating HTML content.) diff --git a/docs/customization/reports.md b/docs/customization/reports.md index f7eef506d..197662873 100644 --- a/docs/customization/reports.md +++ b/docs/customization/reports.md @@ -15,8 +15,12 @@ from extras.reports import Report class MyReport(Report): ``` +<<<<<<< HEAD ```python title="New code" from extras.scripts import Script +======= +Within each report class, we'll create a number of test methods to execute our report's logic. The name of each method must begin with `test_` and the method must accept no arguments. +>>>>>>> c29c257cd (Corrections in documentation about nbshell) class MyReport(Script): ``` diff --git a/docs/features/configuration-rendering.md b/docs/features/configuration-rendering.md index 2ebc0f25e..ab4b43a33 100644 --- a/docs/features/configuration-rendering.md +++ b/docs/features/configuration-rendering.md @@ -35,7 +35,8 @@ Configuration templates are written in the [Jinja2 templating language](https:// {% endblock %} ``` -To see all the attributes of a given object, you can use the [Netbox Shell](../administration/netbox-shell.md). It supports autocompletion and allows one to see all of the methods and attributes a given object type has. All of them can be called from within the configuration template. Also, other objects, for instance, a device's interfaces or connected circuits can be accessed from the template itself, so the rendered configuration may include information not only about the device itself, but also related objects like IP addresses or circuits. +!!! info + To see all the attributes of a given object, you can use the [NetBox Shell](../administration/netbox-shell.md). It supports autocompletion and allows one to see all of the methods and attributes a given object type has. All of them can be called from within the configuration template. When rendered for a specific NetBox device, the template's `device` variable will be populated with the device instance, and `ntp_servers` will be pulled from the device's available context data. The resulting output will be a valid configuration segment that can be applied directly to a compatible network device.