marlin-py 0.1.0__tar.gz

marlin_py-0.1.0/Cargo.toml

@@ -0,0 +1,44 @@
+[workspace]
+resolver = "2"
+members = [
+    "crates/marlin-nmea-envelope",
+    "crates/marlin-nmea-0183",
+    "crates/marlin-ais",
+]
+# The fuzz crate is not part of the main workspace because it requires
+# nightly rustc (cargo-fuzz uses unstable sanitizers). Run it via
+# `cargo +nightly fuzz run <target>`.
+exclude = ["fuzz", "bindings/python"]
+
+[workspace.package]
+version = "0.1.0"
+edition = "2021"
+rust-version = "1.82"
+license = "MIT OR Apache-2.0"
+authors = ["Jurdanas"]
+repository = "https://github.com/jkr78/marlin"
+readme = "README.md"
+
+[workspace.dependencies]
+nom = { version = "8", default-features = false, features = ["alloc"] }
+bytes = "1"
+thiserror = "2"
+tracing = { version = "0.1", default-features = false }
+
+[workspace.lints.rust]
+unsafe_code = "forbid"
+missing_docs = "warn"
+
+[workspace.lints.clippy]
+pedantic = { level = "warn", priority = -1 }
+unwrap_used = "deny"
+expect_used = "deny"
+panic = "deny"
+indexing_slicing = "deny"
+module_name_repetitions = "allow"
+must_use_candidate = "allow"
+missing_errors_doc = "allow"
+
+[profile.release]
+lto = "thin"
+codegen-units = 1

