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

nautobot/docs/development/core/docker-compose-advanced-use-cases.md

@@ -1,228 +0,0 @@
-# Docker Compose Advanced Use Cases
-
-This section describes some of the more advanced use cases for the [Docker Compose development workflow](getting-started.md#docker-compose-workflow).
-
-## Invoke Configuration
-
-The Invoke tasks have some default [configuration](http://docs.pyinvoke.org/en/stable/concepts/configuration.html) which you may want to override. Configuration properties include:
-
-- `project_name`: The name that all Docker containers will be grouped together under (default: `nautobot`, resulting in containers named `nautobot_nautobot_1`, `nautobot_redis_1`, etc.)
-- `python_ver`: the Python version which is used to build the Docker container (default: `3.8`)
-- `local`: run the commands in the local environment vs the Docker container (default: `False`)
-- `compose_dir`: the full path to the directory containing the Docker Compose YAML files (default: `"<nautobot source directory>/development"`)
-- `compose_files`: the Docker Compose YAML file(s) to use (default: `["docker-compose.yml", "docker-compose.postgres.yml", "docker-compose.dev.yml"]`)
-- `docker_image_names_main` and `docker_image_names_develop`: Used when [building Docker images for publication](release-checklist.md#publish-docker-images); you shouldn't generally need to change these.
-
-These setting may be overridden several different ways (from highest to lowest precedence):
-
-- Command line argument on the individual commands (see `invoke $command --help`) if available
-- Using environment variables such as `INVOKE_NAUTOBOT_PYTHON_VER`; the variables are prefixed with `INVOKE_NAUTOBOT_` and must be uppercase; note that Invoke does not presently support environment variable overriding of list properties such as `compose_files`.
-- Using an `invoke.yml` file (see [`invoke.yml.example`](https://github.com/nautobot/nautobot/blob/main/invoke.yml.example))
-
-## Working with Docker Compose
-
-The files related to the Docker development environment can be found inside of the `development` directory at the root of the project.
-
-In this directory you'll find the following core files:
-
-- `docker-compose.yml` - Docker service containers and their relationships to the Nautobot container
-- `docker-compose.debug.yml` - Docker compose override file used to start the Nautobot container for use with [Visual Studio Code's dev container integration](#microsoft-visual-studio-code-integration).
-- `docker-compose.dev.yml` - Docker compose override file used to mount the Nautobot source code inside the container at `/source` and the `nautobot_config.py` from the same directory as `/opt/nautobot/nautobot_config.py` for the active configuration.
-- `docker-compose.final.yml` - Docker compose override file used to start/build the `final` (production) Docker images for local testing.
-- `docker-compose.final-dev.yml` - Docker compose override file used to start/build the `final-dev` (app development environment) Docker images for local testing.
-- `docker-compose.keycloak.yml` - Docker compose override file used to setup an SSO auth backend for Nautobot.
-- `docker-compose.mysql.yml` - Docker compose override file used to add a MySQL container as the database backend for Nautobot.
-- `docker-compose.postgres.yml` - Docker compose override file used to add a Postgres container as the database backend for Nautobot.
-- `dev.env` - Environment variables used to setup the container services
-- `nautobot_config.py` - Nautobot configuration file
-
-In addition to the `development` directory, additional non-development-specific Docker-related files are located in the `docker` directory at the root of the project.
-
-In the `docker` directory you will find the following files:
-
-- `Dockerfile` - Docker container definition for Nautobot containers
-- `docker-entrypoint.sh` - Commands and operations ran once Nautobot container is started including database migrations and optionally creating a superuser
-- `uwsgi.ini` - The [uWSGI](https://uwsgi-docs.readthedocs.io/en/latest/) ini file used in the production docker container
-
-## Docker Compose Overrides
-
-If you require changing any of the defaults found in `docker-compose.yml`, create a file inside the `development` directory called `docker-compose.override.yml` and add this file to the `compose_files` setting in your `invoke.yml` file, for example:
-
-```yaml
----
-nautobot:
-  compose_files:
-    - "docker-compose.yml"
-    - "docker-compose.postgres.yml"
-    - "docker-compose.dev.yml"
-    - "docker-compose.override.yml"
-```
-
-This file will override any configuration in the main `docker-compose.yml` file, without making changes to the repository.
-
-Please see the [official documentation on extending Docker Compose](https://docs.docker.com/compose/extends/) for more information.
-
-### Automatically Creating a Superuser
-
-There may be times where you want to bootstrap Nautobot with a superuser account and API token already created for quick access or for running within a CI/CD pipeline. By using a custom `invoke.yml` as described above, in combination with custom `docker-compose.override.yml` and `override.env` files, you can automatically bootstrap Nautobot with a user and token.
-
-Create `invoke.yml` as described above, then create `development/docker-compose.override.yml` with the following contents:
-
-```yaml
----
-services:
-  nautobot:
-    env_file:
-      - "override.env"
-```
-
-The `docker-entrypoint.sh` script will run any migrations and then look for specific variables set to create the superuser. The `docker-entrypoint.sh` script is copied in during the Docker image build and will read from the default `dev.env` as the `env_file` until you override it as seen above.
-
-Any variables defined in this file will override the defaults. The `override.env` should be located in the `development/` directory, and should look like the following:
-
-```bash
-# Superuser information. NAUTOBOT_CREATE_SUPERUSER defaults to false.
-NAUTOBOT_CREATE_SUPERUSER=true
-NAUTOBOT_SUPERUSER_NAME=admin
-NAUTOBOT_SUPERUSER_EMAIL=admin@example.com
-NAUTOBOT_SUPERUSER_PASSWORD=admin
-NAUTOBOT_SUPERUSER_API_TOKEN=0123456789abcdef0123456789abcdef01234567
-```
-
-The variables defined above within `override.env` will signal the `docker-entrypoint.sh` script to create the superuser with the specified username, email, password, and API token.
-
-After these two files are created, you can use the `invoke` tasks to manage the development containers.
-
-### Using MySQL instead of PostgreSQL
-
-By default the Docker development environment is configured to use a PostgreSQL container as the database backend. For development or testing purposes, you might optionally choose to use MySQL instead. In order to do so, you need to make the following changes to your environment:
-
-- Set up `invoke.yml` as described above and use it to override the postgres docker compose file:
-
-```yaml
----
-nautobot:
-  compose_files:
-    - "docker-compose.yml"
-    - "docker-compose.mysql.yml"
-    - "docker-compose.dev.yml"
-```
-
-Then `invoke stop` (if you previously had the docker environment running with Postgres) and `invoke start` and you should now be running with MySQL.
-
-### SSO Auth Backend with Keycloak
-
-Keycloak and its database are run in the same docker compose project as Nautobot. A separate database is used to ensure you are able to have two separate instances of Postgres, one for Nautobot and one for Keycloak, and allows you to use a MySQL database for Nautobot but maintain Keycloaks required Postgres DB. This setup is meant for local development and testing, and should not be used as a reference for deploying Keycloak in production.
-
-The `invoke.yml` file must be updated to add `development/docker-compose.keycloak.yml` to the docker compose project and to enable OIDC. These setting are solely for local development inside the Nautobot repository and is not applicable to any other deployment. An example `invoke.yml` file:
-
-```yaml
----
-nautobot:
-  compose_files:
-    - "docker-compose.yml"
-    - "docker-compose.postgres.yml"
-    - "docker-compose.dev.yml"
-    - "docker-compose.keycloak.yml"
-```
-
-#### Validating Setup
-
-Once all steps are completed Nautobot should now have the `Continue to SSO` button on the login screen and should immediately redirect the user to sign in with Keycloak.
-
-#### Keycloak Login Credentials
-
-Keycloak admin console is reachable via `http://localhost:8087/admin/` with user `admin` and password `admin`. The below users are pre-configured within Keycloak, at this time their permissions are not directly mapped to any permissions provided by default by Nautobot. This will be a later enhancement to the local development environment.
-
-| Username         | Password  |
-+------------------+-----------+
-| nautobot_unpriv  | unpriv123 |
-| nautobot_admin   | admin123  |
-| nautobot_auditor | audit123  |
-
-## Microsoft Visual Studio Code Integration
-
-For users of Microsoft Visual Studio Code, several files are included to ease development and integrate with the [VS Code Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers). The following related files are found relative to the root of the project:
-
-- `.devcontainers/devcontainer.json` - Dev. container definition
-- `nautobot.code-workspace` - VS Code workspace configuration for Nautobot
-- `development/docker-compose.debug.yml` - Docker Compose file with debug configuration for VS Code
-
-After opening the project directory in VS Code in a supported environment, you will be prompted by VS Code to **Reopen in Container** and **Open Workspace**. Select **Reopen in Container** to build and start the development containers. Once your window is connected to the container, you can open the workspace which enables support for Run/Debug.
-
-To start Nautobot, select **Run Without Debugging** or **Start Debugging** from the Run menu. Once Nautobot has started, you will be prompted to open a browser to connect to Nautobot.
-
-!!! note
-    You can run tests with `nautobot-server --config=nautobot/core/tests/nautobot_config.py test nautobot` while inside the Container.
-
-### Special Workflow for Containers on Remote Servers
-
-A slightly different workflow is needed when your development container is running on a remotely-connected server (such as with SSH). VS Code will not offer the **Reopen in Container** option on a remote server.
-
-To work with remote containers, after `invoke build` use `docker-compose` as follows to start the containers. This prevents the HTTP service from automatically starting inside the container:
-
-```no-highlight
-cd development
-docker compose -f docker-compose.yml -f docker-compose.debug.yml up
-```
-
-- Now open the VS Code Docker extension. In the `CONTAINERS/development` section, right click on a running container and select the **Attach Visual Studio Code** menu item.
-- The **Select the container to attach VS Code** input field provides a list of running containers.
-- Click on `development_nautobot_1` to use VS Code inside the container. The `devcontainer` will startup now.
-- As a last step open the folder `/opt/nautobot` in VS Code.
-
-### Remote Debugging Configuration
-
-Using the Remote-Attach functionality of VS Code debugger is an alternative to debugging in a development container. This allows a local VS Code instance to connect to a remote container and debug the code running in the container the same way as when debugging locally.
-
-Follow the steps below to configure VS Code to debug Nautobot and Celery Worker running in a remote container:
-
-1. **Configure `invoke.yml` to use the `docker-compose.vscode-rdb.yml` file**
-
-    This overrides the container settings without touching the original `docker-compose.yml` file.
-
-    Your `invoke.yml` file should look something like this:
-
-    ```yaml
-    ---
-    nautobot:
-      compose_files:
-        - "docker-compose.yml"
-        - "docker-compose.postgres.yml"
-        - "docker-compose.dev.yml"
-        - "docker-compose.vscode-rdb.yml"
-    ```
-
-    If you already have a custom `invoke.yml` file, append `docker-compose.vscode-rdb.yml` to the end of the `compose_files` list.
-
-    See the [docker compose override](#docker-compose-overrides) documentation for more details.
-
-2. **VS Code debug configuration**
-
-    If you have opened the workspace file `nautobot.code-workspace` then there are two debug
-    configurations for remote debugging already available.
-
-    If you add nautobot to an existing VS Code workspace (Menu: _File > Add Folder to Workspace..._)
-    then copy the `launch:` values to the `.vscode/launch.json` file.
-
-    - Debug Configurations for Remote Debugging:
-
-      ```json
-      {
-        "version": "0.2.0",
-        "configurations": [
-          {
-            "name": "Python: Remote Attach",
-            ...
-          },
-          {
-            "name": "Python: Remote Attach Celery Worker",
-            ...
-          }
-        ]
-      }
-      ```
-
-It is now possible to debug the containerized Nautobot and Celery Worker using the VS Code debugger.
-
-After restarting the Celery-Worker container you need to restart the debug session.

nautobot/docs/development/core/extending-models.md

@@ -1,93 +0,0 @@
-# Extending Models
-
-Below is a list of tasks to consider when adding a new field to a core model.
-
-## Generate and run database migrations
-
-Django migrations are used to express changes to the database schema. In most cases, Django can generate these automatically, however very complex changes may require manual intervention. Always remember to specify a short but descriptive name when generating a new migration.
-
-!!! warning
-    Assert that you have installed Nautobot in your development environment using `poetry install` so that changes you make to migrations will apply to the source tree!
-
-```no-highlight
-nautobot-server makemigrations <app> -n <name>
-nautobot-server migrate
-```
-
-Where possible, try to merge related changes into a single migration. For example, if three new fields are being added to different models within an app, these can be expressed in the same migration. You can merge a new migration with an existing one by combining their `operations` lists.
-
-!!! note
-    Migrations can only be merged within a release. Once a new release has been published, its migrations cannot be altered (other than for the purpose of correcting a bug).
-
-## Add validation logic to `clean()`
-
-If the new field introduces additional validation requirements (beyond what's included with the field itself), implement them in the model's `clean()` method. Remember to call the model's original method using `super()` before or after your custom validation as appropriate:
-
-```python
-class Foo(models.Model):
-
-    def clean(self):
-
-        super().clean()
-
-        # Custom validation goes here
-        if self.bar is None:
-            raise ValidationError()
-```
-
-## Update relevant querysets
-
-If you're adding a relational field (e.g. `ForeignKey`) and intend to include the data when retrieving a list of objects, be sure to include the field using `select_related()` (for `ForeignKey` forward lookups) and/or `prefetch_related()` (for `ForeignKey` reverse lookups and `ManyToManyField` lookups) as appropriate. This will optimize the view and avoid extraneous database queries.
-
-## Update API serializer
-
-Extend the model's API serializer in `nautobot.<app>.api.serializers` to include the new field, if necessary.
-
-+++ 2.0.0
-Most model serializers now use `fields = [__all__]`, in which case you do not have to explicitly include the new field in the model's API serializer. The serializer will automatically pick up the field and render it according to Nautobot standards. If the default rendering does not meet your API needs, you can explicitly declare the field on the serializer.
-
-## Add field to forms
-
-Extend any forms to include the new field as appropriate. Common forms include:
-
-* **Create/edit** - Manipulating a single object
-* **Bulk edit** - Performing a change on many objects at once
-* **Filter** - Displays the options available for filtering a list of objects (both UI and API)
-
-## Extend object filter set
-
-If the new field should be filterable, add it to the `FilterSet` for the model. If the field should be searchable, remember to reference it in the FilterSet's `SearchFilter` definition.
-
-All filtersets should inherit from `BaseFilterSet` or `NautobotFilterSet` as appropriate to the scope of the model's functionality.
-
-## Add column to object table
-
-If the new field will be included in the object list view, add a column to the model's table. For simple fields, adding the field name to `Meta.fields` will be sufficient. More complex fields may require declaring a custom column.
-
-## Update the UI templates
-
-Edit the object's view template to display the new field. There may also be a custom add/edit form template that needs to be updated.
-
-## Validate the new field in GraphQL
-
-If the model is already part of the GraphQL schema, the new field will be included automatically. Validate that the new field is rendering properly in GraphQL. If the field is not compatible with GraphQL or shouldn't be included in GraphQL it's possible to exclude a specific field in the GraphQL Type Object associated with this specific model. You can refer to the [graphene-django documentation](https://docs.graphene-python.org/projects/django/en/latest/queries/#specifying-which-fields-to-include) for additional information.
-
-Note that if you're using the `convert_django_field` registry to override the default GraphQL representation for any field type, this override must be registered within the relevant app's `ready()` function, rather than at module import time.
-
-## Create/extend test cases
-
-Create or extend the relevant test cases to verify that the new field and any accompanying validation logic perform as expected. This is especially important for relational fields. Nautobot incorporates various test suites, including:
-
-* API serializer/view tests (should be based on `nautobot.core.testing.api.APIViewTestCases`)
-* Filter tests (should be based on `nautobot.core.testing.filters.FilterTestCases`)
-* Form tests
-* Model tests (should be based on `nautobot.core.testing.models.ModelTestCases`)
-* View tests (should be based on `nautobot.core.testing.views.ViewTestCases`)
-
-Be diligent to ensure all of the relevant test suites are adapted or extended as necessary to test any new functionality.
-
-## Update the model's documentation
-
-Each model has a dedicated page in the documentation, typically either at `docs/user-guide/core-data-model/<app>/<model>.md`, or in the case of the `extras` app, at `docs/user-guide/platform-functionality/<model>.md`. Some models are exceptions to this pattern; if so, they should declare the path as a `documentation_static_path` attribute on the model class definition.
-
-Update this file to include any relevant information about the new field. Note that this documentation page should automatically be accessible through the web UI via a "question mark" icon on the corresponding model create/edit page.

nautobot/docs/development/core/generic-views.md

@@ -1,65 +0,0 @@
-# Generic Views
-
-* `ObjectView` - Retrieve a single object for display.
-* `ObjectListView` - List a series of objects.
-* `ObjectEditView` - Create or edit a single object.
-* `ObjectDeleteView` - Delete a single object.
-* `BulkCreateView` - Create new objects in bulk.
-* `BulkDeleteView` - Delete objects in bulk.
-* `BulkEditView` - Edit objects in bulk.
-* `BulkImportView` - Import objects in bulk from CSV.
-
-Once you define a view by subclassing any of the above generic classes, you must register it in your `urls.py` as usual. There are a few things to be aware of here:
-
-* Reverse URL naming needs to follow a template of `{modelname}_{method}` where the **model name** is lowercased model class name from `models.py` and **method** is the purpose of the view. E.g. `_list`, `_add`, `_edit`.
-* The default rendering context for the `ObjectListView` includes some standard `action_buttons` for interacting with the listed model. By default this view defines `action_buttons = ("add", "import", "export")`. The `export` action is handled automatically by `ObjectListView`, but the `add` and `import` actions need corresponding views in order to work. In other words, if you implement an `ObjectListView` and do not override its `action_buttons`, you must also implement and register the corresponding `ObjectEditView` and `BulkImportView` subclasses as well.
-
-!!! warning
-    If you're missing any of the aforementioned URLs/Views, when accessing your list view it will result in a error `Reverse for 'None' not found. 'None' is not a valid view function or pattern name.`
-
-If you do not need `ObjectEditView` and/or `BulkImportView` for your particular model, as an alternative you can simply update your `ObjectListView` subclass to overload the action buttons.  For example, `action_buttons = ("add",)` or if none are required `action_buttons = ()`.
-
-To demonstrate these concepts we can look at the `example_plugin` included in the Nautobot repository.
-
-The example plugin has a simple model called `ExampleModel`:
-
-```python
-class ExampleModel(OrganizationalModel):
-    name = models.CharField(max_length=20, help_text="The name of this Example.")
-    number = models.IntegerField(default=100, help_text="The number of this Example.")
-
-    class Meta:
-        ordering = ["name"]
-```
-
-The list view for this model subclasses `generic.ObjectListView` and does **not** overload the `action_buttons`:
-
-```python
-class ExampleModelListView(generic.ObjectListView):
-    """List `ExampleModel` objects."""
-
-    queryset = ExampleModel.objects.all()
-    filterset = filters.ExampleModelFilterSet
-    filterset_form = forms.ExampleModelFilterForm
-    table = tables.ExampleModelTable
-```
-
-!!! info
-    Since `action_buttons` was not overloaded, `action_buttons = ("add", "import", "export")` is inherited.
-
-In order for this to work properly we expect to see `urls.py` have each of the required URLs/Views implemented with the template mentioned above.
-
-```python
-urlpatterns = [
-    ...
-    path("models/", views.ExampleModelListView.as_view(),name="examplemodel_list"),
-    path("models/add/", views.ExampleModelEditView.as_view(), name="examplemodel_add"),
-    ...
-    path(
-        "models/import/",
-        views.ExampleModelBulkImportView.as_view(),
-        name="examplemodel_import",
-    ),
-    ...
-]
-```