puslib 0.3.0__tar.gz → 0.4.0__tar.gz

{puslib-0.3.0/src/puslib.egg-info → puslib-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: puslib
-Version: 0.3.0
+Version: 0.4.0
 Summary: An implementation of the telemetry and telecommand packet utilization standard (PUS).
 Home-page: https://github.com/pxntus/puslib
 Author: Pontus Nyman
@@ -26,24 +26,23 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: bitstring
 Dynamic: license-file
-Dynamic: requires-dist
 
 # Puslib
 
-**Puslib** is a Python implementation of the telemetry and telecommand packet utilization standard (PUS). It is a standard widely used in the space industry for the purposes of remote monitoring and control of spacecraft subsystems and payloads.
+**Puslib** is a Python library for working with the ECSS Packet Utilization Standard (PUS), a protocol widely used in the space industry.
 
-This package is mainly intended for ground segment tools, e.g.:
+PUS defines an application-level interface between ground and space, covering both segments. It specifies a binary packet format for telecommands and telemetry (based on CCSDS space packets) and a routing mechanism for those packets, as well as a software architecture built around application processes and a set of standard services.
 
-* data extraction and post-processing of telemetry.
-* simulators.
-* EGSE SW, and thus enabling the use of mission control systems for controling and monitoring of EGSE equipment.
-* enable Python based commanding for mission control systems and other PUS based systems.
-* mission-specific tools.
-* student projects.
+Puslib covers two main use cases:
+
+* **TM/TC packet parsing** — deserialize raw packet streams, inspect packet fields, and extract parameter data for post-processing or analysis.
+* **PUS application stack** — implement a PUS-compliant backend that receives telecommands and emits telemetry, for use in EGSE equipment, simulators, or any system that communicates over TM/TC.
+
+The PUS stack is designed from the perspective of the system being monitored and controlled. It receives telecommands and produces telemetry, making it better suited for simulators and EGSE than for mission control systems. It targets ground tooling and test equipment rather than flight software, but don't let the sky be the limit.
 
 ## Install
 
-```Shell
+```shell
 pip install puslib
 ```
 
@@ -51,7 +50,7 @@ Python 3.10 or later is required.
 
 ## Basic Example
 
-```Python
+```python
 from datetime import datetime
 from functools import partial
 

{puslib-0.3.0 → puslib-0.4.0}/README.md

@@ -1,19 +1,19 @@
 # Puslib
 
-**Puslib** is a Python implementation of the telemetry and telecommand packet utilization standard (PUS). It is a standard widely used in the space industry for the purposes of remote monitoring and control of spacecraft subsystems and payloads.
+**Puslib** is a Python library for working with the ECSS Packet Utilization Standard (PUS), a protocol widely used in the space industry.
 
-This package is mainly intended for ground segment tools, e.g.:
+PUS defines an application-level interface between ground and space, covering both segments. It specifies a binary packet format for telecommands and telemetry (based on CCSDS space packets) and a routing mechanism for those packets, as well as a software architecture built around application processes and a set of standard services.
 
-* data extraction and post-processing of telemetry.
-* simulators.
-* EGSE SW, and thus enabling the use of mission control systems for controling and monitoring of EGSE equipment.
-* enable Python based commanding for mission control systems and other PUS based systems.
-* mission-specific tools.
-* student projects.
+Puslib covers two main use cases:
+
+* **TM/TC packet parsing** — deserialize raw packet streams, inspect packet fields, and extract parameter data for post-processing or analysis.
+* **PUS application stack** — implement a PUS-compliant backend that receives telecommands and emits telemetry, for use in EGSE equipment, simulators, or any system that communicates over TM/TC.
+
+The PUS stack is designed from the perspective of the system being monitored and controlled. It receives telecommands and produces telemetry, making it better suited for simulators and EGSE than for mission control systems. It targets ground tooling and test equipment rather than flight software, but don't let the sky be the limit.
 
 ## Install
 
-```Shell
+```shell
 pip install puslib
 ```
 
@@ -21,7 +21,7 @@ Python 3.10 or later is required.
 
 ## Basic Example
 
-```Python
+```python
 from datetime import datetime
 from functools import partial
 

{puslib-0.3.0 → puslib-0.4.0}/setup.cfg

@@ -31,6 +31,8 @@ package_dir = = src
 packages = find:
 include_package_data = True
 python_requires = >=3.10
+install_requires = 
+	bitstring
 
 [options.packages.find]
 where = src
@@ -38,6 +40,13 @@ where = src
 [tool:pytest]
 testpaths = tests
 
+[mypy]
+files = src/puslib
+python_version = 3.10
+warn_return_any = True
+warn_unused_ignores = True
+check_untyped_defs = True
+
 [egg_info]
 tag_build = 
 tag_date = 0

puslib-0.4.0/setup.py

@@ -0,0 +1,3 @@
+from setuptools import setup
+
+setup()

{puslib-0.3.0 → puslib-0.4.0}/src/puslib/__init__.py

@@ -2,7 +2,7 @@ from puslib.packet import PusTcPacket, PusTmPacket, AckFlag  # noqa: F401
 from puslib.time import CucTime  # noqa: F401
 from puslib.pus_policy import PusPolicy
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 _pus_policy = PusPolicy()
 
@@ -14,8 +14,14 @@ def set_policy(policy):
     e.g., various field lengths. This is due to that many parts of the PUS standard
     are mission-specific.
 
-    The PUS policy is set on a global scope, thus, multiple simultaneous PUS policies
-    are not supported. Might need to be reviewed in the future.
+    The policy is stored as a module-level global and is not thread-safe. This is a
+    deliberate design choice: the library assumes a single-threaded execution model
+    where the policy is set once at startup and remains unchanged for the lifetime of
+    the application. Calling set_policy() from multiple threads, or changing the policy
+    while packets are being processed, results in undefined behavior.
+
+    If per-thread policies are ever required, replace this global with a
+    contextvars.ContextVar to give each thread or async task its own policy instance.
 
     Arguments:
         policy -- PUS policy
@@ -24,7 +30,7 @@ def set_policy(policy):
     _pus_policy = policy
 
 
-def get_policy():
+def get_policy() -> PusPolicy:
     """Get the current selected PUS policy.
 
     Returns:

puslib-0.4.0/src/puslib/crc_ccitt.py

@@ -0,0 +1,20 @@
+"""CRC-16-CCITT checksum (polynomial 0x1021, preset 0xFFFF)."""
+
+import binascii
+
+_PRESET = 0xffff
+
+
+def calculate(buffer: bytes | bytearray | memoryview) -> int:
+    """Calculate the CRC-16-CCITT checksum on a buffer.
+
+    Using polynomial 0x1021 (default for crc_hqx) and preset (or initial value)
+    0xffff according to ECSS and CCSDS standards.
+
+    Arguments:
+        buffer -- input buffer to calculate checksum for
+
+    Returns:
+        16 bit CRC checksum
+    """
+    return binascii.crc_hqx(buffer, _PRESET)

{puslib-0.3.0 → puslib-0.4.0}/src/puslib/ident.py

@@ -1,4 +1,7 @@
-def _seq_count_generator():
+from typing import Iterator
+
+
+def _seq_count_generator() -> Iterator[int]:
     seq_count = -1
     max_count = 2 ** 14
     while True:
@@ -14,7 +17,7 @@ class PusIdent:
     - APID (Application ID)
     - packet sequence count
 
-    The sequence count is per APID and spans [0..32767].
+    The sequence count is per APID and spans [0..16383].
 
     The APID-sequence pair, thus, uniquely identifies a PUS packet for the foreseeable future.
     """
@@ -33,10 +36,10 @@ class PusIdent:
     def apid(self) -> int:
         return self._apid
 
-    def seq_count(self) -> int:
+    def next_seq_count(self) -> int:
         """Returns next sequence count.
 
         Returns:
-            sequence count [0..32767]
+            sequence count [0..16383]
         """
         return next(self._seq_count_generator)

{puslib-0.3.0 → puslib-0.4.0}/src/puslib/packet.py

@@ -10,11 +10,10 @@ Implementations of the following packet formats:
 import struct
 from enum import IntEnum, IntFlag
 from dataclasses import dataclass
-from typing import Optional, SupportsBytes
-
+from typing import Optional, cast
+from puslib.crc_ccitt import calculate as crc_ccitt_calculate
 from puslib.exceptions import CrcException, IncompletePacketException, InvalidPacketException
 from puslib.time import CucTime
-from puslib.crc_ccitt import calculate as crc_ccitt_calculate
 
 _CCSDS_PACKET_VERSION_NUMBER = 0
 _CCSDS_MAX_PACKET_SIZE = 65542
@@ -26,15 +25,15 @@ _COMMON_SEC_HDR_STRUCT = struct.Struct('>BBB')
 _PEC_FIELD_SIZE = 2
 
 
-def _validate_int_field(field_name: str, val: int, min_val: int, max_val: int):
-    if isinstance(val, int):
+def _validate_int_field(field_name: str, val: int, min_val: int, max_val: int) -> None:
+    if isinstance(val, int) and not isinstance(val, bool):
         if not min_val <= val <= max_val:
             raise InvalidPacketException(f"{field_name} must be between {min_val} and {max_val}")
     else:
         raise TypeError(f"{field_name} must be an integer")
 
 
-def _validate_bool_field(field_name: str, val: bool):
+def _validate_bool_field(field_name: str, val: bool) -> None:
     if not isinstance(val, bool):
         raise TypeError(f"{field_name} must be a bool")
 
@@ -81,8 +80,8 @@ class CcsdsSpacePacket:
             has_pec -- true if a PEC field should be present (default: {True})
         """
         self.header: _PacketPrimaryHeader = _PacketPrimaryHeader()
-        self.secondary_header = None
-        self.payload: SupportsBytes | None = None
+        self.secondary_header: _PacketSecondaryHeaderTc | _PacketSecondaryHeaderTm | None = None
+        self.payload: bytes | None = None
         self._has_pec = has_pec
 
     def __len__(self):
@@ -109,7 +108,7 @@ class CcsdsSpacePacket:
     def has_pec(self) -> bool:
         return self._has_pec
 
-    def serialize(self) -> SupportsBytes:
+    def serialize(self) -> bytes:
         """Serialize the packet to its binary format.
 
         Returns:
@@ -121,17 +120,17 @@ class CcsdsSpacePacket:
         if self.header.secondary_header_flag:
             packet_data_field = b''  # Leave it to subclasses to handle data field
         else:
-            packet_data_field = self.payload
+            packet_data_field = self.payload or b''
         return ccsds_header + packet_data_field
 
-    def request_id(self) -> SupportsBytes:
+    def request_id(self) -> bytes:
         packet_id = self.header.packet_version_number << 13 | (1 if self.header.packet_type == PacketType.TC else 0) << 12 | (1 if self.header.secondary_header_flag else 0) << 11 | self.header.apid
         seq_ctrl = self.header.seq_flags << 14 | self.header.seq_count_or_name
         return struct.pack('>HH', packet_id, seq_ctrl)
 
     @classmethod
-    def deserialize(cls, buffer: SupportsBytes, has_pec: bool = True, validate_pec: bool = True) -> "CcsdsSpacePacket":
-        """Deserialize a packet from its binary format to a packet object.
+    def _parse_primary_header(cls, buffer: bytes | bytearray | memoryview, has_pec: bool = True, validate_pec: bool = True) -> tuple[int, PacketType, bool, int, SequenceFlag, int, int]:
+        """Parse and validate the CCSDS primary header from a buffer.
 
         Arguments:
             buffer -- packet in binary format
@@ -141,9 +140,12 @@ class CcsdsSpacePacket:
             validate_pec -- true if PEC field should be verified during operation (default: {True})
 
         Returns:
-            packet object
+            tuple of (packet_version_number, packet_type, secondary_header_flag, apid, seq_flags, seq_count_or_name, data_length)
         """
-        packet_id, seq_ctrl, data_length = cls._CCSDS_HDR_STRUCT.unpack_from(buffer)
+        try:
+            packet_id, seq_ctrl, data_length = cls._CCSDS_HDR_STRUCT.unpack_from(buffer)
+        except struct.error:
+            raise IncompletePacketException()
 
         packet_size = cls._CCSDS_HDR_STRUCT.size + data_length + 1
         if packet_size > len(buffer):
@@ -156,10 +158,10 @@ class CcsdsSpacePacket:
                 raise CrcException
 
         packet_version_number = (packet_id >> 13) & 0b111
-        packet_type = PacketType.TC if (packet_id >> 12) & 0b1 == 1 else PacketType.TM
-        secondary_header_flag = True if (packet_id >> 11) & 0b1 == 1 else False
+        packet_type = PacketType((packet_id >> 12) & 0b1)
+        secondary_header_flag = bool((packet_id >> 11) & 0b1)
         apid = packet_id & 0x7ff
-        seq_flags = (seq_ctrl >> 14) & 0b11
+        seq_flags = SequenceFlag((seq_ctrl >> 14) & 0b11)
         seq_count_or_name = seq_ctrl & 0x3fff  # count or name
         return packet_version_number, packet_type, secondary_header_flag, apid, seq_flags, seq_count_or_name, data_length
 
@@ -199,6 +201,10 @@ class CcsdsSpacePacket:
         packet.header.apid = apid
 
         seq_flags = kwargs.get('seq_flags', SequenceFlag.UNSEGMENTED)
+        try:
+            seq_flags = SequenceFlag(seq_flags)
+        except ValueError:
+            raise ValueError(f"seq_flags must be a valid SequenceFlag value (0–3), got {seq_flags!r}")
         packet.header.seq_flags = seq_flags
 
         seq_count = kwargs.get('seq_count_or_name', 0)
@@ -209,7 +215,7 @@ class CcsdsSpacePacket:
         if isinstance(data, (bytearray, bytes, type(None))):
             if data is None:
                 data = bytes()
-            packet.payload = data
+            packet.payload = bytes(data)
         else:
             raise TypeError("Application data must be None, bytes or a bytearray")
 
@@ -257,7 +263,7 @@ class PusTcPacket(CcsdsSpacePacket):
 
     def __init__(self, has_pec: bool = True):
         super().__init__(has_pec)
-        self.secondary_header = _PacketSecondaryHeaderTc()
+        self.secondary_header: _PacketSecondaryHeaderTc = _PacketSecondaryHeaderTc()
 
     def __len__(self):
         size = super().__len__()
@@ -277,7 +283,7 @@ class PusTcPacket(CcsdsSpacePacket):
         return pkt_info
 
     @property
-    def name(self) -> str:
+    def name(self) -> int:
         return self.header.seq_count_or_name
 
     def ack(self, ack_flag: AckFlag) -> bool:
@@ -304,10 +310,10 @@ class PusTcPacket(CcsdsSpacePacket):
         return self.secondary_header.source
 
     @property
-    def app_data(self) -> SupportsBytes:
+    def app_data(self) -> bytes | None:
         return self.payload
 
-    def serialize(self):
+    def serialize(self) -> bytes:
         ccsds_header = super().serialize()
 
         if self.header.secondary_header_flag:
@@ -326,18 +332,17 @@ class PusTcPacket(CcsdsSpacePacket):
             ccsds_sec_header_static = bytes()
 
         # Packet error control
-        packet_without_pec = ccsds_header + (ccsds_sec_header_static + ccsds_sec_header_source if self.header.secondary_header_flag else bytes()) + (self.payload if self.header.secondary_header_flag else bytes())
+        packet_without_pec = ccsds_header + (ccsds_sec_header_static + ccsds_sec_header_source if self.header.secondary_header_flag else bytes()) + (self.payload or b'' if self.header.secondary_header_flag else bytes())
         if self.has_pec:
             mem_view = memoryview(packet_without_pec)
-            pec = crc_ccitt_calculate(mem_view)
-            pec = pec.to_bytes(_PEC_FIELD_SIZE, byteorder='big')
+            pec = crc_ccitt_calculate(mem_view).to_bytes(_PEC_FIELD_SIZE, byteorder='big')
         else:
             pec = bytes()
 
         return packet_without_pec + pec
 
     @classmethod
-    def deserialize(cls, buffer: SupportsBytes, has_pec: bool = True, validate_pec: bool = True, has_source_field: bool = True, validate_fields: bool = True):
+    def deserialize(cls, buffer: bytes | bytearray | memoryview, has_pec: bool = True, validate_pec: bool = True, has_source_field: bool = True, validate_fields: bool = True) -> "PusTcPacket":
         """Deserialize a packet from its binary format to a packet object.
 
         Arguments:
@@ -352,7 +357,7 @@ class PusTcPacket(CcsdsSpacePacket):
         Returns:
             packet object
         """
-        packet_version_number, packet_type, secondary_header_flag, apid, seq_flags, seq_count_or_name, data_length = super(cls, cls).deserialize(buffer, has_pec, validate_pec)
+        packet_version_number, packet_type, secondary_header_flag, apid, seq_flags, seq_count_or_name, data_length = cls._parse_primary_header(buffer, has_pec, validate_pec)
         offset = cls._CCSDS_HDR_STRUCT.size
 
         data_field_except_source_length = ((_COMMON_SEC_HDR_STRUCT.size + (cls._SOURCE_FIELD_SIZE if has_source_field else 0)) if secondary_header_flag else 0) + (2 if has_pec else 0)
@@ -409,7 +414,8 @@ class PusTcPacket(CcsdsSpacePacket):
             packet.header.data_length = data_length
             packet.payload = app_data
             packet.secondary_header.pus_version = pus_version
-            packet.secondary_header.ack_flags = ack_flags
+            if ack_flags is not None:
+                packet.secondary_header.ack_flags = ack_flags
             packet.secondary_header.service_type = service_type
             packet.secondary_header.service_subtype = service_subtype
             packet.secondary_header.source = source
@@ -417,7 +423,7 @@ class PusTcPacket(CcsdsSpacePacket):
         return packet
 
     @classmethod
-    def create(cls, **kwargs):
+    def create(cls, **kwargs) -> "PusTcPacket":
         """A factory method to create a PUS TC packet instance.
 
         Keyword Arguments:
@@ -444,7 +450,7 @@ class PusTcPacket(CcsdsSpacePacket):
             kwargs['secondary_header_length'] = secondary_header_length
         kwargs['packet_type'] = PacketType.TC
         kwargs['seq_count_or_name'] = kwargs.get('name', 0)
-        packet = super(cls, cls).create(**kwargs)
+        packet = super().create(**kwargs)
 
         if packet.header.secondary_header_flag:
             pus_version = kwargs.get('pus_version', _TC_PACKET_PUS_VERSION_NUMBER)
@@ -471,7 +477,7 @@ class PusTcPacket(CcsdsSpacePacket):
                 _validate_int_field('Source ID', source, 0, 0xffff)
                 packet.secondary_header.source = source
 
-        return packet
+        return cast("PusTcPacket", packet)
 
 
 @dataclass(slots=True)
@@ -493,7 +499,7 @@ class PusTmPacket(CcsdsSpacePacket):
 
     def __init__(self, has_pec: bool = True):
         super().__init__(has_pec)
-        self.secondary_header = _PacketSecondaryHeaderTm()
+        self.secondary_header: _PacketSecondaryHeaderTm = _PacketSecondaryHeaderTm()
 
     def __len__(self):
         size = super().__len__()
@@ -503,7 +509,7 @@ class PusTmPacket(CcsdsSpacePacket):
                 size += self._MSG_TYPE_COUNTER_FIELD_SIZE
             if self.secondary_header.destination is not None:
                 size += self._DESTINATION_FIELD_SIZE
-            size += len(self.secondary_header.time)
+            size += len(self.secondary_header.time) if self.secondary_header.time else 0
         return size
 
     def __str__(self):
@@ -537,14 +543,14 @@ class PusTmPacket(CcsdsSpacePacket):
         return self.secondary_header.destination
 
     @property
-    def time(self) -> CucTime:
+    def time(self) -> CucTime | None:
         return self.secondary_header.time
 
     @property
-    def source_data(self) -> SupportsBytes:
+    def source_data(self) -> bytes | None:
         return self.payload
 
-    def serialize(self):
+    def serialize(self) -> bytes:
         ccsds_header = super().serialize()
 
         # First static part of secondary header
@@ -563,18 +569,17 @@ class PusTmPacket(CcsdsSpacePacket):
             ccsds_sec_header_destination = bytes()
 
         # Packet error control
-        packet_without_pec = ccsds_header + ccsds_sec_header_static + ccsds_sec_header_msg_type_counter + ccsds_sec_header_destination + bytes(self.secondary_header.time) + self.payload
+        packet_without_pec = ccsds_header + ccsds_sec_header_static + ccsds_sec_header_msg_type_counter + ccsds_sec_header_destination + (bytes(self.secondary_header.time) if self.secondary_header.time else b'') + (self.payload or b'')
         if self.has_pec:
             mem_view = memoryview(packet_without_pec)
-            pec = crc_ccitt_calculate(mem_view)
-            pec = pec.to_bytes(_PEC_FIELD_SIZE, byteorder='big')
+            pec = crc_ccitt_calculate(mem_view).to_bytes(_PEC_FIELD_SIZE, byteorder='big')
         else:
             pec = bytes()
 
         return packet_without_pec + pec
 
     @classmethod
-    def deserialize(cls, buffer: SupportsBytes, has_pec: bool = True, validate_pec: bool = True, cuc_time: CucTime | None = None, has_type_counter_field: bool = True, has_destination_field: bool = True, validate_fields: bool = True):
+    def deserialize(cls, buffer: bytes | bytearray | memoryview, has_pec: bool = True, validate_pec: bool = True, cuc_time: CucTime | None = None, has_type_counter_field: bool = True, has_destination_field: bool = True, validate_fields: bool = True) -> "PusTmPacket":
         """Deserialize a packet from its binary format to a packet object.
 
         Arguments:
@@ -591,7 +596,7 @@ class PusTmPacket(CcsdsSpacePacket):
         Returns:
             packet object
         """
-        packet_version_number, packet_type, secondary_header_flag, apid, seq_flags, seq_count_or_name, data_length = super(cls, cls).deserialize(buffer, has_pec, validate_pec)
+        packet_version_number, packet_type, secondary_header_flag, apid, seq_flags, seq_count_or_name, data_length = cls._parse_primary_header(buffer, has_pec, validate_pec)
         offset = cls._CCSDS_HDR_STRUCT.size
 
         if secondary_header_flag:
@@ -682,7 +687,7 @@ class PusTmPacket(CcsdsSpacePacket):
         return packet
 
     @classmethod
-    def create(cls, **kwargs):
+    def create(cls, **kwargs) -> "PusTmPacket":
         """A factory method to create a PUS TM packet instance.
 
         Keyword Arguments:
@@ -709,11 +714,11 @@ class PusTmPacket(CcsdsSpacePacket):
         time = kwargs.get('time', None)
 
         if kwargs.get('secondary_header_flag', True):
-            secondary_header_length = _COMMON_SEC_HDR_STRUCT.size + (2 if msg_type_counter is not None else 0) + (2 if destination is not None else 0) + len(time)
+            secondary_header_length = _COMMON_SEC_HDR_STRUCT.size + (2 if msg_type_counter is not None else 0) + (2 if destination is not None else 0) + (len(time) if time else 0)
             kwargs['secondary_header_length'] = secondary_header_length
         kwargs['packet_type'] = PacketType.TM
         kwargs['seq_count_or_name'] = kwargs.get('seq_count', 0)
-        packet = super(cls, cls).create(**kwargs)
+        packet = super().create(**kwargs)
 
         if packet.header.secondary_header_flag:
             pus_version = kwargs.get('pus_version', _TM_PACKET_PUS_VERSION_NUMBER)
@@ -746,4 +751,4 @@ class PusTmPacket(CcsdsSpacePacket):
             if time:
                 packet.secondary_header.time = time
 
-        return packet
+        return cast("PusTmPacket", packet)