Prepare to Release v0.1.0

.github/workflows/pydocstyle.yml

@@ -21,7 +21,7 @@ jobs:
         python -m pip install --upgrade pip
         if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
         pip install pydocstyle
-        pip install .
+        pip install .[full]
         python3 -c "import selprotopy; print('selprotopy.__file__')"
     - name: Test NumpyDoc Style
       run: |

.github/workflows/pylint.yml

@@ -21,7 +21,7 @@ jobs:
         python -m pip install --upgrade pip
         if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
         pip install pylint
-        pip install .
+        pip install .[full]
         python3 -c "import selprotopy; print('selprotopy.__file__')"
     - name: Test NumpyDoc Style
       run: |

.github/workflows/sphinx-build.yml

@@ -22,13 +22,13 @@ jobs:
       - name: Install dependencies
         run: |
           #pip install -r requirements.txt
-          pip install -r source/sphinxrequires.txt
+          pip install -r docsource/sphinxrequires.txt
       - name: Build Sphinx docs
         if: success()
         run: |
-          pip install .
+          pip install .[full]
           python3 -c "import selprotopy; print('selprotopy.__file__')"
-          sphinx-build -M html source docs
+          sphinx-build -M html docsource docs
 
       # https://github.com/marketplace/actions/github-pages
       #- if: success()

source/conf.py → docsource/conf.py

@@ -39,7 +39,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'selprotopy'
-copyright = '2020, Joe Stanley'
+copyright = '2023, Joe Stanley'
 author = 'Joe Stanley'
 
 
@@ -48,17 +48,18 @@
 # 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',
-                'sphinx.ext.autosummary',
-                'numpydoc',
-                'sphinx_sitemap',
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.autosummary',
+    'numpydoc',
+    #'sphinx_sitemap',
+    'myst_parser',
+    'sphinx_immaterial',
 ]
 autosummary_generate = True
 numpydoc_show_class_members = True
 
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -71,39 +72,50 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'classic'
+html_theme = 'sphinx_immaterial'
 html_title = 'selprotopy'
 html_logo  = '../logo/selprotopy.png'
 html_favicon = '../logo/relay.png'
 html_theme_options = {
-    'rightsidebar':     'false',
-    'stickysidebar':    'false',
-    'collapsiblesidebar': 'false',
-    'externalrefs':     'false',
-    'footerbgcolor':    '#08385D',
-    'footertextcolor':  '#ffffff',
-    'sidebarbgcolor':   '#08385D',
-    # 'sidebartextcolor': ,
-    'relbarbgcolor':    '#08385D',
-    'relbartextcolor':  '#ffffff',
-    # 'relbarlinkcolor':  '#3432D8',
-    'bgcolor':          '#ffffff',
-    # 'textcolor':        ,
-    'linkcolor':        '#3432D8',
-    # 'visitedlinkcolor': ,
-    'headbgcolor':      '#C1C1C1',
-    'headtextcolor':    '#08385D',
-    'headlinkcolor':    '#3432D8',
-    # 'codebgcolor':      ,
-    # 'codetextcolor':    ,
-    # 'bodyfont':         ,
-    # 'headfont':         ,
+
+    # Specify a base_url used to generate sitemap.xml. If not
+    # specified, then no sitemap will be built.
+    'site_url': 'https://selprotopy.readthedocs.io/en/latest/',
+
+    # Set the color and the accent color
+    "palette": [
+        {
+            "primary": "light-blue",
+            "accent": "blue",
+            "media": "(prefers-color-scheme: light)",
+            "scheme": "default",
+            "toggle": {
+                "icon": "material/toggle-switch-off-outline",
+                "name": "Switch to dark mode",
+            }
+        },
+        {
+            "primary": "blue",
+            "accent": "light-blue",
+            "media": "(prefers-color-scheme: dark)",
+            "scheme": "slate",
+            "toggle": {
+                "icon": "material/toggle-switch",
+                "name": "Switch to light mode",
+            }
+        },
+    ],
+
+    # Set the repo location to get a badge with stats
+    'repo_url': 'https://github.com/engineerjoe440/selprotopy/',
+    'repo_name': 'selprotopy',
+
+    "icon": {
+        "repo": "fontawesome/brands/github",
+        "logo": "material/library",
+    },
 }
 
-# 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']
 
 
 

source/exceptions.rst → docsource/exceptions.rst

@@ -31,7 +31,7 @@ Parse Errors
 Protocol Exceptions
 ===================
 
-.. autoexception:: selprotopy.exceptions.InvalidConmmandType
+.. autoexception:: selprotopy.exceptions.InvalidCommandType
 
 .. autoexception:: selprotopy.exceptions.InvalidControlType
 

docsource/index.md

