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

nautobot/docs/development/apps/api/setup.md

@@ -1,132 +0,0 @@
-# Initial Setup
-
-!!! important "Use a Development Environment, Not Production For App Development"
-    You should not use your production environment for app development. For information on getting started with a development environment, check out [Nautobot development guide](../../core/getting-started.md).
-
-## App Structure
-
-Although the specific structure of an app is largely left to the discretion of its authors, a Nautobot app that makes use of all available app features described in this document could potentially look something like this:
-
-```no-highlight
-app_name/
-  - app_name/
-    - __init__.py           # required
-    - admin.py              # Django Admin Interface
-    - api/
-      - serializers.py      # REST API Model serializers
-      - urls.py             # REST API URL patterns
-      - views.py            # REST API view sets
-    - banner.py             # Banners
-    - custom_validators.py  # Custom Validators
-    - datasources.py        # Loading Data from a Git Repository
-    - filter_extensions.py  # Extending Filters
-    - filters.py            # Filtersets for UI, REST API, and GraphQL Model Filtering
-    - forms.py              # UI Forms and Filter Forms
-    - graphql/
-      - types.py            # GraphQL Type Objects
-    - homepage.py           # Home Page Content
-    - jinja_filters.py      # Jinja Filters
-    - jobs.py               # Job classes
-    - middleware.py         # Request/response middleware
-    - migrations/
-      - 0001_initial.py     # Database Models
-    - models.py             # Database Models
-    - navigation.py         # Navigation Menu Items
-    - secrets.py            # Secret Providers
-    - signals.py            # Signal Handler Functions
-    - template_content.py   # Extending Core Templates
-    - templates/
-      - app_name/
-        - *.html            # UI content templates
-    - urls.py               # UI URL Patterns
-    - views.py              # UI Views and any view override definitions
-  - pyproject.toml          # *** REQUIRED *** - Project package definition
-  - README.md
-```
-
-The top level is the project root. Immediately within the root should exist several items:
-
-* `pyproject.toml` - This is the new [unified Python project settings file](https://www.python.org/dev/peps/pep-0518/) that replaces `setup.py`, `requirements.txt`, and various other setup files (like `setup.cfg`, `MANIFEST.in`, among others).
-* `README.md` - A brief introduction to your app, how to install and configure it, where to find help, and any other pertinent information. It is recommended to write README files using a markup language such as Markdown.
-* The app source directory, with the same name as your app.
-
-The app source directory contains all of the actual Python code and other resources used by your app. Its structure is left to the author's discretion, however it is recommended to follow best practices as outlined in the [Django documentation](https://docs.djangoproject.com/en/stable/intro/reusable-apps/). At a minimum, this directory **must** contain an `__init__.py` file containing an instance of Nautobot's `NautobotAppConfig` class.
-
-!!! note
-    Nautobot includes a command to help create the app directory:
-    `nautobot-server startplugin [app_name]`
-    Please see the [Nautobot Server Guide](../../../user-guide/administration/tools/nautobot-server.md#startplugin) for more information.
-
-## Create pyproject.toml
-
-## Poetry Init (Recommended)
-
-To get started with a project using [Python Poetry](https://python-poetry.org/) you use the `poetry init` command. This will guide you through the prompts necessary to generate a pyproject.toml with details required for packaging.
-
-```no-highlight
-This command will guide you through creating your pyproject.toml config.
-
-Package name [tmp]:  nautobot-animal-sounds
-Version [0.1.0]:
-Description []:  An example Nautobot app
-Author [, n to skip]:  Bob Jones
-License []:  Apache 2.0
-Compatible Python versions [^3.8]:  ^3.8
-
-Would you like to define your main dependencies interactively? (yes/no) [yes] no
-Would you like to define your development dependencies interactively? (yes/no) [yes] no
-Generated file
-
-[tool.poetry]
-name = "nautobot-animal-sounds"
-version = "0.1.0"
-description = "An example Nautobot app"
-authors = ["Bob Jones"]
-license = "Apache 2.0"
-
-[tool.poetry.dependencies]
-python = "^3.8"
-
-[tool.poetry.dev-dependencies]
-
-[build-system]
-requires = ["poetry-core>=1.0.0"]
-build-backend = "poetry.core.masonry.api"
-
-
-Do you confirm generation? (yes/no) [yes]
-```
-
-## Install the App for Development
-
-The app needs to be installed into the same python environment where Nautobot is, so that we can get access to `nautobot-server` command, and also so that the nautobot-server is aware of the new app.
-
-If you installed Nautobot using Poetry, then go to the root directory of your clone of the Nautobot repository and run `poetry shell` there.  Afterward, return to the root directory of your app to continue development.
-
-Otherwise if using the pip install or Docker workflows, manually activate nautobot using `source /opt/nautobot/bin/activate`.
-
-To install the app for development the following steps should be taken:
-
-* Activate the Nautobot virtual environment (as detailed above)
-* Navigate to the project root, where the `pyproject.toml` file exists for the app
-* Execute the command `poetry install` to install the local package into the Nautobot virtual environment
-
-!!! note
-    Poetry installs the current project and its dependencies in editable mode (aka ["development mode"](https://setuptools.readthedocs.io/en/latest/userguide/development_mode.html)).
-
-!!! important "This should be done in development environment"
-    You should not use your production environment for app development. For information on getting started with a development environment, check out [Nautobot development guide](../../core/getting-started.md).
-
-```no-highlight
-poetry install
-```
-
-Once the app has been installed, add it to the configuration for Nautobot:
-
-```python
-PLUGINS = ["animal_sounds"]
-```
-
-## Verify that the App is Installed
-
-After restarting the Nautobot server, the newly installed app should appear in **Plugins -> Installed Plugins** if everything is configured correctly. You can also click on the app's name in this table to view more detailed information about this app based on its NautobotAppConfig and other contents.

nautobot/docs/development/apps/api/testing.md

@@ -1,55 +0,0 @@
-# Testing Apps
-
-In general apps can be tested like other Django apps. In most cases you'll want to run your automated tests via the `nautobot-server test <app_module>` command or, if using the `coverage` Python library, `coverage run --module nautobot.core.cli test <app_module>`.
-
-## Factories
-
-+++ 1.5.0
-
-The [`TEST_USE_FACTORIES`](../../../user-guide/administration/configuration/optional-settings.md#test_use_factories) setting defaults to `False` when testing apps, primarily for backwards-compatibility reasons. It can prove a useful way of populating a baseline of Nautobot database data for your tests and save you the trouble of creating a large amount of baseline data yourself. We recommend adding [`factory-boy`](https://pypi.org/project/factory-boy/) to your app's development dependencies and settings `TEST_USE_FACTORIES = True` in your app's development/test `nautobot_config.py` to take advantage of this.
-
-## Performance Tests
-
-+++ 1.5.0
-
-## Running Performance Tests
-
-You need to install `django-slowtests` as a part of your app dev dependency to run performance tests. It has a very intuitive way to measure the performance of your own tests for your app  (all you have to do is tag your tests with `performance`) and do `invoke performance-test` to get the time to run your tests with `NautobotPerformanceTestRunner`.
-
-`NautobotPerformanceTestRunner` is used by adding the flag `--testrunner nautobot.core.tests.runner.NautobotPerformanceTestRunner` to the `coverage run` command used for unit tests. This flag will replace the default `NautobotTestRunner` while retaining all its functionalities with the addition of performance evaluation after test
-runs.
-Checkout [Performance Tests](../../core/testing.md#performance-tests) for more detail.
-
-```python
-@tag("performance")
-def test_your_app(self)
-    pass
-...
-```
-
-## Gathering Performance Test Baseline Data
-
-If you want to add baselines for your own test to `nautobot/core/tests/performance_baselines.yml` or have your own baseline yaml file for performance testing, specify a different file path for  `TEST_PERFORMANCE_BASELINE_FILE` in app's development/test `nautobot_config.py`, and store the output of `invoke performance-test --performance-snapshot` command in that file. `--performance-snapshot` flag will store the results of your performance test to `report.yml` and all you need to do is copy/paste the result to the file set by `TEST_PERFORMANCE_BASELINE_FILE`. Now you have baselines for your own tests!
-Example output of `invoke performance-test --performance-snapshot`:
-
-```yaml
-tests:
-  - name: >-
-      test_run_job_with_sensitive_variables_and_requires_approval
-      (nautobot.extras.tests.test_views.JobTestCase)
-    execution_time: 4.799533
-  - name: test_run_missing_schedule (nautobot.extras.tests.test_views.JobTestCase)
-    execution_time: 4.367563
-  - name: test_run_now_missing_args (nautobot.extras.tests.test_views.JobTestCase)
-    execution_time: 4.363194
-  - name: >-
-      test_create_object_with_constrained_permission
-      (nautobot.extras.tests.test_views.GraphQLQueriesTestCase)
-    execution_time: 3.474244
-  - name: >-
-      test_run_now_constrained_permissions
-      (nautobot.extras.tests.test_views.JobTestCase)
-    execution_time: 2.727531
-```
-
-We recommend adding [`django-slowtests`](https://pypi.org/project/django-slowtests/) to your app's development dependencies to leverage this functionality to build better performing apps.

nautobot/docs/development/apps/api/ui-extensions/banners.md

@@ -1,26 +0,0 @@
-# Adding a Banner
-
-+++ 1.2.0
-
-An app can provide a function that renders a custom banner on any number of Nautobot views. By default Nautobot looks for a function `banner()` inside of `banner.py`. (This can be overridden by setting `banner_function` to a custom value on the app's `NautobotAppConfig`.)
-
-This function currently receives a single argument, `context`, which is the [Django request context](https://docs.djangoproject.com/en/stable/ref/templates/api/#using-requestcontext) in which the current page is being rendered. The function can return `None` if no banner is needed for a given page view, or can return a `Banner` object describing the banner contents. Here's a simple example `banner.py`:
-
-```python
-# banner.py
-from django.utils.html import format_html
-
-from nautobot.apps.ui import Banner, BannerClassChoices
-
-def banner(context, *args, **kwargs):
-    """Greet the user, if logged in."""
-    # Request parameters can be accessed via context.request
-    if not context.request.user.is_authenticated:
-        # No banner if the user isn't logged in
-        return None
-    else:
-        return Banner(
-            content=format_html("Hello, <strong>{}</strong>! 👋", context.request.user),
-            banner_class=BannerClassChoices.CLASS_SUCCESS,
-        )
-```

nautobot/docs/development/apps/api/ui-extensions/home-page.md

@@ -1,9 +0,0 @@
-# Adding Home Page Content
-
-+++ 1.2.0
-
-Apps can add content to the Nautobot home page. By default, Nautobot looks for a `layout` list inside of `homepage.py`. (This can be overridden by setting `homepage_layout` to a custom value on the app's `NautobotAppConfig`.)
-
-Using a key and weight system, a developer can integrate the app content amongst existing panels, groups, and items and/or create entirely new panels as desired.
-
-More documentation and examples can be found in the guide on [Home Page Panels](../../../core/homepage.md).

nautobot/docs/development/apps/api/ui-extensions/index.md

@@ -1 +0,0 @@
-# Extending the Existing Nautobot UI

nautobot/docs/development/apps/api/ui-extensions/navigation.md

@@ -1,15 +0,0 @@
-# Adding Navigation Menu Items
-
-Apps can extend the existing navigation bar layout. By default, Nautobot looks for a `menu_items` list inside of `navigation.py`. (This can be overridden by setting `menu_items` to a custom value on the app's `NautobotAppConfig`.)
-
-Using a key and weight system, a developer can integrate the app's menu additions amongst existing menu tabs, groups, and items.
-
---- 2.0.0
-    As part of the Nautobot 2.0 UI redesign, the option for apps to add entirely new top-level menu "tabs" has been removed. Additionally, buttons can no longer be added to menu items.
-
-More documentation and examples can be found in the [Navigation Menu](../../../core/navigation-menu.md) guide.
-
-!!! tip
-    To reduce the amount of clutter in the navigation menu, if your app provides an "app configuration" view, we recommend [linking it from the main "Installed Plugins" page](../configuration-view.md) rather than adding it as a separate item in the navigation menu.
-
-    Similarly, if your app provides an "app home" or "dashboard" view, consider linking it from the "Installed Plugins" page, and/or adding a link from the Nautobot home page (see below), rather than adding it to the navigation menu.

nautobot/docs/development/apps/api/ui-extensions/object-detail-views.md

@@ -1,74 +0,0 @@
-# Extending Object Detail Views
-
-Apps can inject custom content into certain areas of the detail views of applicable models. This is accomplished by subclassing `TemplateExtension`, designating a particular Nautobot model, and defining the desired methods to render custom content. Four methods are available:
-
-* `left_page()` - Inject content on the left side of the page
-* `right_page()` - Inject content on the right side of the page
-* `full_width_page()` - Inject content across the entire bottom of the page
-* `buttons()` - Add buttons to the top of the page
-* `detail_tabs()` - Add extra tabs to the end of the list of tabs within the page tabs navigation
-
-Additionally, a `render()` method is available for convenience. This method accepts the name of a template to render, and any additional context data you want to pass. Its use is optional, however.
-
-When a TemplateExtension is instantiated, context data is assigned to `self.context`. Available data include:
-
-* `object` - The object being viewed
-* `request` - The current request
-* `settings` - Global Nautobot settings
-* `config` - App-specific configuration parameters
-
-For example, accessing `{{ request.user }}` within a template will return the current user.
-
-Declared subclasses should be gathered into a list or tuple for integration with Nautobot. By default, Nautobot looks for an iterable named `template_extensions` within a `template_content.py` file. (This can be overridden by setting `template_extensions` to a custom value on the app's `NautobotAppConfig`.) An example is below.
-
-```python
-# template_content.py
-from django.urls import reverse
-from nautobot.apps.ui import TemplateExtension
-
-from .models import Animal
-
-
-class LocationAnimalCount(TemplateExtension):
-    """Template extension to display animal count on the right side of the page."""
-
-    model = 'dcim.location'
-
-    def right_page(self):
-        return self.render('nautobot_animal_sounds/inc/animal_count.html', extra_context={
-            'animal_count': Animal.objects.count(),
-        })
-
-
-class DeviceExtraTabs(TemplateExtension):
-    """Template extension to add extra tabs to the object detail tabs."""
-
-    model = 'dcim.device'
-
-    def detail_tabs(self):
-        """
-        You may define extra tabs to render on a model's detail page by utilizing this method.
-        Each tab is defined as a dict in a list of dicts.
-
-        For each of the tabs defined:
-        - The <title> key's value will become the tab link's title.
-        - The <url> key's value is used to render the HTML link for the tab
-
-        These tabs will be visible (in this instance) on the Device model's detail page as
-        set by the DeviceContent.model attribute "dcim.device"
-
-        This example demonstrates defining two tabs. The tabs will be ordered by their position in list.
-        """
-        return [
-            {
-                "title": "App Tab 1",
-                "url": reverse("plugins:example_plugin:device_detail_tab_1", kwargs={"pk": self.context["object"].pk}),
-            },
-            {
-                "title": "App Tab 2",
-                "url": reverse("plugins:example_plugin:device_detail_tab_2", kwargs={"pk": self.context["object"].pk}),
-            },
-        ]
-
-template_extensions = [DeviceExtraTabs, LocationAnimalCount]
-```

nautobot/docs/development/apps/api/ui-extensions/tabs.md

@@ -1,52 +0,0 @@
-# Adding Extra Tabs
-
-+++ 1.4.0
-
-In order for any extra tabs to work properly, the `"url"` key must reference a view which inherits from the `nautobot.apps.views.ObjectView` class and the template must extend the object's detail template such as:
-
-```html
-<!-- example_plugin/tab_device_detail_1.html -->
-{% extends 'dcim/device.html' %}
-
-{% block content %}
-    <h2>Device App Tab 1</h2>
-    <p>I am some content for the example plugin's device ({{ object.pk }}) detail tab 1.</p>
-{% endblock %}
-```
-
-Here's a basic example of a tab's view
-
-```python
-# views.py
-from nautobot.apps.views import ObjectView
-from nautobot.dcim.models import Device
-
-class DeviceDetailAppTabOne(ObjectView):
-    """
-    This view's template extends the device detail template,
-    making it suitable to show as a tab on the device detail page.
-
-    Views that are intended to be for an object detail tab's content rendering must
-    always inherit from nautobot.apps.views.ObjectView.
-    """
-
-    queryset = Device.objects.all()
-    template_name = "example_plugin/tab_device_detail_1.html"
-```
-
-You must also add the view to the `url_patterns` like so (make sure to read the note after this code snippet):
-
-```python
-# urls.py
-from django.urls import path
-
-from example_plugin import views
-
-urlpatterns = [
-    # ... previously defined urls
-    path("devices/<uuid:pk>/example-plugin-tab-1/", views.DeviceDetailAppTabOne.as_view(), name="device_detail_tab_1"),
-]
-```
-
-!!! note
-    For added tab views, we recommend for consistency that you follow the URL pattern established by the base model detail view and tabs (if any). For example, `nautobot/dcim/urls.py` references Device tab views with the URL pattern `devices/<uuid:pk>/TAB-NAME/`, so above we have followed that same pattern.

nautobot/docs/development/apps/api/views/base-template.md

@@ -1,38 +0,0 @@
-# Extending the Base Template
-
-Nautobot provides a base template to ensure a consistent user experience, which apps can extend with their own content. This template includes four content blocks:
-
-* `title` - The page title
-* `header` - The upper portion of the page
-* `content` - The main page body
-* `javascript` - A section at the end of the page for including Javascript code
-
-For more information on how template blocks work, consult the [Django documentation](https://docs.djangoproject.com/en/stable/ref/templates/builtins/#block).
-
-```jinja2
-{# templates/nautobot_animal_sounds/animal.html #}
-{% extends 'base.html' %}
-
-{% block content %}
-    {% with config=settings.PLUGINS_CONFIG.nautobot_animal_sounds %}
-        <h2 class="text-center" style="margin-top: 200px">
-            {% if animal %}
-                The {{ animal.name|lower }} says
-                {% if config.loud %}
-                    {{ animal.sound|upper }}!
-                {% else %}
-                    {{ animal.sound }}
-                {% endif %}
-            {% else %}
-                No animals have been created yet!
-            {% endif %}
-        </h2>
-    {% endwith %}
-{% endblock %}
-
-```
-
-The first line of the template instructs Django to extend the Nautobot base template and inject our custom content within its `content` block.
-
-!!! note
-    Django renders templates with its own custom [template language](https://docs.djangoproject.com/en/stable/topics/templates/#the-django-template-language). This template language is very similar to Jinja2, however there are some important differences to keep in mind.

nautobot/docs/development/apps/api/views/core-view-overrides.md

@@ -1,26 +0,0 @@
-# Replacing Views
-
-+++ 1.4.0
-
-You may override any of the core or app views by providing an `override_views` `dict` in an app's `views.py` file.
-
-To override a view, you must specify the view's fully qualified name as the `dict` key which consists of the app name followed by the view's name separated by a colon, for instance `dcim:device`. The `dict` value should be the overriding view function.
-
-A simple example to override the device detail view:
-
-```python
-# views.py
-from django.shortcuts import HttpResponse
-from django.views import generic
-
-
-class DeviceViewOverride(generic.View):
-    def get(self, request, *args, **kwargs):
-        return HttpResponse(("Hello world! I'm a view which "
-                             "overrides the device object detail view."))
-
-
-override_views = {
-    "dcim:device": DeviceViewOverride.as_view(),
-}
-```

nautobot/docs/development/apps/api/views/django-generic-views.md

@@ -1,23 +0,0 @@
-# Utilizing Generic Django Views
-
-The use of `generic` Django views can aid in app development. As an example, let's write a view which displays a random animal and the sound it makes. First, create the view in `views.py`:
-
-```python
-# views.py
-from django.shortcuts import render
-from django.views.generic import View
-
-from .models import Animal
-
-
-class RandomAnimalView(View):
-    """Display a randomly-selected Animal."""
-
-    def get(self, request):
-        animal = Animal.objects.order_by('?').first()
-        return render(request, 'nautobot_animal_sounds/animal.html', {
-            'animal': animal,
-        })
-```
-
-This view retrieves a random animal from the database and and passes it as a context variable when rendering a template named `animal.html`, which doesn't exist yet. To create this template, first create a directory named `templates/nautobot_animal_sounds/` within the app source directory. (We use the app's name as a subdirectory to guard against naming collisions with other apps.) Then, create a template named `animal.html` as described below.

nautobot/docs/development/apps/api/views/help-documentation.md

@@ -1,16 +0,0 @@
-# Adding Help Documentation
-
-If you are using the `generic.ObjectEditView` from Nautobot for your object, the form can automatically include a help icon with a link to that object's documentation. For this to happen, Nautobot must be able to find the documentation for this object in a specific directory tree within your app:
-
-```no-highlight
-app_name/                   # "nautobot_animal_sounds"
-  - static/
-    - app_name/             # "nautobot_animal_sounds"
-      - docs/
-        - index.html
-        - core-data-model/
-          - object_model.html  # "animal.html"
-```
-
-+/- 2.0.0
-    If you have a need to deviate from this structure, your model can define as a class attribute a `documentation_static_path` string to provide a different location within the `static/` subdirectory.

nautobot/docs/development/apps/api/views/index.md

@@ -1,3 +0,0 @@
-# Adding Web UI Views
-
-If your app needs its own page or pages in the Nautobot web UI, you'll need to define views. A view is a particular page tied to a URL within Nautobot, which renders content using a template.

nautobot/docs/development/apps/api/views/nautobot-generic-views.md

@@ -1,35 +0,0 @@
-# Utilizing Nautobot Generic Views
-
-+++ 1.1.0
-    Via [PR #14](https://github.com/nautobot/nautobot/issues/14), some `generic` views have been exposed to help aid in plugin development. These views have some requirements that must be in place in order to work. These can be used by importing them from `from nautobot.core.views import generic`.
-
-More documentation and examples can be found in [Generic Views](../../../core/generic-views.md) guide.
-
-## Note URL Endpoint
-
-+++ 1.4.0
-
-Models that inherit from `PrimaryModel` and `OrganizationalModel` can have notes associated. In order to utilize this new feature you will need to add the endpoint to `urls.py`. Here is an option to be able to support both 1.4+ and older versions of Nautobot:
-
-!!! tip
-    This is only necessary if you are not using NautobotUIViewSet & NautobotUIViewSetRouter and wish to include Notes functionality.
-
-```python
-
-urlpatterns = [
-    path('random/', views.RandomAnimalView.as_view(), name='random_animal'),
-]
-
-try:
-    from nautobot.extras.views import ObjectNotesView
-    urlpatterns.append(
-        path(
-            'random/<uuid:pk>/notes/),
-            ObjectNotesView.as_view(),
-            name="random_notes",
-            kwargs={"model": Random},
-        )
-    )
-except ImportError:
-    pass
-```