Release: v0.5.0

[RemingtonRohel]

This release moves to a mixed Python/Rust project, featuring a more user-friendly Python API with integration tests on the API. It also bumps pyo3 to 0.26.0, which adds support up to Python 3.14.

Python API

The functions below show the generic read/write ability of this package. Additionally, there are specific functions for each SuperDARN file type (iqdat, rawacf, fitacf, grid, map, and snd). These are structured identically, but conduct more tests to determine that the data is compliant with the specific file format (i.e. all required fields are present, no additional fields are present, fields have the expected data type, etc.).

def read_dmap(
    source: Union[str, bytes], mode: str = "lax"
) -> Union[dict, list[dict], tuple[list[dict], Optional[int]]]:
    """
    Reads in DMAP data from `source`.

    Parameters
    ----------
    source: Union[str, bytes]
        Where to read data from. If input is of type `str`, this is interpreted as the path to a file.
        If input is of type `bytes`, this is interpreted as the raw data itself.
    mode: str
        Mode in which to read the data, either "lax" (default), "strict", or "sniff".
        In "lax" mode, all valid records will be returned in a tuple along with the byte index of `source` where the
        corruption starts.
        In "strict" mode, any corruption in the data will raise an error.
        In "sniff" mode, `source` must be a path, and only the first record will be read.

    Returns
    -------
    If `mode` is `lax`, returns `tuple[list[dict], Optional[int]]`, where the first element is the records which were parsed,
    and the second is the byte index where `source` was no longer a valid record of type `fmt`.
    If `mode` is `strict`, returns `list[dict]` which is the parsed records.
    If `mode` is `sniff`, returns `dict`, which is the first record.
    """

def write_dmap(
    source: list[dict], outfile: Union[None, str] = None
) -> Union[None, bytes]:
    """
    Writes DMAP data from `source` to either a `bytes` object or to `outfile`.

    Parameters
    ----------
    source: list[dict]
        list of DMAP records as dictionaries.
    outfile: Union[None, str]
        If `None`, returns the data as a `bytes` object. If this is a string, then this is interpreted as a path
        and data will be written to the filesystem. If the file ends in the `.bz2` extension, the data will be
        compressed using bzip2.
    """

Rust API

This can be seen by cloning the repo and running cargo doc to generate the HTML documentation. Once this crate is published, you can search for the darn-dmap crate on https://docs.rs/.