marlin_py-0.1.0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: marlin-py
+Version: 0.1.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Communications
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Networking
+Classifier: Typing :: Typed
+Requires-Dist: pytest>=7 ; extra == 'dev'
+Requires-Dist: hypothesis>=6 ; extra == 'dev'
+Requires-Dist: mypy>=1.8 ; extra == 'dev'
+Provides-Extra: dev
+Summary: Sans-I/O NMEA 0183 + AIS (AIVDM/AIVDO) parser, Rust-backed
+Keywords: nmea,nmea-0183,ais,aivdm,aivdo,marine,maritime,gps,parser,sans-io
+Author: Jurdanas
+License: MIT OR Apache-2.0
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Changelog, https://github.com/jkr78/marlin/blob/main/bindings/python/CHANGELOG.md
+Project-URL: Documentation, https://github.com/jkr78/marlin/tree/main/bindings/python
+Project-URL: Homepage, https://github.com/jkr78/marlin
+Project-URL: Issues, https://github.com/jkr78/marlin/issues
+Project-URL: Repository, https://github.com/jkr78/marlin
+
+# marlin-py
+
+Python bindings for the Marlin Rust suite — NMEA 0183 envelope parsing,
+typed sentence decoding, and AIS (AIVDM/AIVDO) message decoding with
+multi-sentence reassembly.
+
+## Status
+
+Wraps three Rust crates: `marlin-nmea-envelope` (framing + checksum),
+`marlin-nmea-0183` (GGA, VTG, HDT, PSXN, PRDID typed decoders), and
+`marlin-ais` (Types 1/2/3/5/18/19/24A/24B + reassembly). API surface is
+feature-complete for v0.1. `py.typed` marker and `.pyi` stubs ship with the
+package; mypy `--strict` is clean across the entire `python/marlin/`, `tests/`, and `examples/` tree.
+
+## Install
+
+The PyPI distribution name is `marlin-py`; the Python import name stays
+plain `marlin`.
+
+```bash
+# From PyPI (once the v0.1.0 wheels publish)
+pip install marlin-py
+
+# Local development — build the extension in-place
+cd bindings/python
+maturin develop
+```
+
+## Quickstart: envelope
+
+```python
+from marlin.envelope import StreamingParser
+
+parser = StreamingParser()
+parser.feed(b"$GPGGA,123519,4807.038,N,01131.000,E,1,08,0.9,545.4,M,46.9,M,,*47\r\n")
+for sentence in parser:
+    talker = sentence.talker.decode() if sentence.talker else ""
+    print(talker, sentence.sentence_type, sentence.checksum_ok)
+    # GP GGA True
+```
+
+`OneShotParser` handles UDP datagrams (no `\r\n` required). `parse()` is a
+one-call convenience for a single complete sentence.
+
+## Quickstart: NMEA typed decode
+
+```python
+from marlin.envelope import parse
+from marlin.nmea import Nmea0183Parser, decode_gga, DecodeOptions, PrdidDialect
+
+# Single-sentence convenience.
+raw = parse(b"$GPGGA,123519,4807.038,N,01131.000,E,1,08,0.9,545.4,M,46.9,M,,*47")  # raises EnvelopeError on framing/checksum failure
+gga = decode_gga(raw)                # raises DecodeError if not GGA or fields are malformed
+print(gga.latitude_deg, gga.longitude_deg, gga.fix_quality)
+
+# Streaming parser — same feed/iterate API as the envelope layer.
+parser = Nmea0183Parser.streaming()
+parser.feed(b"$GPGGA,123519,4807.038,N,01131.000,E,1,08,0.9,545.4,M,46.9,M,,*47\r\n")
+for msg in parser:
+    print(type(msg).__name__, msg)
+```
+
+`DecodeOptions` configures dialect-sensitive sentences:
+
+```python
+opts = DecodeOptions().with_prdid_dialect(PrdidDialect.PITCH_ROLL_HEADING)
+parser = Nmea0183Parser.streaming(options=opts)
+```
+
+Per-sentence extension functions (`decode_gga`, `decode_vtg`, `decode_hdt`,
+`decode_psxn`, `decode_prdid`) are public so downstream code can build its
+own message enum and delegate to Marlin for the standard types.
+
+## Quickstart: AIS
+
+```python
+from marlin.ais import AisParser, PositionReportA
+
+parser = AisParser.streaming()
+parser.feed(b"!AIVDM,1,1,,A,13aGmP0P00PD;88MD5MTDww@2<0L,0*23\r\n")
+for msg in parser:
+    if isinstance(msg.body, PositionReportA):
+        print(msg.body.mmsi, msg.body.latitude_deg, msg.body.longitude_deg)
+```
+
+Multi-sentence reassembly is automatic — feed fragments in order and the
+parser yields a complete `AisMessage` only when the last fragment arrives.
+
+## AIS clock modes
+
+Fragment reassembly has three timeout behaviours, selected at construction.
+
+**No timeout** — fragments are buffered until the 16-slot eviction cap is
+reached. The oldest incomplete group is discarded when a 17th arrives. No
+clock reads occur:
+
+```python
+parser = AisParser.streaming()          # timeout_ms omitted → no timeout
+```
+
+**Auto clock** — the binding calls `time.monotonic_ns()` internally to
+drive the timeout. Use this when system time is reliable and you do not
+need deterministic replay:
+
+```python
+parser = AisParser.streaming(timeout_ms=60_000)          # clock="auto" implied
+# or explicitly:
+parser = AisParser.streaming(timeout_ms=60_000, clock="auto")
+```
+
+**Manual clock** — the caller drives the clock via `tick(now_ms=...)`. No
+clock reads occur inside the binding. This is the correct mode for unit
+tests, simulators, and any environment where `time` is patched:
+
+```python
+parser = AisParser.streaming(timeout_ms=60_000, clock="manual")
+
+parser.feed(fragment_bytes)
+parser.tick(now_ms=current_time_ms)     # expire stale groups at this instant
+for msg in parser:
+    ...
+```
+
+Calling `tick()` on a parser that wasn't built with `clock="manual"` raises
+`ValueError` — including parsers built with no `timeout_ms` (which default to
+`clock="auto"`).
+
+## Errors
+
+Every exception is a `MarlinError` subclass (importable from `marlin`):
+
+- `EnvelopeError` — framing or checksum failure
+- `DecodeError` — field-level decode failure in a typed NMEA sentence
+- `AisError` — AIS armor or bit-level decode failure
+- `ReassemblyError` — fragment reassembly violation (out-of-order, channel
+  mismatch, or timeout eviction)
+
+Property tests (via Hypothesis) verify panic-freedom on arbitrary byte
+inputs — no input can cause the binding to crash the interpreter.
+
+## Examples
+
+Six runnable scripts live in `bindings/python/examples/`:
+
+| Script | What it shows |
+| --- | --- |
+| `one_shot_no_crlf.py` | Single-datagram framing without `\r\n` (`OneShotParser`) |
+| `parse_log_file.py` | Disk-backed `.nmea` log replay (`StreamingParser`) |
+| `streaming_tcp_style.py` | TCP-style chunked feed; sentences straddle `feed()` boundaries |
+| `decode_aivdm_log.py` | Multi-fragment AIS reassembly: Type 1 + Type 5 |
+| `parse_stdin.py` | Stdin pipe reader for live NMEA/AIS capture |
+| `live_ais_dashboard.py` | Live ship tracker: envelope + AIS in one script, periodic refresh |
+
+## Type stubs
+
+The `py.typed` marker is included in the package. Every public class,
+function, and constant has a `.pyi` stub. Downstream projects that run
+`mypy --strict` get full type-check coverage without extra configuration.
+
+## Rust crates
+
+The Python bindings wrap three Rust crates:
+[`marlin-nmea-envelope`](../../crates/marlin-nmea-envelope),
+[`marlin-nmea-0183`](../../crates/marlin-nmea-0183),
+[`marlin-ais`](../../crates/marlin-ais).
+
+## MSRV / Python version
+
+Rust 1.82. Python 3.9+.
+
+## License
+
+Dual-licensed under MIT OR Apache-2.0.
+

