Merge pull request #43 from networktocode/develop

Release 0.2.2

.bandit.yml

@@ -3,3 +3,4 @@ skips: []
 # No need to check for security issues in the test scripts!
 exclude_dirs:
   - "./tests/"
+  - "./docs/"

.pydocstyle.ini

@@ -1,7 +1,7 @@
 [pydocstyle]
 convention = google
 inherit = false
-match = (?!__init__).*\.py
+match = (?!__init__|conf).*\.py
 match-dir = (?!tests)[^\.].*
 # D212 is enabled by default in google convention, and complains if we have a docstring like:
 # """

.readthedocs.yml

@@ -0,0 +1,12 @@
+---
+version: 2
+
+sphinx:
+  builder: "html"
+  configuration: "docs/source/conf.py"
+  fail_on_warning: false
+
+python:
+  version: 3.7
+  install:
+    - requirements: "docs/requirements.txt"

.travis.yml

@@ -3,8 +3,6 @@
 stages:
   - name: "lint"
   - name: "test"
-  - name: "verify_pypi_release"
-    if: "tag IS present"
   - name: "deploy_github"
     if: "tag IS present"
   - name: "deploy_pypi"
@@ -45,14 +43,6 @@ jobs:
         - "invoke flake8"
         - "invoke yamllint"
         - "invoke pylint"
-    - stage: "verify_pypi_release"
-      before_script:
-        - "pip install --upgrade pip"
-        - "pip install invoke poetry toml"
-        - "poetry config virtualenvs.create false"
-        - "poetry install --no-interaction"
-      script:
-        - "invoke check-pypi-version"
     - stage: "deploy_github"
       before_script:
         - "pip install --upgrade pip"

CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## v0.2.2 - 2021-09
+
+### Added
+
+- #35 TCP/UDP Mappings
+- #31 Interface range expansion
+- #28 IPv6 Functionality to IP Module
+- #34 Interface sorting
+
+### Changed
+
+- #39 Updated docs to include automation library mappings
+- #41 Updated docs to include tcp/udp mappings
+
+### Fixed
+
+- Corrected contribution and attribution docs
+
 ## v0.2.1 - 2021-06
 
 ### Added

README.md

@@ -32,9 +32,23 @@ Functions are grouped with like functions, such as IP or MAC address based funct
 * Route - Provides the ability to provide a list of routes and an IP Address and return the longest prefix matched route.
 * VLANs - Provide the ability to convert configuration into lists or lists into configuration.
 
+# Installation
+
+Option 1: Install from PyPI.
+
+```bash
+$ pip install netutils
+```
+
+Option 2: Install from a GitHub branch, such as develop as shown below.
+
+```bash
+$ pip install git+https://github.com/networktocode/netutils.git@develop
+```
+
 # Examples
 
-While all functions come with examples in the docstrings, for quick reference of the types of problems this library intends to 
+While all functions come with examples in the docstrings, for quick reference of the types of problems this library intends to
 solve the following examples are provided.
 
 The following function will help in deploying list of VLANs and match the configuration style in a standard IOS-like configurations.
@@ -52,10 +66,10 @@ The following function will help in deploying list of VLANs and match the config
 ...         print(f"  switchport trunk allowed vlan {line}")
 ...     else:
 ...         print(f"  switchport trunk allowed vlan add {line}")
-... 
+...
   switchport trunk allowed vlan 1-3,5,6,1000,1002,1004,1006,1008,1010,1012,1014
   switchport trunk allowed vlan add 1016,1018
->>> 
+>>>
 ```
 
 You may want to compare a known password with a given encrypted password. This can help in verifying if the
@@ -111,8 +125,8 @@ issues. Functions that were known to be rewritten and their known origin.
 
 | Function | Origin |
 | -------- | ------ |
-| asn_to_int | NAPALM | 
-| is_ip | IPCal | 
+| asn_to_int | NAPALM |
+| is_ip | IPCal |
 | ip_to_bin | IPCal |
 | get_usable_range | IPCal |
 | encrypt_type7 | unknown |
@@ -141,38 +155,44 @@ The project is following Network to Code software development guidelines and are
 The project features a CLI helper based on [invoke](http://www.pyinvoke.org/) to help setup the development environment. The commands are listed below in 3 categories:
 - `dev environment`
 - `utility`
-- `testing`. 
+- `testing`
 
 Each command can be executed with `invoke <command>`. Each command also has its own help `invoke <command> --help`
 
 ### Local dev environment
 
 ```
-  build            Build all docker images.
-  clean            Remove the project specific image.
-  rebuild          Clean the Docker image and then rebuild without using cache.
+  build              Build all docker images.
+  clean              Remove the project specific image.
+  rebuild            Clean the Docker image and then rebuild without using cache.
 ```
 
-### Utility 
+### Utility
 
 ```
-  cli              Enter the image to perform troubleshooting or dev work.
+  clean-docs         Removes the build directory and all of its contents.
+  check-pypi-version Verify if the version specified already exists on PyPI.
+  cli                Enter the image to perform troubleshooting or dev work.
+  html               Creates html docs using sphinx-build command.
 ```
 
-### Testing 
+### Testing
 
 ```
