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

nautobot/docs/development/core/navigation-menu.md

@@ -1,142 +0,0 @@
-# Populating the Navigation Menu
-
-Both core applications and plugins can contribute items to the navigation menu by defining `menu_items` inside of their app's `navigation.py`. Using the key and weight system, a developer can integrate amongst existing menu tabs, groups, items and buttons and/or create entirely new menus as desired.
-
-## Modifying Existing Menu
-
-By defining an object with the same identifier, a developer can modify existing objects. The example below shows modifying an existing tab to have a new group.
-
-A tab object is being created with the same identifier as an existing object using the `name` attribute. Then a group is being created with a weight of `150`, which means it will appear between the already defined `Circuits` and `Provider` groups.
-
-!!! tip
-    Weights for already existing items can be found in the nautobot source code (in `navigation.py`) or with a web session open to your nautobot instance, you can inspect an element of the navbar using the developer tools. Each type of element will have an attribute `data-{type}-weight`. The type can be `tab`, `group`, `item` or `button`.
-
-This pattern works for modifying all objects in the tree. New items can be added to existing groups and new buttons can be added to existing items.
-
-``` python
-menu_tabs = (
-    NavMenuTab(
-        name="Circuits",
-        groups=(
-            NavMenuGroup(
-                name="Example Circuit Group",
-                weight=150,
-                items=(
-                    NavMenuItem(
-                        link="plugins:example_plugin:examplemodel_list",
-                        name="Example Model",
-                        permissions=[
-                            "example_plugin.view_examplemodel"
-                        ],
-                        buttons=(
-                            NavMenuAddButton(
-                                link="plugins:example_plugin:examplemodel_add",
-                                permissions=[
-                                    "example_plugin.add_examplemodel",
-                                ],
-                            ),
-                            NavMenuImportButton(
-                                link="plugins:example_plugin:examplemodel_import",
-                                permissions=[
-                                    "example_plugin.add_examplemodel"
-                                ],
-                            ),
-                        ),
-                    ),
-                ),
-            ),
-        ),
-    ),
-)
-```
-
-## Adding a New Menu
-
-The code below shows how to add a new tab to the navbar. A tab is defined by a `NavMenuTab` object. Similarly a group is defined using `NavMenuGroup`. Both of these objects are used as containers for actual items.
-
-The position in the navigation menu is defined by the weight. The lower the weight the closer to the start of the menus the object will be. All core objects have weights in multiples of 100, meaning there is plenty of space around the objects for plugins to customize.
-
-Below you can see `Example Tab` has a weight value of `150`. This means the tab will appear between `Organization` and `Devices`.
-
-``` python
-from nautobot.core.apps import NavMenuAddButton, NavMenuGroup, NavMenuItem, NavMenuImportButton, NavMenuTab
-
-menu_items = (
-    NavMenuTab(
-        name="Example Tab",
-        weight=150,
-        groups=(
-            NavMenuGroup(
-                name="Example Group 1",
-                weight=100,
-                items=(
-                    NavMenuItem(
-                        link="plugins:example_plugin:examplemodel_list",
-                        link_text="Example Model",
-                        permissions=[
-                            "example_plugin.view_examplemodel"
-                        ],
-                        buttons=(
-                            NavMenuAddButton(
-                                link="plugins:example_plugin:examplemodel_add",
-                                permissions=[
-                                    "example_plugin.add_examplemodel",
-                                ],
-                            ),
-                            NavMenuImportButton(
-                                link="plugins:example_plugin:examplemodel_import",
-                                permissions=[
-                                    "example_plugin.add_examplemodel"
-                                ],
-                            ),
-                        ),
-                    ),
-                ),
-            ),
-        ),
-    ),
-)
-```
-
-## Classes and Attributes
-
-!!! note
-    For the `NavMenuTab`, `NavMenuGroup`, and `NavMenuItem` objects to be hidden when the user does not have permissions, set `HIDE_RESTRICTED_UI = True` in the `nautobot_config.py`.
-    Please refer to [HIDE_RESTRICTED_UI](../../user-guide/administration/configuration/optional-settings.md#hide_restricted_ui)
-
-A `NavMenuTab` has the following attributes:
-
-* `name` - Display name to be shown in navigation menu
-* `weight` - Defines the position the object should be displayed at (optional)
-* `permissions` - A list of permissions required to display this link (optional)
-* `groups` - List or tuple of `NavMenuGroup`
-
-A `NavMenuGroup` has the following attributes:
-
-* `name` - Display name to be shown in navigation menu
-* `weight` - Defines the position the object should be displayed at (optional)
-* `permissions` - A list of permissions required to display this link (optional)
-* `items` - List or tuple of `NavMenuItem`
-
-A `NavMenuItem` has the following attributes:
-
-* `link` - The name of the URL path to which this menu item links
-* `name` - The text presented to the user
-* `weight` - Defines the position the object should be displayed at (optional)
-* `permissions` - A list of permissions required to display this link (optional)
-* `buttons` - An iterable of NavMenuButton (or subclasses of NavMenuButton) instances to display (optional)
-
-!!! note
-    Any buttons associated within a menu item will be hidden if the user does not have permission to access the menu item, regardless of what permissions are set on the buttons.
-
-A `NavMenuButton` has the following attributes:
-
-* `title` - The tooltip text (displayed when the mouse hovers over the button)
-* `link` - The name of the URL path to which this button links
-* `weight` - Defines the position the object should be displayed at (optional)
-* `icon_class` - Button icon CSS classes (Nautobot currently supports [Material Design Icons](https://materialdesignicons.com) or one of the choices provided by `ButtonActionIconChoices`)
-* `button_class` - One of the choices provided by `ButtonActionColorChoices` (optional)
-* `permissions` - A list of permissions required to display this button (optional)
-
-!!! note
-    `NavMenuAddButton` and `NavMenuImportButton` are subclasses of `NavMenuButton` that can be used to provide the commonly used "Add" and "Import" buttons.

nautobot/docs/development/core/react-ui.md

@@ -1,137 +0,0 @@
-# Building the React UI
-
-## Introduction
-
-Nautobot 2.0 introduces a new user interface built on React. This new UI will eventually be a complete replacement for the previous Django-based UI. It currently prioritizes read-only operations for core views. In subsequent releases, more operations and features will become available in this new UI.
-
-## Design Patterns
-
-A key change with moving to a client-side application for the user interface is that the application is now stateful. This means that the application is aware of the current state of the user interface, and can update the UI without requiring a page refresh. This is a significant change from the previous Django-based UI, which was stateless. In order to achieve this, a perspective on how the UI is rendered is required. Since much of the data is retrieved from the API, the UI is rendered in two phases:
-
-- **Phase 1**: The UI is rendered with placeholder data, and the API is queried for the actual data
-- **Phase 2**: The UI is re-rendered with the actual data
-
-This encourages the UI to be built in a way that is resilient to changes in the data, and allows the UI to be updated without requiring a page refresh. Placeholder data can either be empty, for example on a list view this is easy: an empty list `[]`. But in more complex cases, a view may choose to show a loading indicator until the data is available.
-
-In most cases, we build the UI with the preference we only display the final component once the data is available and display a loading indicator until then.
-
-### State Management
-
-The React UI is built with a concept of state management, which is handled by Redux. There is a single state store that is used to manage the state of the entire application, split into two core sections:
-
-- **Application State**: Managed by Redux
-    - Is the user logged in?
-    - What is the current user?
-    - What is the current page?
-    - What are the models and navigation menu the user can access?
-- **API State**: Managed by RTK Query (a subset library provided by Redux)
-    - Previous responses to detail and list requests
-
-These sections are known as "slices" of state, and have their own methods for updating and retrieving state. For more information on Redux, see the [Redux documentation](https://redux.js.org/).
-
-### Hooks
-
-The React UI uses hooks to manage state and side effects. Hooks are functions that let you "hook into" React state and lifecycle features. To learn more about hooks, see the [React Hooks documentation](https://react.dev/reference/react).
-
-## Getting Started With Development
-
-The libraries and tools used to build the React UI are:
-
-- [React](https://reactjs.org/)
-- [React Router](https://reactrouter.com/)
-- [Chakra UI](https://chakra-ui.com/)
-- [Redux](https://redux.js.org/)
-- [React Redux](https://react-redux.js.org/)
-- [RTK Query](https://redux-toolkit.js.org/rtk-query/overview)
-
-### Customizing a Model's detail view
-
-Currently, it is possible to customize the layout, groups, and fields of a detail view for a model. You can achieve this by creating groups that contain fields, which can be positioned either in the left column or the right column. To customize the detail view of your model, follow the instructions below:
-
-```python
-class ExampleModelSerializer(ModelSerializer):
-    ...
-    class Meta:
-        ...
-        detail_view_config = {
-            "layout": [
-                {
-                    "Group Name 1": {"fields": ["name", ...]},
-                    "Group Name 2": {"fields": [...]},
-                },
-                {
-                    "Group Name 3": {"fields": [...]},
-                    "Group Name 4": {"fields": [...]},
-                },
-            ],
-            "include_others": False
-        }
-```
-
-In the above example, we add the `detail_view_config` attribute to the Serializer's inner `Meta` class. The value of this attribute is a dict containing `layout` and `include_others`(optional). the `layout` is a list containing two dictionaries, each representing the two columns of the detail view. The first dictionary represents the fields in the first column, while the second dictionary represents the fields in the second column. Each dictionary consists of a key-value pair, where the key is the name of the grouping, and the value is a list of the model fields that should be included in that grouping.
-The optional key `include_others`, when set to `True`, adds missing serializer fields from the `detail_view_config["layout"]` to the view_config layout.
-
-If a `detail_view_config` is not provided to the Model Serializer, the default view configuration will be used. The default view configuration displays all non-many-to-many (non-m2m) fields in the left column, and many-to-many (m2m) fields in the right column, with each field having its own grouping.
-
-!!! note
-    `Other Fields` cannot be used as a group name as this is a reserved keyword.
-
-### Documenting Your Code
-
-The UI uses JS Doc to document the code. For more information on JS Doc, see the [JS Doc website](https://jsdoc.app/).
-
-We prefer to use the `@param` and `@returns` tags to document the parameters and return values of functions. For example:
-
-```js
-/**
- * Given an API payload with session information, updates the state with the session information
- * @param {Object} state - The current state
- * @param {Object} action - The called-with payload and action type
- * @returns The updated state
- */
-updateAuthStateWithSession(state, action) {
-    //... 
-}
-```
-
-### Linting & Formatting
-
-#### Linting
-
-The UI uses ESLint to lint the code. For more information on ESLint, see the [ESLint website](https://eslint.org/).
-
-To check for linting errors, run the following command:
-
-```shell
-invoke eslint
-```
-
-To automatically fix some linting errors, run the following command:
-
-```shell
-invoke eslint -a
-```
-
-#### Formatting
-
-The UI uses Prettier to format the code. For more information on Prettier, see the [Prettier website](https://prettier.io/).
-
-To check for linting errors, run the following command:
-
-```shell
-invoke prettier
-```
-
-To automatically format the code, run the following command:
-
-```shell
-invoke prettier -a
-```
-
-## Additional Links
-
-Here are some links to resources that may be helpful when working with the React UI:
-
-- [React and Effects](https://react.dev/learn/synchronizing-with-effects)
-- [RTK Query and Asynchronous Hooks](https://redux-toolkit.js.org/rtk-query/usage/queries#query-hook-options)
-- [Using useDispatch](https://react-redux.js.org/api/hooks#usedispatch)

nautobot/docs/development/core/release-checklist.md

@@ -1,312 +0,0 @@
-# Release Checklist
-
-This document is intended for Nautobot maintainers and covers the steps to perform when releasing new versions.
-
-## Minor Version Bumps
-
-### Update Requirements
-
-Required Python packages are maintained in two files: `pyproject.toml` and `poetry.lock`.
-
-#### The `pyproject.toml` file
-
-Python packages are defined inside of `pyproject.toml`. The `[tool.poetry.dependencies]` section of this file contains a list of all the packages required by Nautobot.
-
-Where possible, we use [tilde requirements](https://python-poetry.org/docs/dependency-specification/#tilde-requirements) to specify a minimal version with some ability to update, for example:
-
-```toml
-# REST API framework
-djangorestframework = "~3.12.2"
-```
-
-This would allow Poetry to install `djangorestframework` versions `>=3.12.2` but `<3.13.0`.
-
-#### The `poetry.lock` file
-
-The other file is `poetry.lock`, which is managed by Poetry and contains package names, versions, and other metadata.
-
-Each of the required packages pinned to its current stable version. When Nautobot is installed, this file is used to resolve and install all dependencies listed in `pyproject.toml`, but Poetry will use the exact versions found in `poetry.lock` to ensure that a new release of a dependency doesn't break Nautobot.
-
-!!! warning
-    You must never directly edit this file. You will use `poetry update` commands to manage it.
-
-#### Run `poetry update`
-
-Every minor version release should refresh `poetry.lock`, so that it lists the most recent stable release of each package. To do this:
-
-1. Review each requirement's release notes for any breaking or otherwise noteworthy changes.
-2. Run `poetry update <package>` to update the package versions in `poetry.lock` as appropriate.
-3. If a required package requires updating to a new release not covered in the version constraints for a package as defined in `pyproject.toml`, (e.g. `Django ~3.1.7` would never install `Django >=4.0.0`), update it manually in `pyproject.toml`.
-4. Run `poetry install` to install the refreshed versions of all required packages.
-5. Run all tests and check that the UI and API function as expected.
-
-!!! hint
-    You may use `poetry update --dry-run` to have Poetry automatically tell you what package updates are available and the versions it would upgrade.
-
-### Update Static Libraries
-
-Update the following static libraries to their most recent stable release:
-
-* [Bootstrap 3](https://getbootstrap.com/docs/3.4)
-* [Material Design Icons](https://materialdesignicons.com/)
-* [Select2](https://github.com/select2/select2/releases)
-* [jQuery](https://jquery.com/download/)
-* [jQuery UI](https://jqueryui.com/)
-
-### Link to the Release Notes Page
-
-Add the release notes (`docs/release-notes/X.Y.md`) to the table of contents within `mkdocs.yml`, and point `index.md` to the new file.
-
-### Verify and Revise the Install Documentation
-
-Follow the [install instructions](../../user-guide/administration/installation/nautobot.md) to perform a new production installation of Nautobot.
-
-The goal of this step is to walk through the entire install process *as documented* to make sure nothing there needs to be changed or updated, to catch any errors or omissions in the documentation, and to ensure that it is current with each release.
-
-!!! tip
-    Fire up `mkdocs serve` in your development environment to start the documentation server! This allows you to view the documentation locally and automatically rebuilds the documents as you make changes.
-
-Commit any necessary changes to the documentation before proceeding with the release.
-
-### Close the Release Milestone
-
-Close the release milestone on GitHub after ensuring there are no remaining open issues associated with it.
-
----
-
-## All Releases
-
-### Verify CI Build Status
-
-Ensure that continuous integration testing on the `develop` branch is completing successfully.
-
-### Bump the Version
-
-Update the package version using `invoke version`. This command shows the current version of the project or bumps the version of the project and writes the new version back to `pyproject.toml` (for the Nautobot Python package) and `package.json` (for the Nautobot UI) if a valid bump rule is provided.
-
-The new version should ideally be a valid semver string or a valid bump rule: `patch`, `minor`, `major`, `prepatch`, `preminor`, `premajor`, `prerelease`. Always try to use a bump rule when you can.
-
-Display the current version with no arguments:
-
-```no-highlight
-invoke version
-```
-
-Example output:
-
-```no-highlight
-{
-  nautobot: '2.0.0-beta.2',
-  npm: '9.5.1',
-  node: '18.16.1',
-  ...
-}
-```
-
-Bump pre-release versions using `prerelease`:
-
-```no-highlight
-invoke version -v prerelease
-```
-
-Example output:
-
-```no-highlight
-v2.0.0-beta.3
-```
-
-For major versions, use `major`:
-
-```no-highlight
-invoke version -v major
-```
-
-Example output:
-
-```no-highlight
-v3.0.0
-```
-
-For patch versions, use `minor`:
-
-```no-highlight
-invoke version minor
-```
-
-Example output:
-
-```no-highlight
-v2.1.0
-```
-
-And lastly, for patch versions, you guessed it, use `patch`:
-
-```no-highlight
-invoke version patch
-```
-
-Example output:
-
-```no-highlight
-v2.0.1
-```
-
-The `invoke version [<version>]` command internally runs `poetry version` and `npm version` commands to handle the versioning process. However, there might be cases where you need to manually configure the version. Here's how you can do that:
-
-* **Poetry Version**: If you want to manually set the version for the Python dependencies managed by Poetry, you can refer to the [Poetry documentation](https://python-poetry.org/docs/cli/#version) on version for detailed instructions. It provides information on how to set the version directly in the `pyproject.toml` file or update it using the `poetry version` command.
-* **npm Version**: To manually configure the version for the Node.js packages managed by npm, you can refer to the official [npm documentation](https://docs.npmjs.com/cli/v9/commands/npm-version) on `npm version` for more information. It explains how to set the version directly in the `package.json` file or update it using the `npm version` command.
-
-### Update the Changelog
-
-Create a release branch off of `develop` (`git checkout -b release/1.4.3 develop`)
-
-Generate release notes with `towncrier build --version 1.4.3` and answer `yes` to the prompt `Is it okay if I remove those files? [Y/n]:`. This will update the release notes in `nautobot/docs/release-notes/version-1.4.md`, stage that file in git, and `git rm` all of the fragments that have now been incorporated into the release notes.
-
-Run `invoke markdownlint` to make sure the generated release notes pass the linter checks.
-
-Check the git diff to verify the changes are correct (`git diff --cached`).
-
-Commit and push the staged changes.
-
-!!! important
-    The changelog must adhere to the [Keep a Changelog](https://keepachangelog.com/) style guide.
-
-### Submit Pull Request
-
-Submit a pull request titled **"Release vX.Y.Z"** to merge your release branch into `main`. Copy the documented release notes into the pull request's body.
-
-Once CI has completed on the PR, merge it.
-
-!!! important
-    Do not squash merge this branch into `main`. Make sure to select `Create a merge commit` when merging in GitHub.
-
-### Create a New Release Tag
-
-You need to create a release tag locally so that you can use it later when you draft the new release for nautobot, for example, `v1.4.3`.
-To create the tag locally:
-
-```bash
-$ git tag v1.4.3
-```
-
-To list all the tags to see if it is created successfully:
-
-```bash
-$ git tag
-```
-
-To push the tag upstream:
-
-```bash
-$ git push origin v1.4.3
-```
-
-### Create a New Release
-
-Draft a [new release](https://github.com/nautobot/nautobot/releases/new) with the following parameters.
-
-* **Tag:** Current version (e.g. `v1.0.0`)
-
-!!! warning
-    You will need to create a new release tag locally **before** you draft the new release. To create a new release tag, follow the steps outlined [here](#create-a-new-release-tag).
-
-* **Target:** `main`
-* **Title:** Version and date (e.g. `v1.0.0 - 2021-06-01`)
-* **Release Notes:** Follow the steps below
-
-1. Click on **Generate release notes** button and you should see some release notes auto-generated by GitHub.
-2. Copy and paste the changelog entries newly generated by towncrier in `nautobot/docs/release-notes/version-1.4.md` from your previous pull request to the auto-generated release notes on top of the **What's Changed** section.
-3. Change the heading **What's Changed** to **Contributors**.
-4. Change the entries under the heading to only the usernames of the contributors. e.g. `* Updated dockerfile by @nautobot_user in https://github.com/nautobot/nautobot/pull/123` -> `* @nautobot_user`
-5. Make sure there is no redundant username in the **Contributors** list.
-6. Leave the **New Contributors** list as it is.
-
-### Publish to PyPI
-
-Now that there is a tagged release, the final step is to upload the package to the Python Package Index.
-
-First, you'll need to render the documentation.
-
-```no-highlight
-poetry run mkdocs build --no-directory-urls --strict
-```
-
-Second, you'll need to build the Python package distributions (which will include the rendered documentation):
-
-```no-highlight
-poetry build
-```
-
-Finally, publish to PyPI using the username `__token__` and the Nautobot PyPI API token as the password. The API token can be found in the Nautobot maintainers vault (if you're a maintainer, you'll have access to this vault):
-
-```no-highlight
-poetry publish --username __token__ --password <api_token>
-```
-
-### Publish Docker Images
-
-Build the images locally:
-
-```no-highlight
-for ver in 3.8 3.9 3.10 3.11; do
-  export INVOKE_NAUTOBOT_PYTHON_VER=$ver
-  invoke buildx --target final --tag networktocode/nautobot-py${INVOKE_NAUTOBOT_PYTHON_VER}:local
-  invoke buildx --target final-dev --tag networktocode/nautobot-dev-py${INVOKE_NAUTOBOT_PYTHON_VER}:local
-done
-```
-
-Test the images locally - to do this you need to set the following in your `invoke.yml`:
-
-```yaml
----
-nautobot:
-  compose_files:
-    - "docker-compose.yml"
-    - "docker-compose.postgres.yml"
-    - "docker-compose.final.yml"
-```
-
-!!! warning
-    You should *not* include `docker-compose.dev.yml` in this test scenario!
-
-```no-highlight
-for ver in 3.8 3.9 3.10 3.11; do
-  export INVOKE_NAUTOBOT_PYTHON_VER=$ver
-  invoke stop
-  invoke integration-tests
-done
-```
-
-Push the images to GitHub Container Registry and Docker Hub
-
-```no-highlight
-docker login
-docker login ghcr.io
-for ver in 3.8 3.9 3.10 3.11; do
-  export INVOKE_NAUTOBOT_PYTHON_VER=$ver
-  invoke docker-push main
-done
-```
-
-### Bump the Development Version
-
-Create a new branch off of `main` and use `poetry version prepatch` to bump the version to the next release. Then open a pull request to the `develop` branch to update the version and sync the release notes and changelog fragment updates from `main`.
-
-For example, if you just released `v1.1.0`:
-
-```no-highlight
-poetry version prepatch
-```
-
-Example output:
-
-```no-highlight
-Bumping version from 1.1.0 to 1.1.1-alpha.0
-```
-
-!!! important
-    Do not squash merge this branch into `develop`. Make sure to select `Create a merge commit` when merging in GitHub.
-
-### Redeploy demo.nautobot.com Sandbox Environment
-
-Afer you publish the release, you need to blow away the current demo environment and redeploy it for `demo.nautobot.com`. The documentation on how to build a demo environment is available in the nautobot/sandboxes repository.

nautobot/docs/development/core/role-internals.md

@@ -1,28 +0,0 @@
-# Role Internals
-
-!!! warning
-    The section below is largely intended for developers who may need to create
-    data models of their own that implement a `role` field. Proceed at your
-    own risk!
-
-Any model that is intended to have a `role` field must use a `nautobot.extras.models.roles.RoleField` field for its foreign-key to the Role model. This field type will automatically assign a `related_name` for the reverse relationship back to the inheriting model's verbose plural name (e.g. `devices`).
-
-## `RoleField` model field
-
-The `RoleField` field type is a subclass of `django.db.models.ForeignKey`.
-
-This model field also emits its own form field to eliminate the requirement for a form field to be explicitly added to model forms.
-
-## `RoleFilter` filter field
-
-Any filter that is intended to have a `role` field must inherit from `nautobot.extras.filters.RoleModelFilterSetMixin`. This will add a `nautobot.extras.filters.RoleFilter` to the filter, which allows filtering by the `name` or `id` of the role.
-
-## Form fields
-
-Any filter form that is intended to have a `role` field must inherit from `nautobot.extras.forms.RoleModelFilterFormMixin`. This mixin adds a non-required, multiple-choice `role` filter field to the filter form.
-
-Any bulk edit form that is intended to have a `role` field must inherit from `nautobot.extras.forms.RoleModelBulkEditFormMixin`. This mixin adds a non-required `role` field to the form, and constrains the eligible role choices to the object type being edited.
-
-## Table field
-
-If you wish for a table to include a `role` column, your table must inherit from `nautobot.extras.tables.RoleTableMixin`. This includes a `ColorColumn` with the header `role` on the table.