marlin_py-0.1.0/README.md

@@ -0,0 +1,173 @@
+# marlin-py
+
+Python bindings for the Marlin Rust suite — NMEA 0183 envelope parsing,
+typed sentence decoding, and AIS (AIVDM/AIVDO) message decoding with
+multi-sentence reassembly.
+
+## Status
+
+Wraps three Rust crates: `marlin-nmea-envelope` (framing + checksum),
+`marlin-nmea-0183` (GGA, VTG, HDT, PSXN, PRDID typed decoders), and
+`marlin-ais` (Types 1/2/3/5/18/19/24A/24B + reassembly). API surface is
+feature-complete for v0.1. `py.typed` marker and `.pyi` stubs ship with the
+package; mypy `--strict` is clean across the entire `python/marlin/`, `tests/`, and `examples/` tree.
+
+## Install
+
+The PyPI distribution name is `marlin-py`; the Python import name stays
+plain `marlin`.
+
+```bash
+# From PyPI (once the v0.1.0 wheels publish)
+pip install marlin-py
+
+# Local development — build the extension in-place
+cd bindings/python
+maturin develop
+```
+
+## Quickstart: envelope
+
+```python
+from marlin.envelope import StreamingParser
+
+parser = StreamingParser()
+parser.feed(b"$GPGGA,123519,4807.038,N,01131.000,E,1,08,0.9,545.4,M,46.9,M,,*47\r\n")
+for sentence in parser:
+    talker = sentence.talker.decode() if sentence.talker else ""
+    print(talker, sentence.sentence_type, sentence.checksum_ok)
+    # GP GGA True
+```
+
+`OneShotParser` handles UDP datagrams (no `\r\n` required). `parse()` is a
+one-call convenience for a single complete sentence.
+
+## Quickstart: NMEA typed decode
+
+```python
+from marlin.envelope import parse
+from marlin.nmea import Nmea0183Parser, decode_gga, DecodeOptions, PrdidDialect
+
+# Single-sentence convenience.
+raw = parse(b"$GPGGA,123519,4807.038,N,01131.000,E,1,08,0.9,545.4,M,46.9,M,,*47")  # raises EnvelopeError on framing/checksum failure
+gga = decode_gga(raw)                # raises DecodeError if not GGA or fields are malformed
+print(gga.latitude_deg, gga.longitude_deg, gga.fix_quality)
+
+# Streaming parser — same feed/iterate API as the envelope layer.
+parser = Nmea0183Parser.streaming()
+parser.feed(b"$GPGGA,123519,4807.038,N,01131.000,E,1,08,0.9,545.4,M,46.9,M,,*47\r\n")
+for msg in parser:
+    print(type(msg).__name__, msg)
+```
+
+`DecodeOptions` configures dialect-sensitive sentences:
+
+```python
+opts = DecodeOptions().with_prdid_dialect(PrdidDialect.PITCH_ROLL_HEADING)
+parser = Nmea0183Parser.streaming(options=opts)
+```
+
+Per-sentence extension functions (`decode_gga`, `decode_vtg`, `decode_hdt`,
+`decode_psxn`, `decode_prdid`) are public so downstream code can build its
+own message enum and delegate to Marlin for the standard types.
+
+## Quickstart: AIS
+
+```python
+from marlin.ais import AisParser, PositionReportA
+
+parser = AisParser.streaming()
+parser.feed(b"!AIVDM,1,1,,A,13aGmP0P00PD;88MD5MTDww@2<0L,0*23\r\n")
+for msg in parser:
+    if isinstance(msg.body, PositionReportA):
+        print(msg.body.mmsi, msg.body.latitude_deg, msg.body.longitude_deg)
+```
+
+Multi-sentence reassembly is automatic — feed fragments in order and the
+parser yields a complete `AisMessage` only when the last fragment arrives.
+
+## AIS clock modes
+
+Fragment reassembly has three timeout behaviours, selected at construction.
+
+**No timeout** — fragments are buffered until the 16-slot eviction cap is
+reached. The oldest incomplete group is discarded when a 17th arrives. No
+clock reads occur:
+
+```python
+parser = AisParser.streaming()          # timeout_ms omitted → no timeout
+```
+
+**Auto clock** — the binding calls `time.monotonic_ns()` internally to
+drive the timeout. Use this when system time is reliable and you do not
+need deterministic replay:
+
+```python
+parser = AisParser.streaming(timeout_ms=60_000)          # clock="auto" implied
+# or explicitly:
+parser = AisParser.streaming(timeout_ms=60_000, clock="auto")
+```
+
+**Manual clock** — the caller drives the clock via `tick(now_ms=...)`. No
+clock reads occur inside the binding. This is the correct mode for unit
+tests, simulators, and any environment where `time` is patched:
+
+```python
+parser = AisParser.streaming(timeout_ms=60_000, clock="manual")
+
+parser.feed(fragment_bytes)
+parser.tick(now_ms=current_time_ms)     # expire stale groups at this instant
+for msg in parser:
+    ...
+```
+
+Calling `tick()` on a parser that wasn't built with `clock="manual"` raises
+`ValueError` — including parsers built with no `timeout_ms` (which default to
+`clock="auto"`).
+
+## Errors
+
+Every exception is a `MarlinError` subclass (importable from `marlin`):
+
+- `EnvelopeError` — framing or checksum failure
+- `DecodeError` — field-level decode failure in a typed NMEA sentence
+- `AisError` — AIS armor or bit-level decode failure
+- `ReassemblyError` — fragment reassembly violation (out-of-order, channel
+  mismatch, or timeout eviction)
+
+Property tests (via Hypothesis) verify panic-freedom on arbitrary byte
+inputs — no input can cause the binding to crash the interpreter.
+
+## Examples
+
+Six runnable scripts live in `bindings/python/examples/`:
+
+| Script | What it shows |
+| --- | --- |
+| `one_shot_no_crlf.py` | Single-datagram framing without `\r\n` (`OneShotParser`) |
+| `parse_log_file.py` | Disk-backed `.nmea` log replay (`StreamingParser`) |
+| `streaming_tcp_style.py` | TCP-style chunked feed; sentences straddle `feed()` boundaries |
+| `decode_aivdm_log.py` | Multi-fragment AIS reassembly: Type 1 + Type 5 |
+| `parse_stdin.py` | Stdin pipe reader for live NMEA/AIS capture |
+| `live_ais_dashboard.py` | Live ship tracker: envelope + AIS in one script, periodic refresh |
+
+## Type stubs
+
+The `py.typed` marker is included in the package. Every public class,
+function, and constant has a `.pyi` stub. Downstream projects that run
+`mypy --strict` get full type-check coverage without extra configuration.
+
+## Rust crates
+
+The Python bindings wrap three Rust crates:
+[`marlin-nmea-envelope`](../../crates/marlin-nmea-envelope),
+[`marlin-nmea-0183`](../../crates/marlin-nmea-0183),
+[`marlin-ais`](../../crates/marlin-ais).
+
+## MSRV / Python version
+
+Rust 1.82. Python 3.9+.
+
+## License
+
+Dual-licensed under MIT OR Apache-2.0.

