space_packet_parser.generators.udp
==================================

.. py:module:: space_packet_parser.generators.udp

.. autoapi-nested-parse::

   UDP packet generator.

   This module provides functionality for parsing UDP (User Datagram Protocol) packets from binary data sources.
   UDP is a connectionless transport protocol defined in RFC 768.

   Classes
   -------
   UDPPacketBytes : bytes
       Binary representation of a UDP packet with header field accessors.

   Functions
   ---------
   create_udp_packet : UDPPacketBytes
       Factory function to create UDP packets from components.
   udp_generator : Iterator[UDPPacketBytes]
       Generator that yields UDP packets from binary data sources.



Classes
-------

.. autoapisummary::

   space_packet_parser.generators.udp.UDPPacketBytes


Functions
---------

.. autoapisummary::

   space_packet_parser.generators.udp.create_udp_packet
   space_packet_parser.generators.udp.udp_generator


Module Contents
---------------

.. py:class:: UDPPacketBytes

   Bases: :py:obj:`bytes`


   Binary (bytes) representation of a UDP packet.

   Methods to extract the UDP header fields are added to the raw bytes object.
   This class follows the same pattern as CCSDSPacketBytes.

   UDP Packet Structure (RFC 768):
   - Source Port: 16 bits (0-65535)
   - Destination Port: 16 bits (0-65535)
   - Length: 16 bits (total length in bytes including 8-byte header)
   - Checksum: 16 bits (optional error checking)
   - Data: Variable length payload


   .. py:attribute:: HEADER_LENGTH_BYTES
      :value: 8



   .. py:method:: __str__() -> str

      Return a human-readable string representation of the UDP packet header.



   .. py:property:: source_port
      :type: int


      UDP source port (16 bits, bytes 0-1).


   .. py:property:: dest_port
      :type: int


      UDP destination port (16 bits, bytes 2-3).


   .. py:property:: length
      :type: int


      UDP packet length in bytes, including 8-byte header (16 bits, bytes 4-5).


   .. py:property:: checksum
      :type: int


      UDP checksum (16 bits, bytes 6-7).


   .. py:property:: header_values
      :type: tuple[int, Ellipsis]


      Convenience property for tuple of header values.

      :returns: Tuple containing (source_port, dest_port, length, checksum).
      :rtype: tuple[int, ...]


   .. py:property:: header
      :type: bytes


      Convenience property returns the UDP header bytes (first 8 bytes).

      :returns: The 8-byte UDP header.
      :rtype: bytes


   .. py:property:: data
      :type: bytes


      Convenience property returns only the UDP payload data (no header).

      :returns: The UDP payload data without the header.
      :rtype: bytes


.. py:function:: create_udp_packet(data: bytes = b'', *, source_port: int = 0, dest_port: int = 0, checksum: int = 0) -> UDPPacketBytes

   Create a binary UDP packet from input values.

   Pack the header fields into the proper bit locations and append the data bytes.

   :param data: Payload data bytes.
   :type data: bytes
   :param source_port: UDP source port (16 bits, 0-65535).
   :type source_port: int
   :param dest_port: UDP destination port (16 bits, 0-65535).
   :type dest_port: int
   :param checksum: UDP checksum (16 bits, 0-65535). Use 0 if not computed.
   :type checksum: int

   :returns: Resulting binary UDP packet.
   :rtype: UDPPacketBytes

   :raises ValueError: If any field value is out of range or if the total packet length exceeds 65535 bytes.

   .. rubric:: Notes

   This function is useful for generating test UDP packets for debugging or mocking purposes.
   The length field is automatically computed as 8 + len(data).


.. py:function:: udp_generator(binary_data: BinaryIO | socket.socket | bytes, *, buffer_read_size_bytes: int | None = None, show_progress: bool = False) -> collections.abc.Iterator[UDPPacketBytes]

   A generator that reads UDP packets from binary data.

   Each iteration yields a UDPPacketBytes object representing a single UDP packet.
   The generator reads the UDP length field to determine packet boundaries.

   :param binary_data: Binary data source containing UDP packets. Can be a file-like object, socket, or bytes.
   :type binary_data: Union[BinaryIO, socket.socket, bytes]
   :param buffer_read_size_bytes: Number of bytes to read from e.g. a BufferedReader or socket binary data source on each read attempt.
                                  If None, defaults to 4096 bytes from a socket, -1 (full read) from a file.
   :type buffer_read_size_bytes: int, optional
   :param show_progress: Default False.
                         If True, prints a status bar. Note that for socket sources, the percentage will be zero until the generator
                         ends.
   :type show_progress: bool

   :Yields: *UDPPacketBytes* -- The bytes of a single UDP packet.

   .. rubric:: Notes

   This generator assumes:
   - Binary data contains back-to-back UDP packets with no additional framing
   - Each packet has a valid length field
   - No error checking or recovery from malformed packets