-  bandit           Run bandit to validate basic static code security analysis.
-  black            Run black to check that Python files adhere to its style standards.
-  coverage         Run the coverage report against pytest.
-  flake8           Run flake8 to check that Python files adhere to its style standards.
-  pylint           Run pylint code analysis.
-  pydocstyle       Run pydocstyle to validate docstring formatting adheres to NTC defined standards.
-  tests            Run all tests for the specified name and Python version.
-  yamllint         Run yamllint to validate formatting adheres to NTC defined YAML standards.
+  bandit             Run bandit to validate basic static code security analysis.
+  black              Run black to check that Python files adhere to its style standards.
+  coverage           Run the coverage report against pytest.
+  flake8             Run flake8 to check that Python files adhere to its style standards.
+  pylint             Run pylint code analysis.
+  pydocstyle         Run pydocstyle to validate docstring formatting adheres to NTC defined standards.
+  pytest             Run pytest for the specified name and Python version.
+  tests              Run all tests for the specified name and Python version.
+  yamllint           Run yamllint to validate formatting adheres to NTC defined YAML standards.
 ```
 
 ## Questions
 
-For any questions or comments, feel free to swing by the [Network to Code slack channel](https://networktocode.slack.com/) (channel #networktocode).
+Please see [the documentation](https://netutils.readthedocs.io/) for detailed documentation on how to use netutils. For any additional questions or
+comments, feel free to swing by the [Network to Code slack channel](https://networktocode.slack.com/) (channel #networktocode).
 Sign up [here](http://slack.networktocode.com/)
+

docs/requirements.txt

@@ -0,0 +1,4 @@
+m2r2==0.2.7
+Sphinx
+toml
+sphinx-rtd-theme

docs/source/_static/schema-page.css

@@ -0,0 +1,62 @@
+body {
+  font-family: 'Fira Sans', 'Noto Sans', 'Source Sans Pro', 'Segoe UI', Roboto, 'Lucida Sans Unicode', 'Lucida Grande', 'DejaVu Sans', sans-serif;
+}
+@media (min-width: 60em) {
+  body {
+    display: flex;
+    flex-direction: row;
+  }
+}
+#jschemer-nav {
+  min-width: 15rem;
+  padding: 1em;
+}
+.jschemer-schema {
+  border: 0.05em solid #CCC;
+  border-radius: 0.25em;
+  margin: 0.5em;
+  max-width: 60em;
+  padding: 1em;
+}
+.jschemer-schema code,
+.jschemer-schema pre {
+  background-color: rgba(27, 31, 35, 0.05);
+  border-radius: 0.1em;
+  font-size: 85%;
+  line-height: 1.5;
+}
+.jschemer-schema pre {
+  padding: 1em 0.5em;
+}
+.jschemer-schema code {
+  display: inline;
+  font-family: 'Fira Mono', 'Noto Mono', 'Source Code Pro', Consolas, 'Roboto Mono', 'Lucida Console', Monaco, 'DejaVu Sans Mono', monospace;
+  font-size: 85%;
+  line-height: inherit;
+  padding: 0.2em 0.4em;
+  word-wrap: normal;
+}
+.jschemer-schema pre > code {
+  background-color: transparent;
+  padding: 0;
+}
+.jschemer-schema h1 {
+  display: inline;
+  font-size: 1.5em;
+  vertical-align: middle;
+}
+.jschemer-schema h1 code::before {
+  content: '"';
+}
+.jschemer-schema h1 code::after {
+  content: '"';
+}
+.jschemer-schema h2 {
+  font-size: 1em;
+}
+main > .jschemer-schema > details > summary > h1 {
+  font-size: 2em;
+}
+main ul {
+  list-style: disc;
+}

docs/source/_static/theme_overrides.css

@@ -0,0 +1,13 @@
+/* override table width restrictions */
+@media screen and (min-width: 767px) {
+
+   .wy-table-responsive table td {
+      /* !important prevents the common CSS stylesheets from overriding
+         this as on RTD they are loaded after this stylesheet */
+      white-space: normal !important;
+   }
+
+   .wy-table-responsive {
+      overflow: visible !important;
+   }
+}

docs/source/attribution/index.rst

@@ -0,0 +1,7 @@
+###########
+Attribution
+###########
+
+.. mdinclude:: ../../../README.md
+   :start-line: 106
+   :end-line: 140

docs/source/conf.py

@@ -0,0 +1,94 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+# pylint: disable=W,C
+import os
+import sys
+import toml
+
+sys.path.insert(0, os.path.abspath("../.."))
+sys.path.append(os.path.abspath("sphinxext"))
+toml_dict = toml.load("../../pyproject.toml")
+
+
+# -- Project information -----------------------------------------------------
+
+project = toml_dict["tool"]["poetry"]["name"]
+copyright = f"{toml_dict['tool']['poetry']['authors'][0]}, 2021"
+author = ",".join(toml_dict["tool"]["poetry"]["authors"])
+
+# The full version, including alpha/beta/rc tags
+release = toml_dict["tool"]["poetry"]["version"]
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon", "m2r2", "exec"]
+
+autodoc_default_options = {
+    "members": True,
+    "show-inheritance": True,
+    "special-members": "__init__",
+    "undoc-members": True,
+}
+
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = ".rst"
+
+# The master toctree document.
+master_doc = "index"
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "sphinx"
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+
+html_context = {
+    "css_files": [
+        "_static/theme_overrides.css",  # override wide tables in RTD theme
+        "_static/schema-page.css",  # Add css from jschemer
+    ]
+}
+
+html_sidebars = {"**": ["globaltoc.html", "relations.html", "sourcelink.html", "searchbox.html"]}

docs/source/contributing/index.rst

@@ -0,0 +1,7 @@
+############
+Contributing
+############
+
+.. mdinclude:: ../../../README.md
+   :start-line: 144
+   :end-line: 197

docs/source/examples/index.rst

@@ -0,0 +1,7 @@
+########
+Examples
+########
+
+.. mdinclude:: ../../../README.md
+   :start-line: 50
+   :end-line: 102