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

.. py:module:: space_packet_parser.generators

.. autoapi-nested-parse::

   Generators subpackage, containing packet generators for different packet formats.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/space_packet_parser/generators/ccsds/index
   /autoapi/space_packet_parser/generators/fixed_length/index
   /autoapi/space_packet_parser/generators/udp/index
   /autoapi/space_packet_parser/generators/utils/index


Functions
---------

.. autoapisummary::

   space_packet_parser.generators.ccsds_generator
   space_packet_parser.generators.fixed_length_generator
   space_packet_parser.generators.udp_generator


Package Contents
----------------

.. py:function:: ccsds_generator(binary_data: io.BufferedIOBase | io.RawIOBase | socket.socket | bytes, *, buffer_read_size_bytes: int | None = None, show_progress: bool = False, skip_header_bytes: int = 0, combine_segmented_packets: bool = False, secondary_header_bytes: int = 0) -> collections.abc.Iterator[CCSDSPacketBytes]

   A generator that reads raw packet data from a filelike object or a socket.

   Each iteration of the generator yields a ``CCSDSPacketBytes`` object that makes up
   a single CCSDS packet. If combining segmented packets is enabled, the generator will
   combine segmented packets into a single packet for parsing. This is useful for parsing
   packets that are split into multiple packets due to size constraints.

   :param binary_data: Binary data source containing CCSDSPackets.
   :type binary_data: Union[io.BufferedIOBase, io.RawIOBase, 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
   :param skip_header_bytes: Default 0. The parser skips this many bytes at the beginning of every packet. This allows dynamic stripping
                             of additional header data that may be prepended to packets in "raw record" file formats.
   :type skip_header_bytes: int
   :param combine_segmented_packets: Default False. If True, combines segmented packets into a single packet for parsing. This is useful for
                                     parsing packets that are split into multiple packets due to size constraints. The packet data is combined
                                     by concatenating the data from each packet together. The combined packet is then parsed as a single packet.
                                     Only the first CCSDS header is kept when concatenating continued packets. CCSDS headers (and secondary headers)
                                     from continuation packets are discarded.
   :type combine_segmented_packets: bool
   :param secondary_header_bytes: Default 0. The length of the secondary header in bytes.
                                  This is used to skip the secondary header of segmented packets.
                                  The byte layout within the returned packet has all data concatenated together as follows:
                                  [packet0header, packet0secondaryheader, packet0data, packet1data, packet2data, ...].
   :type secondary_header_bytes: int

   :Yields: *CCSDSPacketBytes* -- The bytes of a single CCSDS packet.


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

   A generator that yields fixed-length chunks from binary_data.

   :param binary_data: Binary data source.
   :type binary_data: Union[BinaryIO, socket.socket, bytes]
   :param packet_length_bytes: Number of bytes per packet to yield.
   :type packet_length_bytes: int
   :param buffer_read_size_bytes: Number of bytes to read from the source per read.
   :type buffer_read_size_bytes: int, optional
   :param show_progress: If True, prints a status bar.
   :type show_progress: bool

   :Yields: *bytes* -- Fixed-length packet bytes.


.. 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