Merge 745a815d27 into 85db007ff5

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:
+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:
 
 ```
 ./manage.py nbshell
@@ -143,6 +143,40 @@ 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")
+<Device: AP994003 (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 "<console>", line 1, in <module>
+  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()
+<RestrictedQuerySet [<CircuitTermination: 20899518: Termination A>, <CircuitTermination: DT00018356: Termination A>]>
+>>>
+```
+
+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/).
 

docs/customization/custom-scripts.md

@@ -56,6 +56,15 @@ class AnotherCustomScript(Script):
 script_order = (MyCustomScript, AnotherCustomScript)
 ```
 
+### The run() method
+
+The run() method is the entrypoint for the script, and it runs in the context of Netbox's own execution environment. This means from here, everything inside Netbox itself is accesible. The [Netbox Shell](../administration/netbox-shell.md) is a good resource to keep in hand, since it allows to see the objects in Netbox in the same way the run() method of the script does.
+
+The run() method can itself call other methods that are in the same module but outside the "MyCustomScript" class, and if there are several scripts in the same module (this is, in the same Python file), both scripts can reuse the same auxiliary methods, keeping the code cleaner. For this reason, it is encouraged to keep similar scripts in the same module.
+
+The run() method can return a string, and this will be displayed in a text box in the web interface after the script finishes. This is useful, for instance, for returning a piece of configuration or information that you want the user to be able to easily copy and paste somewhere else.
+
+
 ## Module Attributes
 
 ### `name`

docs/customization/export-templates.md

@@ -32,6 +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.
+
 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.)
 
 A MIME type and file extension can optionally be defined for each export template. The default MIME type is `text/plain`.

docs/customization/reports.md

@@ -29,7 +29,9 @@ class DeviceIPsReport(Report):
     description = "Check that every device has a primary IP address assigned"
 ```
 
-Within each report class, we'll create a number of test methods to execute our report's logic. In DeviceConnectionsReport, for instance, we want to ensure that every live device has a console connection, an out-of-band management connection, and two power connections.
+Within each report class, we'll create a number of test methods to execute our report's logic. The method's name must start with "test_" and it takes no arguments.
+
+In DeviceConnectionsReport, for instance, we want to ensure that every live device has a console connection, an out-of-band management connection, and two power connections.
 
 ```
 from dcim.choices import DeviceStatusChoices
@@ -82,6 +84,8 @@ class DeviceConnectionsReport(Report):
 
 As you can see, reports are completely customizable. Validation logic can be as simple or as complex as needed. Also note that the `description` attribute support markdown syntax. It will be rendered in the report list page.
 
+In the same way scripts do, reports run from within Netbox's own environment and can access the objects inside Netbox directly. The [Netbox Shell](../administration/netbox-shell.md) is a good resource to keep in hand, since it allows to see the objects in Netbox in the same way the test methods of a report do.
+
 !!! warning
     Reports should never alter data: If you find yourself using the `create()`, `save()`, `update()`, or `delete()` methods on objects within reports, stop and re-evaluate what you're trying to accomplish. Note that there are no safeguards against the accidental alteration or destruction of data.
 

docs/features/configuration-rendering.md

@@ -35,6 +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.
+
 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.
 
 ### Context Data