marlin_py-0.1.0/bindings/python/.gitignore

@@ -0,0 +1,15 @@
+# Binding-local build artifacts. The crate is excluded from the workspace,
+# so it gets its own Cargo.lock — treat it the same way fuzz/ does.
+Cargo.lock
+
+# uv's dev-env lockfile — downstream users install pre-built wheels, so this
+# only pins the local pytest/maturin environment. Same library-vs-binary
+# rationale as Cargo.lock above.
+uv.lock
+
+# Python bytecode + extension modules built in-place by `maturin develop`.
+__pycache__/
+.pytest_cache/
+*.pyc
+*.so
+*.abi3.so

marlin_py-0.1.0/bindings/python/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to `marlin-py` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-04-28
+
+### Added
+
+- Initial release of `marlin-py` — Python bindings for the Marlin Rust suite
+  (envelope framing, NMEA 0183 typed decoders, AIS typed decoders + reassembly)
+- Synchronous parsers: `OneShotParser`, `StreamingParser` (envelope),
+  `Nmea0183Parser` (NMEA), `AisParser` (AIS) — all with iterator protocol
+- Context manager support (`with parser as p: ...`) on every parser
+- Async iterator helpers in `marlin.aio`: `aiter_sentences`,
+  `aiter_nmea_messages`, `aiter_ais_messages` for `asyncio.StreamReader`
+  integration
+- Frozen dataclass mirrors in `marlin.dataclasses` with `to_dataclass(msg)`
+  dispatcher — JSON / msgspec / dataclasses-asdict friendly
+- Three AIS clock modes (no-timeout / auto / manual) with deterministic-replay
+  guarantee on `clock="manual"`
+- Six runnable examples under `bindings/python/examples/`
+- Type stubs (`py.typed` + `.pyi` files) for full mypy --strict coverage
+- CI workflow: wheel builds for Linux x86_64/aarch64, macOS universal2,
+  Windows x86_64; pytest + mypy strict; sdist
+- Hypothesis property tests verifying panic-freedom on arbitrary byte input