55 repair generated documentation (#56)

.github/workflows/release.yml

@@ -1,10 +1,8 @@
 name: release
 
 on:
-  push:
-    branches:
-      - "main"
-      - "master"
+  workflow_dispatch:
+
 
 jobs:
   pypi_version:

.github/workflows/test.yml

@@ -14,7 +14,7 @@ env:
   FORCE_COLOR: "1"
 
 jobs:
-  run:
+  tests:
     name: Python ${{ matrix.python-version }} on ${{ startsWith(matrix.os, 'macos-') && 'macOS' || startsWith(matrix.os, 'windows-') && 'Windows' || 'Linux' }}
     runs-on: ${{ matrix.os }}
     strategy:
@@ -44,4 +44,57 @@ jobs:
       run: hatch fmt --check
 
     - name: Run tests
-      run: hatch run test.py${{ matrix.python-version }}:cov
+      run: hatch run test.py${{ matrix.python-version }}:test-cov
+
+    - name: Upload coverage data
+      uses: actions/upload-artifact@v3
+      with:
+        name: covdata
+        path: .coverage.*
+        include-hidden-files: true
+
+  coverage:
+    name: Coverage
+    needs:
+      tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.12
+
+      - name: Install dependencies
+        run:
+          python -m pip install --upgrade pip coverage[toml]
+
+      - name: Download coverage data
+        uses: actions/download-artifact@v3
+        with:
+          name: covdata
+
+      - name: Combine
+        run: |
+          python -m compileall examples src tests
+          coverage combine
+          coverage report -i
+          coverage json -i
+          export TOTAL=$(cat coverage.json | jq -r .totals.percent_covered_display)
+          echo "total=${TOTAL}" >> $GITHUB_ENV
+          echo "### Total coverage: ${TOTAL} %" >> $GITHUB_STEP_SUMMARY
+
+      - name: Make badge
+        uses: schneegans/dynamic-badges-action@v1.7.0
+        with:
+          auth: ${{ secrets.GIST_SECRET }}
+          gistID: 12a0c0616d67fc2b8b9cda9eda30be5d
+          filename: sliplib_coverage.svg
+          label: Coverage
+          message: ${{ env.total }} %
+          minColorRange: 50
+          maxColorRange: 90
+          valColorRange: ${{ env.total }}
+

.gitignore

@@ -2,6 +2,7 @@
 *.pyc
 .cache
 .coverage
+.coverage.*
 .externalToolBuilders
 .idea
 .mypy_cache
@@ -20,3 +21,4 @@ Lib
 pyvenv.cfg
 Scripts
 venv
+/coverage.json

CHANGELOG.md

@@ -1,21 +1,27 @@
-# Changelog
+Changelog
+=========
 
 ## Unpublished
 
 ### Upgrade steps
 
+- Implementations that use the `Driver` class directly must update their code
+  with respect to handling received data and retrieving messages.
+  Use `Driver.receive()` to receive data and add it to the internal buffer.
+  Use `Driver.get()` to obtain the next message.
+
 ### Breaking Changes
 
 - Removed support for Python version 3.6 and lower.
+- `Driver.receive()` no longer returns a list of messages.
+  Instead, use `Driver.get()` to retrieve the next message.
 
 ### New Features
 
 ### Bug Fixes
 
 ### Improvements
 
-- Added `block` and `timeout` arguments to the `Driver.get()` method.
-
 ### Other Changes
 
 - Converted project to use `hatch`.
@@ -37,6 +43,7 @@
 
 - Updated documentation and examples
 
+
 ## v0.5.0
 
 ### New Features

README.rst → README.md

@@ -1,106 +1,90 @@
-
-.. image:: https://readthedocs.org/projects/sliplib/badge/?version=latest
-   :target: http://sliplib.readthedocs.org/en/master/?badge=master
-   :alt: ReadTheDocs Documentation Status
-
-.. image:: https://travis-ci.org/rhjdjong/SlipLib.svg
-   :target: https://travis-ci.org/rhjdjong/SlipLib
-   :alt: Travis Test Status
-
-.. image:: https://ci.appveyor.com/api/projects/status/d1nwwn34xoaxh3tt/branch/master?svg=true
-   :target: https://ci.appveyor.com/project/RuuddeJong/sliplib/branch/master
-   :alt: AppVeyor Test Status
-
-
-==============================================
-``sliplib`` --- A module for the SLIP protocol
-==============================================
-
-
-The `sliplib` module implements the encoding and decoding
-functionality for SLIP packets, as described in :rfc:`1055`.
-It defines encoding, decoding, and validation functions,
-as well as a  driver class that can be used to implement
-a SLIP protocol stack, and higher-level classes that
-apply the SLIP protocol to TCP connections or IO streams.
-Read the `documentation <http://sliplib.readthedocs.org/en/master/>`_
-for detailed information.
-
-Background
-==========
-
-The SLIP protocol is described in :rfc:`1055` (:title:`A Nonstandard for
-Transmission of IP Datagrams over Serial Lines: SLIP`, J. Romkey,
-June 1988).  The original purpose of the protocol is
-to provide a mechanism to indicate the boundaries of IP packets,
-in particular when the IP packets are sent over a connection that
-does not provide a framing mechanism, such as serial lines or
-dial-up connections.
-
-There is, however, nothing specific to IP in the SLIP protocol.
-SLIP offers a generic framing method that can be used for any
-type of data that must be transmitted over a (continuous) byte stream.
-In fact, the main reason for creating this module
-was the need to communicate with a third-party application that
-used SLIP over TCP (which is a continuous byte stream)
-to frame variable length data structures.
-
-
-Usage
-=====
-
-Installation
-------------
-
-To install the `sliplib` module, use
-
-.. code::
-
-    pip install sliplib
-
-Low-level usage
----------------
-
-The recommended basic usage is to run all encoding and decoding operations
-through an instantiation `driver` of the `Driver` class, in combination
-with the appropriate I/O code.
-The `Driver` class itself works without any I/O, and can therefore be used with
-any networking code, or any bytestream like pipes, serial I/O, etc.
-It can work in synchronous as well as in asynchronous environments.
-
-The `Driver` class offers the methods
-`send` and `receive` to handle
-the conversion between messages and SLIP-encoded packets.
-
-High-level usage
-----------------
-
-The module also provides a `SlipWrapper` abstract baseclass
-that provides the methods `send_msg` and `recv_msg` to send
-and receive single SLIP-encoded messages. This base class
-wraps an instance of the `Driver` class with a user-provided stream.
-
-Two concrete subclasses of `SlipWrapper` are provided:
-
-* `SlipStream` allows the wrapping of a byte IO stream.
-* `SlipSocket` allows the wrapping of a TCP socket.
-
-In addition, the module also provides a `SlipRequestHandler`
-to facilitate the creation of TCP servers that can handle
-SLIP-encoded messages.
-
-
-Error Handling
-==============
-
-Contrary to the reference implementation described in :rfc:`1055`,
-which chooses to essentially ignore protocol errors,
-the functions and classes in the `sliplib` module
-use a `ProtocolError` exception
-to indicate protocol errors, i.e. SLIP packets with invalid byte sequences.
-The `Driver` class raises the `ProtocolError` exception
-as soon as a complete SLIP packet with an invalid byte sequence is received.
-The `SlipWrapper` class and its subclasses catch the `ProtocolError`\s
-raised by the `Driver` class, and re-raise them when
-an attempt is made to read the contents of a SLIP packet that contained
-invalid data.
+[![Stable Version](https://img.shields.io/pypi/v/sliplib?color=blue)](https://pypi.org/project/sliplib/)
+[![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/)
+[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
+![tests](https://github.com/rhjdjong/SlipLib/actions/workflows/test.yml/badge.svg)
+![coverage](https://gist.githubusercontent.com/rhjdjong/12a0c0616d67fc2b8b9cda9eda30be5d/raw/sliplib_coverage.svg)
+
+# `sliplib` &mdash; A module for the SLIP protocol
+
+The `sliplib` module implements the encoding and decoding
+functionality for SLIP packets, as described in
+[RFC 1055][rfc1055].
+It defines encoding, decoding, and validation functions,
+as well as a driver class that can be used to implement
+a SLIP protocol stack, and higher-level classes that
+apply the SLIP protocol to TCP connections or IO streams.
+Read the [documentation](http://sliplib.readthedocs.org/en/master/)
+for detailed information.
+
+## Background
+
+The SLIP protocol is described in [RFC 1055][rfc1055] (*A Nonstandard for
+Transmission of IP Datagrams over Serial Lines: SLIP*, J. Romkey,
+June 1988).  The original purpose of the protocol is
+to provide a mechanism to indicate the boundaries of IP packets,
+in particular when the IP packets are sent over a connection that
+does not provide a framing mechanism, such as serial lines or
+dial-up connections.
+
+There is, however, nothing specific to IP in the SLIP protocol.
+SLIP offers a generic framing method that can be used for any
+type of data that must be transmitted over a (continuous) byte stream.
+In fact, the main reason for creating this module
+was the need to communicate with a third-party application that
+used SLIP over TCP (which is a continuous byte stream)
+to frame variable length data structures.
+
+
+## Usage
+
+### Installation
+
+To install the `sliplib` module, use
+
+```
+pip install sliplib
+```
+
+### Low-level usage
+
+The recommended basic usage is to run all encoding and decoding operations
+through an instantiation `driver` of the `Driver` class, in combination
+with the appropriate I/O code.
+The `Driver` class itself works without any I/O, and can therefore be used with
+any networking code, or any bytestream like pipes, serial I/O, etc.
+It can work in synchronous as well as in asynchronous environments.
+
+The `Driver` class offers the methods
+`send` and `receive` to handle
+the conversion between messages and SLIP-encoded packets.
+
+### High-level usage
+
+The module also provides a `SlipWrapper` abstract baseclass
+that provides the methods `send_msg` and `recv_msg` to send
+and receive single SLIP-encoded messages. This base class
+wraps an instance of the `Driver` class with a user-provided stream.
+
+Two concrete subclasses of `SlipWrapper` are provided:
+
+* `SlipStream` allows the wrapping of a byte IO stream.
+* `SlipSocket` allows the wrapping of a TCP socket.
+
+In addition, the module also provides a `SlipRequestHandler`
+to facilitate the creation of TCP servers that can handle
+SLIP-encoded messages.
+
+
+## Error Handling
+
+Contrary to the reference implementation described in :rfc:`1055`,
+which chooses to essentially ignore protocol errors,
+the functions and classes in the `sliplib` module
+use a `ProtocolError` exception
+to indicate protocol errors, i.e. SLIP packets with invalid byte sequences.
+The `Driver` class raises a `ProtocolError` exception
+when an attempt is made to `get()` a message from such a packet.
+
+[rfc1055]: http://tools.ietf.org/html/rfc1055.html

docs/source/changes.md

@@ -0,0 +1,2 @@
+```{include} ../../CHANGELOG.md
+```

docs/source/conf.py

@@ -40,18 +40,20 @@
     "sphinx_toolbox.more_autodoc.typevars",
     "sphinx_toolbox.more_autodoc.variables",
     "sphinx_autodoc_typehints",
+    "myst_parser",
 ]
 
 templates_path = ["_templates"]
 exclude_patterns = []
 
 napoleon_google_docstring = True
-# napoleon_use_rtype = False
 autoclass_content = "both"
 autodoc_typehints = "description"
 autodoc_type_aliases = {}
 add_module_names = False
-intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

docs/source/index.rst

@@ -7,15 +7,16 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-.. include:: ../../README.rst
-.. include:: ../../CHANGES.rst
+.. include:: ../../README.md
+   :parser: myst_parser.sphinx_
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents
 
    module
    example
+   changes
 
 
 Indices and tables