Merge pull request #126 from nautobot/develop

See #107 for detail commits, update to nornir-nautobot 3.0 (#107)
nautobot · Oct 1, 2023 · 69afbe7 · 69afbe7
2 parents 7a002d1 + b6c9f9f
commit 69afbe7
Show file tree

Hide file tree

Showing 68 changed files with 2,428 additions and 1,595 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -14,7 +14,7 @@ jobs:
       - name: "Set up Python"
         uses: "actions/setup-python@v2"
         with:
-          python-version: "3.9.7"
+          python-version: "3.11"
       - name: "Install Python Packages for Linting"
         run: "pip install --upgrade pip wheel invoke toml black"
       - name: "Linting: Black"
@@ -29,7 +29,7 @@ jobs:
       - name: "Set up Python"
         uses: "actions/setup-python@v2"
         with:
-          python-version: "3.9"
+          python-version: "3.11"
       - name: "Install Python Packages for Linting"
         run: "pip install --upgrade pip wheel invoke toml bandit"
       - name: "Linting: Bandit"
@@ -46,7 +46,7 @@ jobs:
       - name: "Set up Python"
         uses: "actions/setup-python@v2"
         with:
-          python-version: "3.9"
+          python-version: "3.11"
       - name: "Install Python Packages for Linting"
         run: "pip install --upgrade pip wheel invoke toml pydocstyle"
       - name: "Linting: pydocstyle"
@@ -63,7 +63,7 @@ jobs:
       - name: "Set up Python"
         uses: "actions/setup-python@v2"
         with:
-          python-version: "3.9"
+          python-version: "3.11"
       - name: "Install Python Packages for Linting"
         run: "pip install --upgrade pip wheel invoke toml flake8"
       - name: "Linting: flake8"
@@ -80,7 +80,7 @@ jobs:
       - name: "Set up Python"
         uses: "actions/setup-python@v2"
         with:
-          python-version: "3.9"
+          python-version: "3.11"
       - name: "Install Python Packages for Linting"
         run: "pip install --upgrade pip wheel invoke toml yamllint"
       - name: "Linting: yamllint"
@@ -95,7 +95,7 @@ jobs:
       - name: "Set up Python"
         uses: "actions/setup-python@v2"
         with:
-          python-version: "3.9"
+          python-version: "3.11"
       - name: "Install Python Packages for Setup"
         run: "pip install invoke poetry toml"
       - name: "Build Container"
@@ -113,7 +113,7 @@ jobs:
       - name: "Set up Python"
         uses: "actions/setup-python@v2"
         with:
-          python-version: "3.9"
+          python-version: "3.11"
       - name: "Install Python Packages for Linting"
         run: "pip install invoke poetry toml"
       - name: "Build Container"
@@ -126,7 +126,7 @@ jobs:
     strategy:
       fail-fast: true
       matrix:
-        python-version: ["3.7", "3.8", "3.9", "3.10"]
+        python-version: ["3.8", "3.9", "3.10", "3.11"]
     runs-on: "ubuntu-20.04"
     env:
       PYTHON_VER: "${{ matrix.python-version }}"
@@ -136,7 +136,7 @@ jobs:
       - name: "Set up Python"
         uses: "actions/setup-python@v2"
         with:
-          python-version: "3.9"
+          python-version: "3.11"
       - name: "Install Python Packages for Linting"
         run: "pip install invoke poetry toml"
       - name: "Build Container"
@@ -155,7 +155,7 @@ jobs:
       - name: "Set up Python"
         uses: "actions/setup-python@v2"
         with:
-          python-version: "3.9"
+          python-version: "3.11"
       - name: "Install Python Packages for Linting"
         run: "pip install invoke poetry toml"
       - name: "Set env"
@@ -184,7 +184,7 @@ jobs:
       - name: "Set up Python"
         uses: "actions/setup-python@v2"
         with:
-          python-version: "3.9"
+          python-version: "3.11"
       - name: "Install Python Packages"
         run: "pip install poetry"
       - name: "Set env"

diff --git a/docs/dev/CHANGELOG.md b/docs/dev/CHANGELOG.md
@@ -1,31 +1,45 @@
 # Changelog
 
