Merge branch 'main' into dependabot/pip/aenum-gte-3.0.0-and-lt-3.1.16

.github/pull_request_template.md

@@ -1,11 +1,11 @@
-## Description
+# Description
 <!--- Describe your changes -->
 
 
-## How Has This Been Tested?
+# How Has This Been Tested?
 <!--- Please shortly describe how you tested your code. -->
 
 
-## Process
+# Process
 <!--- If you are familiar with the process, leave the line below. If not, please describe what you did, so we could help you deliver your changed according to our quality policies -->
 I know the [process](https://github.com/mdabrowski1990/uds/wiki/Software-Development-Life-Cycle) and did my best to follow it

.github/workflows/ci.yml → .github/workflows/testing.yml

@@ -1,4 +1,4 @@
-name: CI
+name: Testing
 
 
 on: [push, pull_request]
@@ -28,7 +28,7 @@ jobs:
 
       - name: Install external packages used for dynamic tests
         run: |
-          pip install -r tests/requirements_for_software_tests.txt
+          pip install .[test]
 
       - name: Execute unit tests with coverage report [pytest]
         run: |
@@ -50,10 +50,10 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Set up Python 3.11
+      - name: Set up Python 3.12
         uses: actions/setup-python@v4
         with:
-          python-version: 3.11
+          python-version: 3.12
 
       - name: Install project dependencies
         run: |
@@ -63,20 +63,16 @@ jobs:
 
       - name: Install external packages used for dynamic tests
         run: |
-          pip install -r tests/requirements_for_software_tests.txt
-
-      - name: Prepare coverage uploader [CodeCov]
-        run: |
-          curl -Os https://app.codecov.io/gh/mdabrowski1990/uds/uploader/linux/codecov
-          chmod +x codecov
+          pip install .[test]
 
       - name: Execute unit tests [pytest]
         run: |
           pytest tests/software_tests --cov-report=xml --cov=uds -m "not integration and not performance"
 
       - name: Upload unit tests report [CodeCov]
-        uses: codecov/codecov-action@v3
+        uses: codecov/codecov-action@v4
         with:
+          fail_ci_if_error: true
           token: ${{ secrets.CODECOV_TOKEN }}
           files: coverage.xml
           flags: unit-tests
@@ -86,23 +82,14 @@ jobs:
           pytest tests/software_tests --cov-report=xml --cov=uds -m "integration"
 
       - name: Upload integration tests report [CodeCov]
-        uses: codecov/codecov-action@v3
+        uses: codecov/codecov-action@v4
         with:
+          fail_ci_if_error: true
           token: ${{ secrets.CODECOV_TOKEN }}
           files: coverage.xml
           flags: integration-tests
 
-# TODO: uncomment when performance tests are added
-#      - name: Execute performance tests [pytest]
-#        run: |
-#          pytest tests/software_tests --cov-report=xml --cov=uds -m "performance"
-#
-#      - name: Upload performance tests report [CodeCov]
-#        uses: codecov/codecov-action@v3
-#        with:
-#          token: ${{ secrets.CODECOV_TOKEN }}
-#          files: coverage.xml
-#          flags: performance-tests
+# TODO: add performance tests upload when added
 
 
   static_code_analysis:
@@ -127,7 +114,7 @@ jobs:
 
       - name: Install external packages used for static tests
         run: |
-          pip install -r tests/requirements_for_static_code_analysis.txt
+          pip install .[static-code-analysis]
 
       - name: Execute static code analysis [prospector]
         run: |
@@ -150,8 +137,63 @@ jobs:
 
       - name: Install external packages used for dependency scanning
         run: |
-          pip install -r tests/requirements_for_dependency_scanning.txt
+          python -m pip install --upgrade pip
+          pip install .[dependency-scan]
 
       - name: Execute dependency scanning [safety]
         run: |
           safety check -r requirements.txt
+
+      - name: Execute dependency scanning [pip-audit]
+        run: |
+          pip-audit
+
+  sorting_imports:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.12
+
+      - name: Install project dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install --upgrade setuptools
+          pip install -r requirements.txt
+
+      - name: Install external packages used for sorting imports
+        run: |
+          pip install .[sorting-imports]
+
+      - name: Check imports are sorted [isort]
+        run: |
+          isort uds
+          isort tests
+          isort examples
+
+  documentation_checks:
+    runs-on: windows-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.12
+
+      - name: Install project dependencies
+        run: |
+          pip install -r requirements.txt
+
+      - name: Install external packages used for documentation checking
+        run: |
+          pip install .[docs-checks]
+
+      - name: Check RST documentation [doc8]
+        run: |
+          doc8 docs\source

README.rst

@@ -1,6 +1,6 @@
-*****
+***
 UDS
-*****
+***
 
 |CI| |SecurityScan| |BestPractices| |ReadTheDocs| |CodeCoverage|
 
@@ -19,6 +19,64 @@ Security policy for this package is defined in `SECURITY.md`_ file.
 If you want to become a contributor, please read `CONTRIBUTING.md`_ file.
 
 
+Why another UDS package?
+------------------------
+There are a few already existing python packages to handle UDS protocol,
+so you might wonder why would you consider using this one?
+
+This package is meant to support **multiple buses** (including CAN, LIN, Ethernet, K-Line, FlexRay) and **multiple
+bus managers** (e.g. `python-can`_).
+Additionally, it handles both communication nodes (client and server), and contains detailed configuration to fully
+control all timing and transmission parameters.
+
+Thanks to all these features, this package can have multiple use-cases, including:
+
+- simple send-receive messages to/from any network
+- comprehensive node simulations
+- testing of UDS protocol communication implementation
+
+Unfortunately, all previously mentioned plans make the project a huge effort and at the time of writing,
+the implementation process of these features is still ongoing (and probably the status will stay the same for at least
+a couple more years).
+On the other hand, the architecture to support all these features is already designed and some of the features
+are already implemented with others defined or planned.
+
+To check the current implementation status, visit:
+
+- https://uds.readthedocs.io/en/stable/#features
+- https://uds.readthedocs.io/en/stable/pages/knowledge_base/osi_model.html#uds-functionalities
+
+
+Alternative options
+```````````````````
+
+python-udsoncan
+'''''''''''''''
+Link: https://github.com/pylessard/python-udsoncan
+
+- pros:
+    - comprehensive documentation
+    - handlers for multiple diagnostic services is implemented
+- cons:
+    - only positive use case scenarios (where communication is in line with UDS standard) are supported
+    - only CAN bus is supported
+    - only Client side communication can be handled
+    - limited communication parameters configuration
+
+
+python-uds
+''''''''''
+Link: https://github.com/richClubb/python-uds
+
+- pros:
+    - CAN and LIN buses are supported
+- cons:
+    - modest documentation
+    - only a few communication interfaces are supported
+    - only Client side communication can be handled
+    - limited communication parameters configuration
+
+
 Contact
 -------
 - e-mail: uds-package-development@googlegroups.com
@@ -34,8 +92,10 @@ Contact
 
 .. _Unified Diagnostic Services: https://en.wikipedia.org/wiki/Unified_Diagnostic_Services
 
-.. |CI| image:: https://github.com/mdabrowski1990/uds/actions/workflows/ci.yml/badge.svg?branch=main
-   :target: https://github.com/mdabrowski1990/uds/actions/workflows/ci.yml
+.. _python-can: https://github.com/hardbyte/python-can
+
+.. |CI| image:: https://github.com/mdabrowski1990/uds/actions/workflows/testing.yml/badge.svg?branch=main
+   :target: https://github.com/mdabrowski1990/uds/actions/workflows/testing.yml
    :alt: Continuous Integration Status
 
 .. |SecurityScan| image:: https://github.com/mdabrowski1990/uds/actions/workflows/codeql-analysis.yml/badge.svg?branch=main

docs/source/conf.py

@@ -14,10 +14,11 @@
 # import sys
 # sys.path.insert(0, os.path.abspath("."))
 
-import os
-import sys
 import datetime
+import os
 import re
+import sys
+
 try:  # python 3.11 or newer
     import tomlib
 except ModuleNotFoundError:

docs/source/pages/knowledge_base/diagnostic_message.rst

@@ -231,8 +231,9 @@ in one or multiple servers' memory.
 ReadDTCInformation
 ``````````````````
 ReadDTCInformation service allows the client to read from any server or group of servers within a vehicle,
-current information about all Diagnostic Trouble Codes. This could be a status of reported Diagnostic Trouble Code (DTC),
-number of currently active DTCs or any other information returned by supported ReadDTCInformation SubFunctions.
+current information about all Diagnostic Trouble Codes.
+This could be a status of reported Diagnostic Trouble Code (DTC), number of currently active DTCs or any other
+information returned by supported ReadDTCInformation SubFunctions.
 
 
 ReadDataByIdentifier

docs/source/pages/knowledge_base/packet.rst

@@ -196,8 +196,8 @@ where:
 Extended Addressing
 '''''''''''''''''''
 If extended addressing format is used, then the value of **the first CAN frame byte informs about a target** of
-a UDS packet and remaining `Network Address Information`_ (a sending entity and :ref:`an addressing type <knowledge-base-addressing>`)
-are determined by CAN Identifier value.
+a UDS packet and remaining `Network Address Information`_ (a sending entity and
+:ref:`an addressing type <knowledge-base-addressing>`) are determined by CAN Identifier value.
 
 Following parameters specifies `Network Address Information`_ when Extended Addressing is used:
  - CAN ID
@@ -402,7 +402,8 @@ Number of payload bytes carried by SF is specified by
 Single Frame Data Length
 ........................
 Single Frame Data Length (SF_DL) is 4-bit (for CAN packets with DLC<=8) or 8-bit (for CAN packets with DLC>8) value
-carried by every Single Frame as presented in :ref:`the table with CAN packet formats<knowledge-base-can-packets-format>`.
+carried by every Single Frame as presented in
+:ref:`the table with CAN packet formats<knowledge-base-can-packets-format>`.
 SF_DL specifies number of diagnostic message payload bytes transmitted in a Single Frame.
 
 .. note:: Maximal value of SF_DL depends on Single Frame :ref:`addressing format <knowledge-base-can-addressing>`
@@ -534,8 +535,9 @@ Block Size (BS) is a one byte value specified by receiving entity that informs a
 Block Size values:
  - 0x00
 
-    The value 0 of the Block Size parameter informs a sender that no more :ref:`Flow Control <knowledge-base-can-flow-control>`
-    frames shall be sent during the transmission of the segmented message.
+    The value 0 of the Block Size parameter informs a sender that no more
+    :ref:`Flow Control <knowledge-base-can-flow-control>` frames shall be sent during the transmission
+    of the segmented message.
 
     Reception of Block Size = 0 shall cause the sender to send all remaining
     :ref:`Consecutive Frames <knowledge-base-can-consecutive-frame>` without any stop for further

docs/source/pages/knowledge_base/performance.rst

@@ -42,8 +42,8 @@ Timeout value:
   1000 ms
 
 Error handling:
-  If N_As timeout is exceeded, then the transmission of the :ref:`diagnostic message <knowledge-base-diagnostic-message>`
-  shall be aborted.
+  If N_As timeout is exceeded, then the transmission of
+  the :ref:`diagnostic message <knowledge-base-diagnostic-message>` shall be aborted.
 
 Affected :ref:`CAN Packets <knowledge-base-uds-can-packet>`:
   - :ref:`Single Frame <knowledge-base-can-single-frame>`
@@ -75,10 +75,10 @@ Affected :ref:`CAN Packets <knowledge-base-uds-can-packet>`:
 N_Bs
 ````
 N_Bs is a time parameter related to :ref:`Flow Control (CAN Packet) <knowledge-base-can-flow-control>` reception
-by a sender.
-It is measured from the end of the last CAN Packet transmission (either transmitted :ref:`First Frame <knowledge-base-can-first-frame>`,
-:ref:`Consecutive Frame <knowledge-base-can-consecutive-frame>` or received :ref:`Flow Control <knowledge-base-can-flow-control>`),
-till the reception of :ref:`Flow Control <knowledge-base-can-flow-control>`.
+by a sender. It is measured from the end of the last CAN Packet transmission (either transmitted
+:ref:`First Frame <knowledge-base-can-first-frame>`, :ref:`Consecutive Frame <knowledge-base-can-consecutive-frame>`
+or received :ref:`Flow Control <knowledge-base-can-flow-control>`), till the reception of
+:ref:`Flow Control <knowledge-base-can-flow-control>`.
 
 Timeout value:
   1000 ms
@@ -96,10 +96,10 @@ Affected :ref:`CAN Packets <knowledge-base-uds-can-packet>`:
 N_Br
 ````
 N_Br is a time parameter related to :ref:`Flow Control (CAN Packet) <knowledge-base-can-flow-control>` transmission
-by a receiver.
-It is measured from the end of the last CAN Packet transmission (either received :ref:`First Frame <knowledge-base-can-first-frame>`,
-:ref:`Consecutive Frame <knowledge-base-can-consecutive-frame>` or transmitted :ref:`Flow Control <knowledge-base-can-flow-control>`),
-till the start of :ref:`Flow Control <knowledge-base-can-flow-control>` transmission.
+by a receiver. It is measured from the end of the last CAN Packet transmission (either received
+:ref:`First Frame <knowledge-base-can-first-frame>`, :ref:`Consecutive Frame <knowledge-base-can-consecutive-frame>`
+or transmitted :ref:`Flow Control <knowledge-base-can-flow-control>`), till the start of
+:ref:`Flow Control <knowledge-base-can-flow-control>` transmission.
 
 Performance requirement:
   A receiving entity is obliged to transmit :ref:`Flow Control <knowledge-base-can-flow-control>` packet before value
@@ -119,9 +119,9 @@ Affected :ref:`CAN Packets <knowledge-base-uds-can-packet>`:
 N_Cs
 ````
 N_Cs is a time parameter related to :ref:`Consecutive Frame (CAN Packet) <knowledge-base-can-consecutive-frame>`
-transmission by a sender.
-It is measured from the end of the last CAN Packet transmission (either received :ref:`Flow Control <knowledge-base-can-flow-control>`
-or transmitted :ref:`Consecutive Frame <knowledge-base-can-consecutive-frame>`), till the start of
+transmission by a sender. It is measured from the end of the last CAN Packet transmission (either received
+:ref:`Flow Control <knowledge-base-can-flow-control>` or transmitted
+:ref:`Consecutive Frame <knowledge-base-can-consecutive-frame>`), till the start of
 :ref:`Consecutive Frame <knowledge-base-can-consecutive-frame>` transmission.
 
 Performance requirement:
@@ -142,9 +142,9 @@ Affected :ref:`CAN Packets <knowledge-base-uds-can-packet>`:
 N_Cr
 ````
 N_Cr is a time parameter related to :ref:`Consecutive Frame (CAN Packet) <knowledge-base-can-consecutive-frame>`
-reception by a receiver.
-It is measured from the end of the last CAN Packet transmission (either transmitted :ref:`Flow Control <knowledge-base-can-flow-control>`
-or received :ref:`Consecutive Frame <knowledge-base-can-consecutive-frame>`), till the reception of
+reception by a receiver. It is measured from the end of the last CAN Packet transmission (either transmitted
+:ref:`Flow Control <knowledge-base-can-flow-control>` or received
+:ref:`Consecutive Frame <knowledge-base-can-consecutive-frame>`), till the reception of
 :ref:`Consecutive Frame <knowledge-base-can-consecutive-frame>`.
 
 Timeout value:

docs/source/pages/user_guide/client_simulation.rst

@@ -5,4 +5,4 @@ ECUs) in UDS communication. Client simulation enables sending diagnostic request
 from connected nodes.
 
 `THIS FEATURE <https://github.com/mdabrowski1990/uds/milestone/8>`_ IS PLANNED BUT NOT IMPLEMENTED YET,
-THEREFORE THERE ARE NO MORE INFORMATION TO DISPLAY.
+THEREFORE THERE ARE NO MORE INFORMATION TO DISPLAY.

docs/source/pages/user_guide/segmentation.rst

@@ -87,7 +87,8 @@ Following functionalities are provided by :class:`~uds.segmentation.can_segmente
 - CAN packets desegmentation:
 
   As a user, you are able to :ref:`desegment CAN packets <knowledge-base-packets-desegmentation>`
-  (either objects of :class:`~uds.packet.can_packet.CanPacket` or :class:`~uds.packet.can_packet_record.CanPacketRecord` class)
+  (either objects of :class:`~uds.packet.can_packet.CanPacket` or
+  :class:`~uds.packet.can_packet_record.CanPacketRecord` class)
   into diagnostic messages (either objects of :class:`~uds.message.uds_message.UdsMessage` or
   :class:`~uds.message.uds_message.UdsMessageRecord` class).