Extend the application-layer API to avoid hard-coded protocol-related…

… constants in applications (#154)

.appveyor.yml

@@ -74,7 +74,7 @@ for:
       - '[[ -z "$APPVEYOR_PULL_REQUEST_HEAD_COMMIT" ]] || unset SONARCLOUD_TOKEN'
     test_script:
       - 'nox --non-interactive --error-on-missing-interpreters --session test pristine --python $PYTHON'
-      - 'nox --non-interactive --error-on-missing-interpreters --session check_style docs'
+      - 'nox --non-interactive --session demo check_style docs'
 
   - # DEPLOYMENT
     matrix:

.gitignore

@@ -31,6 +31,7 @@ htmlcov/
 nosetests.xml
 coverage.xml
 *,cover
+.*mypy.json
 
 .project
 .pydevproject
@@ -45,6 +46,7 @@ coverage.xml
 .*generated
 .*compiled
 *.cache
+*.db
 
 .scannerwork
 

.test_deps/README.md

@@ -38,6 +38,6 @@ Npcap is needed for testing the network sniffer of the UAVCAN/UDP transport impl
 Npcap is distributed under the terms of Nmap Public Source License: https://nmap.org/npsl/.
 
 
-### SonarQube scanner
+## SonarQube scanner
 
 New versions can be obtained from https://binaries.sonarsource.com/Distribution/sonar-scanner-cli/.

CHANGELOG.rst

@@ -14,6 +14,24 @@ v1.2
 
 - Constructor parameter ``anonymous`` for ``UDPTransport`` has been deprecated in favor of ``local_node_id``.
 
+- Refactor the Node API:
+
+  - Add factory function ``make_node()``.
+
+  - Implement the UAVCAN Register API and add port construction factory methods that take port-ID from the registry.
+    This is a major change that allows applications to avoid hard-coding any port-ID whatsoever.
+    The respective configuration is now sourced from the registers, which in turn are read from environment variables
+    and from persistent register files (i.e., configuration files).
+
+  - Support context manager API (``__enter__``, ``__leave__``).
+
+  - Rework the documentation accordingly.
+
+- Fix minor issues with logging throughout.
+
+- In ``pyuavcan.dsdl``: rename ``generate_package`` into ``compile``, add ``compile_all``.
+
+
 v1.1
 ----
 

CONTRIBUTING.rst

@@ -94,27 +94,26 @@ Example: ``start()`` -- do nothing if already started; ``close()`` -- do nothing
 If you intend to implement some form of RAII with the help of object finalizers ``__del__()``,
 beware that if the object is accidentally resurrected in the process, the finalizer may or may not be invoked
 again later, which breaks the RAII logic.
-A nasty pitfall I encountered is that if the object is referenced in a logging call from the finalizer,
-the logging library may retain the reference until the next GC cycle, causing the finalizer to be invoked again.
+This may happen, for instance, if the object is passed to a logging call.
 
 API functions and methods that contain the following parameters should adhere to the semantic naming conventions:
 
-+-----------------------------------------+-------------------------+-----------------------------------------------------------+
-|Type                                     | Name                    | Purpose                                                   |
-+=========================================+=========================+===========================================================+
-|``pydsdl.*Type``                         | ``model``               | PyDSDL type model (descriptor).                           |
-+-----------------------------------------+-------------------------+-----------------------------------------------------------+
-|``pyuavcan.dsdl.*Object``                | ``obj``                 | Instance of a generated class implementing a DSDL type.   |
-+-----------------------------------------+-------------------------+-----------------------------------------------------------+
-|``typing.Type[pyuavcan.dsdl.*Object]``   | ``dtype``               | Generated class implementing a DSDL type.                 |
-+-----------------------------------------+-------------------------+-----------------------------------------------------------+
-|``float``                                | ``monotonic_deadline``  | Abort operation if not completed **by** this time.        |
-|                                         |                         | Time system is ``AbstractEventLoop.time()``.              |
-+-----------------------------------------+-------------------------+-----------------------------------------------------------+
-|``float``                                | ``timeout``             | Abort operation if not completed **in** this time.        |
-+-----------------------------------------+-------------------------+-----------------------------------------------------------+
-|``int``                                  | ``node_id``             | A node identifier.                                        |
-+-----------------------------------------+-------------------------+-----------------------------------------------------------+
++--------------------------------------+-----------------------+-------------------------------------------------------+
+|Type                                  |Name                   |Purpose                                                |
++======================================+=======================+=======================================================+
+|``pydsdl.*Type``                      |``model``              |PyDSDL type model (descriptor).                        |
++--------------------------------------+-----------------------+-------------------------------------------------------+
+|``pyuavcan.dsdl.*Object``             |``obj``                |Instance of a generated class implementing DSDL type.  |
++--------------------------------------+-----------------------+-------------------------------------------------------+
+|``typing.Type[pyuavcan.dsdl.*Object]``|``dtype``              |Generated class implementing a DSDL type.              |
++--------------------------------------+-----------------------+-------------------------------------------------------+
+|``float``                             |``monotonic_deadline`` |Abort operation if not completed **by** this time.     |
+|                                      |                       |Time system is ``AbstractEventLoop.time()``.           |
++--------------------------------------+-----------------------+-------------------------------------------------------+
+|``float``                             |``timeout``            |Abort operation if not completed **in** this time.     |
++--------------------------------------+-----------------------+-------------------------------------------------------+
+|``int``                               |``node_id``            |A node identifier.                                     |
++--------------------------------------+-----------------------+-------------------------------------------------------+
 
 
 Documentation
@@ -173,8 +172,7 @@ Ensure that your tests do not emit any errors or warnings into stderr output upo
 because that may distract the developer from noticing true abnormalities
 (you may use ``caplog.at_level('CRITICAL')`` to suppress undesirable output).
 
-Write unit tests as functions without arguments prefixed with ``_unittest_``;
-optionally, for slow test functions use the prefix ``_unittest_slow_``.
+Write unit tests as functions without arguments prefixed with ``_unittest_``.
 Generally, simple test functions should be located as close as possible to the tested code,
 preferably at the end of the same Python module; exception applies to several directories listed in ``setup.cfg``,
 which are unconditionally excluded from unit test discovery because they rely on DSDL autogenerated code
@@ -251,7 +249,7 @@ with suppression comments.
 
 Configure a File Watcher to run Black on save (make sure to disable running it on external file changes though).
 
-The test suite stores compiled DSDL into `.compiled/` in the current working directory
+The test suite stores compiled DSDL into ``.compiled/`` in the current working directory
 (when using Nox, the current working directory may be under a virtualenv private directory).
 Make sure to mark it as a source directory to enable code completion and type analysis in the IDE
 (for PyCharm: right click -> Mark Directory As -> Sources Root).

README.md

@@ -22,11 +22,14 @@ It is designed to support **GNU/Linux**, **MS Windows**, and **macOS** as first-
 However, the library does not rely on any platform-specific capabilities,
 so it should be usable with other systems as well.
 
-[UAVCAN](https://uavcan.org) is an open lightweight data bus standard designed for reliable intravehicular
-communication in aerospace and robotic applications via
-CAN bus, Ethernet, RS-485, IEEE 802.15.4, and other robust transports.
+[UAVCAN](https://uavcan.org) is an open technology for real-time intravehicular distributed computing
+and communication based on modern networking standards (Ethernet, CAN FD, etc.).
 The acronym *UAVCAN* stands for ***Uncomplicated Application-level Vehicular Computing And Networking***.
 
+<p align="center">
+  <a href="https://pyuavcan.readthedocs.io/"><img src="/docs/static/arch-non-redundant.svg" width="400px"></a>
+</p>
+
 **READ THE DOCS: [pyuavcan.readthedocs.io](https://pyuavcan.readthedocs.io/)**
 
 **Ask questions: [forum.uavcan.org](https://forum.uavcan.org/)**

demo/custom_data_types/sirius_cyber_corp/PerformLinearLeastSquaresFit.1.0.uavcan

@@ -1,12 +1,8 @@
-#
-# This service accepts a dynamic array of 2D coordinates and returns the best-fit linear function coefficients.
-#
-# This service doesn't have a fixed subject-ID.
-#
+# This service accepts a list of 2D point coordinates and returns the best-fit linear function coefficients.
+# If no solution exists, the returned coefficients are NaN.
 
 PointXY.1.0[<64] points
 
-@assert _offset_ % 8 == {0}
 @extent 1024 * 8
 
 ---

demo/custom_data_types/sirius_cyber_corp/PointXY.1.0.uavcan

@@ -1,8 +1,3 @@
-#
-# This nested type contains 2D point coordinates.
-#
-
 float16 x
 float16 y
-
 @sealed