+
+## 3.0.0
+
+- [#107](https://github.com/nautobot/nornir-nautobot/pull/107) Changed the dispatcher method function signature - Breaking change
+- [#107](https://github.com/nautobot/nornir-nautobot/pull/107) Restructured file layout to accommodate new dispatcher - Breaking change
+- [#107](https://github.com/nautobot/nornir-nautobot/pull/107) Removed NornirLogger - Breaking Change
+- [#107](https://github.com/nautobot/nornir-nautobot/pull/107) Updated to Nautobot loggin standard based on Python standard library logger
+- [#107](https://github.com/nautobot/nornir-nautobot/pull/107) Migrated filters to Nautobot 2.0 standards, e.g. location
+- [#107](https://github.com/nautobot/nornir-nautobot/pull/107) Added error codes e.g. E1001, to better facilitate troubleshooting
+- [#107](https://github.com/nautobot/nornir-nautobot/pull/107) Added ability to control what `tcp_port` number to use in the `check_connectivity` method
+- [#107](https://github.com/nautobot/nornir-nautobot/pull/107) Updated to latest NTC development standards and updated dependencies
+
+
 ## v2.6.1
 
-- (#108) Add enable threading option
-- (#109) Patch merge_config methods return values
+- [#108](https://github.com/nautobot/nornir-nautobot/pull/108) Add enable threading option
+- [#109](https://github.com/nautobot/nornir-nautobot/pull/109) Patch merge_config methods return values
+
 
 ## v2.6.0
 
-- (#96) Changes backup_file to be conditional for get_config
-- (#98) Adds merge_config method
+- [#96](https://github.com/nautobot/nornir-nautobot/pull/96) Changes backup_file to be conditional for get_config
+- [#98](https://github.com/nautobot/nornir-nautobot/pull/98) Adds merge_config method
 
 ## v2.5.0
 
-- (#93) Updates Nornir-Netmiko to 1.0.0 release
-- (#97) Adds Jinja Environment option to generate_config
+- [#93](https://github.com/nautobot/nornir-nautobot/pull/93) Updates Nornir-Netmiko to 1.0.0 release
+- [#97](https://github.com/nautobot/nornir-nautobot/pull/97) Adds Jinja Environment option to generate_config
 
 ## v2.4.0
 
-- (#61) Be more clear on error messages by @itdependsnetworks
-- (#66) Add basic typing to the methods in logger by @KalleDK
-- (#75) Documentation refactor by @susanhooks
-- (#77) added ICX/Fastiron Nornir Driver by @pato23arg
-- (#78) Fix RTD docs build by @cmsirbu
-- (#83) Adds provision_config method by @joewesch
-- (#76) Mikrotik RouterOS CLI Support by @pato23arg
-- (#79) Mikrotik RouterOS API support by @pato23arg
-- (#85) Ruckus Smartzone WLC and Access Point Driver by @pato23arg
+- [#61](https://github.com/nautobot/nornir-nautobot/pull/61) Be more clear on error messages by @itdependsnetworks
+- [#66](https://github.com/nautobot/nornir-nautobot/pull/66) Add basic typing to the methods in logger by @KalleDK
+- [#75](https://github.com/nautobot/nornir-nautobot/pull/75) Documentation refactor by @susanhooks
+- [#77](https://github.com/nautobot/nornir-nautobot/pull/77) added ICX/Fastiron Nornir Driver by @pato23arg
+- [#78](https://github.com/nautobot/nornir-nautobot/pull/78) Fix RTD docs build by @cmsirbu
+- [#83](https://github.com/nautobot/nornir-nautobot/pull/83) Adds provision_config method by @joewesch
+- [#76](https://github.com/nautobot/nornir-nautobot/pull/76) Mikrotik RouterOS CLI Support by @pato23arg
+- [#79](https://github.com/nautobot/nornir-nautobot/pull/79) Mikrotik RouterOS API support by @pato23arg
+- [#85](https://github.com/nautobot/nornir-nautobot/pull/85) Ruckus Smartzone WLC and Access Point Driver by @pato23arg
 
 ## New Contributors
 * @KalleDK made their first contribution in https://github.com/nautobot/nornir-nautobot/pull/66
@@ -36,41 +50,41 @@
 
 ## v2.3.0
 
-- (#67) fix pylint, tests, and drop py36 support #67
+- [#67](https://github.com/nautobot/nornir-nautobot/pull/67) fix pylint, tests, and drop py36 support #67
 
 ## v2.2.0
 
-- (#41) Added jinja2 filter pass to generate config
-- (#42) Added Cisco ASA mapping to default mapping
+- [#41](https://github.com/nautobot/nornir-nautobot/pull/41) Added jinja2 filter pass to generate config
+- [#42](https://github.com/nautobot/nornir-nautobot/pull/42) Added Cisco ASA mapping to default mapping
 
 ## v2.1.2
 
-- (#40) Fix nornir inventory defaults
+- [#40](https://github.com/nautobot/nornir-nautobot/pull/40) Fix nornir inventory defaults
 
 ## v2.1.1
 
-- (#31) Migrate from Travis-CI to GitHub Actions for CI
-- (#32) Fix data population when generating configurations from the dispatcher
+- [#31](https://github.com/nautobot/nornir-nautobot/pull/31) Migrate from Travis-CI to GitHub Actions for CI
+- [#32](https://github.com/nautobot/nornir-nautobot/pull/32) Fix data population when generating configurations from the dispatcher
 
 ## v2.1.0
 
-- (#26) Updates in poetry packaging for pre 1.0.0 dependencies in Nornir to allow all new up to 1.0.0 releases
+- [#26](https://github.com/nautobot/nornir-nautobot/pull/26) Updates in poetry packaging for pre 1.0.0 dependencies in Nornir to allow all new up to 1.0.0 releases
 
 ## v2.0.3
 
-- (#24) Change import mechanism / changes deprecated function
+- [#24](https://github.com/nautobot/nornir-nautobot/pull/24) Change import mechanism / changes deprecated function
 
 ## v2.0.1
 
-- (#20) Fixes inventory failure when platform is not defined for a device
+- [#20](https://github.com/nautobot/nornir-nautobot/pull/20) Fixes inventory failure when platform is not defined for a device
 ## v2.0.0
 
-- (#18) Migrates functions to new NTC netutils library, which is removing methods previously available:
-  - compliance
-  - make_folder
-  - hostname_resolves
-  - test_tcp_port
-  - is_ip
+- [#18](https://github.com/nautobot/nornir-nautobot/pull/18) Migrates functions to new NTC netutils library, which is removing methods previously available:
+    - compliance
+    - make_folder
+    - hostname_resolves
+    - test_tcp_port
+    - is_ip
 
 ## v0.1.0 - 2020-12-27
 

diff --git a/docs/dev/CONTRIBUTING.md b/docs/dev/CONTRIBUTING.md
@@ -10,7 +10,7 @@ This section describes how to install *nornir_nautobot* for development, how to
 
 ## Python Versions
 
-This leverages Python3.6 or later. All features will be tested against 3.6 - 3.9 versions of Python.
+This leverages Python3.8 or later. All features will be tested against 3.8 - 3.11 versions of Python.
 
 ## Versioning
 
@@ -27,7 +27,7 @@ Follow these steps to set up your local development environment:
 ```bash
 # Double check your version
 $ python --version
-Python 3.7.7
+Python 3.11.1
 # Activate the Poetry environment, which will auto create the virtual environment related to the project
 $ poetry shell
 # Install project dependencies as well as development dependencies
@@ -61,7 +61,7 @@ All tests should be located within the `tests\` directory with `tests\unit` for
 The following linting tasks are required:
 
 * [Bandit](https://bandit.readthedocs.io/en/latest/)
-  * Basic security tests, should be run on Python3.6 or Python3.7
+  * Basic security tests, should be run on Python3.11
 * [Black code style](https://github.com/psf/black)
   * Code formatting with version 20.8b1. There are some differences in the format between versions 19 and 20.
 * [Flake8](https://flake8.pycqa.org/en/latest/)

diff --git a/docs/dev/migrating_to_v3.md b/docs/dev/migrating_to_v3.md
@@ -0,0 +1,17 @@
+# Migrating to v3
+
+This is intended to document the changes and considerations for migration to Nornir-Nautobot 3.0. **Please Note** this is nornir-nautobot's version number, not Nautobot's version number. This major upgrade did coincide with the release of Nautobot 2.0, but the version trains are on their own path.
+
+## Inventory Update
+
+The inventory has been updated to reflect the changes in Nautobot, specifically that `Region` and `Site` have been collapsed into Location. Please see the [inventory docs](../inventory/inventory.md) for the latest documentation.
+
+## Dispatcher Update
+
+The dispatcher function signature has substantially changed. Overall, this will allow for easier configurations to end users and specifically users of Nautobot's Golden Config plugin. Please see the relevant [dispatcher docs](../task/task.md#dispatcher-sender) for the latest documentation.
+
+The dispatcher now prefers senders in the following order, in which `framework` examples would be `netmiko` or `napalm` and `network_driver` examples would be `cisco_ios` or `arista_eos`.
+
+- If there is a custom_dispatcher, **only** use that
+- Check for the `framework` and `network_driver`
+- Check for the `framework`'s default
diff --git a/docs/inventory/inventory.md b/docs/inventory/inventory.md
@@ -39,27 +39,35 @@ With the Nornir Nautobot Inventory plugin you have the option of using all of th
 
 ## Filtering Examples
 
-For each of the examples the sites correspond to the first three letters of the devices below:
+For each of the examples the locations correspond to the first three letters of the devices below:
 
 ```python
 >>> nautobot.dcim.devices.all()
 [den-rtr01, den-rtr02, grb-rtr01, msp-rtr01, msp-rtr02, nyc-rtr01, nyc-rtr02]
 ```
 
-### Filtering Example: Select from single site
+### Filtering Example: Select from single location
 
-To filter from a single site you can use the filter site to get the devices at a single site based on the **slug** for the site:
+To filter from a single location you can use the filter location to get the devices at a single location based on the **Primary Key** for the location:
+
+> NOTE: Location names do not guarantee uniqueness in Nautobot 2.0.
+> 
+> See this document for more information:
+> 
+> https://docs.nautobot.com/projects/core/en/next/development/apps/api/platform-features/uniquely-identify-objects/
+>
+> *TLDR*: To query for a unique location, use the `id` object or a combination of fields (attributes) that are specific to the unique location.
 
 ```python
-site = "msp"
+location = "msp"
 
 my_nornir = InitNornir(
     inventory={
         "plugin": "NautobotInventory",
         "options": {
             "nautobot_url": os.getenv("NAUTOBOT_URL"),
             "nautobot_token": os.getenv("NAUTBOT_TOKEN"),
-            "filter_parameters": {"site": site},
+            "filter_parameters": {"location": location},
             "ssl_verify": False,
         },
     },
@@ -73,26 +81,26 @@ print(my_nornir.inventory.hosts.keys())
 This results in:
 
 ```
-root@2e8168a1c3e7:/local# python examples/filter_site.py 
+root@2e8168a1c3e7:/local# python examples/filter_location.py 
 Hosts found: 2
 dict_keys(['msp-rtr01', 'msp-rtr02'])
 ```
 
 
-### Filter Example: Multiple Sites
+### Filter Example: Multiple Locations
 
-To search within multiple sites, pass a list of site slugs. In the example below, it is the same as the previous example with a list passed in instead of a single string.
+To search within multiple locations, pass a list of location Primary Keys. In the example below, it is the same as the previous example with a list passed in instead of a single string.
 
 ```python
-site = ["msp", "grb"]
+location = ["msp", "grb"]
 
 my_nornir = InitNornir(
     inventory={
         "plugin": "NautobotInventory",
         "options": {
             "nautobot_url": os.getenv("NAUTOBOT_URL"),
             "nautobot_token": os.getenv("NAUTBOT_TOKEN"),
-            "filter_parameters": {"site": site},
+            "filter_parameters": {"location": location},
             "ssl_verify": False,
         },
     },
@@ -106,25 +114,25 @@ print(my_nornir.inventory.hosts.keys())
 Results in:
 
 ```
-root@2e8168a1c3e7:/local# python examples/filter_multiple_sites.py 
+root@2e8168a1c3e7:/local# python examples/filter_multiple_locations.py 
 Hosts found: 3
 dict_keys(['grb-rtr01', 'msp-rtr01', 'msp-rtr02'])
 ```
 
-### Filtering Example: Not at a site
+### Filtering Example: Not at a location
 
 The negative filters also are supported. These are all of the filters possible. Here we will search for devices **not** at _MSP_:
 
 ```python
-not_site = "msp"
+not_location = "msp"
 
 my_nornir = InitNornir(
     inventory={
         "plugin": "NautobotInventory",
         "options": {
             "nautobot_url": os.getenv("NAUTOBOT_URL"),
             "nautobot_token": os.getenv("NAUTBOT_TOKEN"),
-            "filter_parameters": {"site__n": not_site},
+            "filter_parameters": {"location__n": not_location},
             "ssl_verify": False,
         },
     },
@@ -138,7 +146,7 @@ print(my_nornir.inventory.hosts.keys())
 Results in:
 
 ```
-root@2e8168a1c3e7:/local# python examples/filter_negate_site.py 
+root@2e8168a1c3e7:/local# python examples/filter_negate_location.py 
 Hosts found: 5
 dict_keys(['den-rtr01', 'den-rtr02', 'grb-rtr01', 'nyc-rtr01', 'nyc-rtr02'])
 ```

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,5 +1,5 @@
-mkdocs==1.3.1
-mkdocs-material==8.3.9
-mkdocstrings==0.19
-mkdocstrings-python==0.7.1
+mkdocs==1.5.2
+mkdocs-material==9.2.4
+mkdocstrings==0.22.0
+mkdocstrings-python==1.5.2
 mkdocs-version-annotations==1.0.0