@@ -0,0 +1,94 @@
+---
+:hero: <b><i>Python Bindings for the SEL Protocol Suite</i></b>
+---
+
+# SELPROTOPY: Python Bindings for the SEL Protocol Suite
+
+`selprotopy` is intended to be used as a protocol binding suite for the SEL
+Protocol suite which includes SEL Fast Meter, SEL Fast Message, and SEL Fast
+Operate; each of which are proprietary protocols designed by
+[Schweitzer Engineering Laboratories](https://selinc.com/) for use primarily
+with protective electric relays, and other intelligent electronic devices.
+
+```{note}
+This project, although binding SEL Protocol, is not sponsored, tested, or
+vetted in any way by Schweitzer Engineering Laboratories (SEL). This project
+is authored and maintained as an open-source project. Testing is performed
+on a very small set of hardware running in the author's basement. In short,
+this project has no association with SEL.
+```
+
+## Protocol Documentation
+
+SEL Protocol was introduced in the early 1990s to support various communications
+and control of SEL protective relays. SEL provided a very supportive
+[application guide](https://selinc.com/api/download/5026/) which provides great
+detail about the protocol's implementation.
+
+```{toctree}
+---
+maxdepth: 1
+---
+
+selprotopy
+```
+
+```{warning}
+*Since this project is not rigorously tested across all SEL devices or in a
+wide variety of use-cases, any time this project is used, it should first be
+thoroughly tested. This project is not intended to serve protection-class
+systems in any capacity. It should primarily be used for research,
+exploration, and other learning objectives.*
+```
+
+### Installation
+
+#### Typical Installation (From PyPI)
+
+```shell
+pip install selprotopy[full]
+```
+
+#### From Source (Development)
+
+To install `selprotopy` from GitHub:
+
+1. Download the repository as a zipped package.
+2. Unzip the repository.
+3. Open a terminal (command-prompt) and navigate to the new folder that's been unzipped.
+
+    ```{hint}
+    Use `cd <the-path-to-the-folder-you-unzipped-in>/selprotopy`
+    ```
+
+4. Use `pip` or `python` to install with the following commands, respectively:
+
+    ```shell
+    pip install -e .
+    ```
+
+5. Verify that it's been installed by opening a Python instance and importing:
+
+    ```python
+    >>> import selprotopy
+    ```
+
+    If no errors arise, the package has been installed.
+
+## Project Information
+
+For additional information related to this project, please refer to the links
+and materials linked below.
+
+### Contact Info
+
+As mentioned in the
+[caution](https://engineerjoe440.github.io/selprotopy/#selprotopy-python-bindings-for-the-sel-protocol-suite)
+above, this project is not associated with Schweitzer Engineering Laboratories
+(SEL) in any way, and as such, all contacts for questions, support, or other
+items should be directed to the resources listed here.
+
+For issues found in the source code itself, please feel free to open an
+[issue](https://github.com/engineerjoe440/selprotopy/issues), but for general
+inquiries and other contact, feel free to address
+[Joe Stanley](mailto:[email protected]).

docsource/selprotopy.md

@@ -0,0 +1,16 @@
+# API Reference
+
+```{eval-rst}
+.. autoclass:: selprotopy.client.base.SELClient
+   :members:
+```
+
+
+# Sub-Modules and Other Package API References
+
+```{eval-rst}
+.. toctree::
+   :maxdepth: 1
+
+   exceptions
+```

docsource/sphinxrequires.txt

@@ -0,0 +1,8 @@
+wheel
+sphinx
+pyserial
+numpydoc
+myst-parser
+sphinx-sitemap
+sphinx-immaterial
+coverage-badge

pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["flit_core >=3.2,<4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "selprotopy"
+description = "Schweitzer Engineering Laboratories (SEL) Protocol Bindings in Python"
+authors = [{name = "Joe Stanley", email = "[email protected]"}]
+readme = "README.md"
+license = {file = "LICENSE"}
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dynamic = ["version"]
+
+[project.urls]
+Home = "https://selprotopy.readthedocs.io/en/latest/"
+Repository = "https://github.com/engineerjoe440/selprotopy/"
+PyPI = "https://pypi.org/project/selprotopy/"
+Issues = "https://github.com/engineerjoe440/selprotopy/issues"
+
+[project.optional-dependencies]
+serial = [
+    "pyserial",
+]
+full = [
+    "pyserial",
+]

selprotopy/__init__.py

@@ -1,30 +1,29 @@
+################################################################################
 """
 selprotopy: A Protocol Binding Suite for the SEL Protocol Suite.
 
 Supports:
-  - SEL Fast Meter
-  - SEL Fast Message
-  - SEL Fast Operate
+    - SEL Fast Meter
+    - SEL Fast Message
+    - SEL Fast Operate
 
 Author(s):
-  - Joe Stanley: joe_stanley@selinc.com
+    - Joe Stanley: engineerjoe440@yahoo.com
 
 Homepage: https://github.com/engineerjoe440/sel-proto-py
 
 SEL Protocol Application Guide: https://selinc.com/api/download/5026/
 """
+################################################################################
 
 # Standard Imports
 import telnetlib
 
 # Local Imports
-from selprotopy import telnetlib_support
-from selprotopy.client import SelClient # Alias class for easy access
+from selprotopy.support import telnet
 
 # Describe Package for External Interpretation
-_name_ = "selprotopy"
-_version_ = "0.1"
-__version__ = _version_  # Alias the Version String
+__version__ = "0.1.0"
 
 # `telnetlib` Discards Null Characters, but SEL Protocol Requires them
-telnetlib.Telnet.process_rawq = telnetlib_support.process_rawq
+telnetlib.Telnet.process_rawq = telnet.process_rawq

selprotopy/client/__init__.py

@@ -0,0 +1,27 @@
+################################################################################
+"""
+selprotopy: A Protocol Binding Suite for the SEL Protocol Suite.
+
+Supports:
+    - SEL Fast Meter
+    - SEL Fast Message
+    - SEL Fast Operate
+
+Author(s):
+    - Joe Stanley: [email protected]
+
+Homepage: https://github.com/engineerjoe440/sel-proto-py
+
+SEL Protocol Application Guide: https://selinc.com/api/download/5026/
+"""
+################################################################################
+
+try:
+    from selprotopy.client.serial import *
+except ImportError:
+    pass
+
+try:
+    from selprotopy.client.ethernet import *
+except ImportError:
+    pass