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

.. py:module:: space_packet_parser.generators.utils

.. autoapi-nested-parse::

   Utility functions for building packet generators.



Attributes
----------

.. autoapisummary::

   space_packet_parser.generators.utils.logger


Functions
---------

.. autoapisummary::

   space_packet_parser.generators.utils._read_packet_file
   space_packet_parser.generators.utils._
   space_packet_parser.generators.utils._
   space_packet_parser.generators.utils._
   space_packet_parser.generators.utils._
   space_packet_parser.generators.utils._
   space_packet_parser.generators.utils._setup_binary_reader
   space_packet_parser.generators.utils._
   space_packet_parser.generators.utils._
   space_packet_parser.generators.utils._
   space_packet_parser.generators.utils._
   space_packet_parser.generators.utils._print_progress


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

.. py:data:: logger

.. py:function:: _read_packet_file(packet_file) -> Union[bytes, io.BufferedIOBase, io.RawIOBase]

   Read a packet file or file-like object and return an object suitable for passing to a generator.

   Specifically this function prepares the input for use with _setup_binary_reader.

   :param packet_file:
   :type packet_file: Union[str, Path, PathLike, BinaryIO, bytes]

   .. rubric:: Notes

   This function handles strings and pathlike objects but it reads the full file into memory for the generator.
   This alleviates the need for generators to internally handle opening and closing files.
   For a more memory efficient approach, pass an opened file object.


.. py:function:: _(packet_file: Union[io.BufferedIOBase, io.RawIOBase]) -> Union[io.BufferedIOBase, io.RawIOBase]

   File-like object, this can be passed directly to a generator.


.. py:function:: _(packet_file: bytes) -> bytes

   bytes input, return as-is.


.. py:function:: _(packet_file: str) -> bytes

   String file path, open and read bytes.


.. py:function:: _(packet_file: pathlib.Path) -> bytes

   Path file path, open and read bytes.

   .. rubric:: Notes

   This is a bit inefficient as we have to read the entire file into memory, but it does ensure we close the file after reading.


.. py:function:: _(packet_file: os.PathLike) -> bytes

   PathLike file path (e.g. anything supporting the Path interface), open and read bytes.

   .. rubric:: Notes

   This is a bit inefficient as we have to read the entire file into memory, but it does ensure we close the file after reading.


.. py:function:: _setup_binary_reader(binary_data, buffer_read_size_bytes=None) -> tuple

   Helper to set up reading from binary_data (file, socket, bytes) for a packet generator.

   :param binary_data: The binary data source to read from.
   :type binary_data: Union[io.BufferedIOBase, socket.socket, bytes]
   :param buffer_read_size_bytes: The number of bytes to read at a time from the source. If None, defaults to a sensible value based on the type of source.
   :type buffer_read_size_bytes: Optional[int]

   :rtype: read_buffer, total_length_bytes, read_bytes_from_source, buffer_read_size_bytes

   .. rubric:: Notes

   This function does not handle pathlike objects. It expects objects to be opened and readable already.


.. py:function:: _(binary_data: Union[io.BufferedIOBase, io.RawIOBase], buffer_read_size_bytes=None) -> tuple

   Set up a binary reader from a file-like object.


.. py:function:: _(binary_data: socket.socket, buffer_read_size_bytes=None) -> tuple

   Set up a binary reader from a socket object.


.. py:function:: _(binary_data: bytes, buffer_read_size_bytes=None) -> tuple

   Set up a binary reader from a bytes object.


.. py:function:: _(binary_data: io.TextIOWrapper, buffer_read_size_bytes=None)

   Informative error if someone tries to pass a text file.


.. py:function:: _print_progress(*, current_bytes: int, total_bytes: Optional[int], start_time_ns: int, current_packets: int, end: str = '\r', log: bool = False)

   Prints a progress bar for a packet generator, including statistics on parsing rate.

   :param current_bytes: Number of bytes parsed so far.
   :type current_bytes: int
   :param total_bytes: Number of total bytes to parse, if known. None otherwise.
   :type total_bytes: Optional[int]
   :param current_packets: Number of packets parsed so far.
   :type current_packets: int
   :param start_time_ns: Start time on system clock, in nanoseconds.
   :type start_time_ns: int
   :param end: Print function end string. Default is `\r` to create a dynamically updating loading bar.
   :type end: str
   :param log: If True, log the progress bar at INFO level.
   :type log: bool