python-aaronia 0.6.2__tar.gz → 0.7.1__tar.gz

{python_aaronia-0.6.2 → python_aaronia-0.7.1}/CHANGELOG.md

@@ -4,6 +4,73 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [v0.7.1] - 2026-08-12
+
+### Fixed
+- **The published macOS SoapySDR module would not load, on any Mac.**
+  `dlopen` failed with "symbol not found in flat namespace" for a Rust
+  vtable entry. CMake links module targets on macOS with
+  `-undefined dynamic_lookup`, and the Apple linker emitted a
+  flat-namespace bind for a symbol it had already localised into the
+  same image. The module now resolves its symbols at link time, so this
+  is a build failure rather than something a user meets on first run.
+  Every 0.5.x, 0.6.x and 0.7.0 macOS archive is affected; the Linux and
+  Windows modules are not.
+- **The packaged module's load check ran on Linux only**, which is why
+  the above shipped. It now runs on all three platforms at release
+  time, and CI builds and checks the plugin on macOS as well as Linux.
+
+### Documentation
+- The Linux module needs glibc 2.38 or later, so it does not load on
+  Ubuntu 22.04 or Debian 12. Said so in the plugin README.
+
+## [v0.7.0] - 2026-08-12
+
+### Added
+- **`aaronia.open()`, block iteration and context-manager support in
+  Python.** The shortest working program is now three lines. `open()`
+  takes the URL, frequency and either an exact `rate` or the
+  `bandwidth` you want covered, connects, and starts streaming;
+  `for block in src.blocks(65536)` ends when the source runs out
+  instead of raising; and `with` stops the stream even when the body
+  fails, raising a failed teardown only if the body itself succeeded.
+  The old config-object path is unchanged and still the way to reach
+  every option.
+- **`aaronia-doctor`, a command that checks an RTSA server.** It reports
+  whether the server answers, whether the mission has an input carrying
+  IQ, and what rate the device is running, and prints the fix for each
+  failure. The same checks are available as `aaronia.diagnose(url)`,
+  which returns `(ok, message, fix)` tuples, bounded at 20 seconds so a
+  stalled server cannot leave it waiting. Every failure it names is one
+  that otherwise shows up as a timeout with no explanation.
+- **`aaronia.sample_rates()` and `aaronia.sample_rate_for_bandwidth()`**,
+  exposing the crate's rate ladder to Python so a program can ask for a
+  rate the hardware will actually run.
+- **`Error::StreamClosed`**, separating "the stream ended" from "a read
+  failed". Both used to arrive as `Error::Protocol`, so a consumer
+  could not tell a capture that finished from one that was cut short.
+  Rust code matching on `Error::Protocol` for the closed-stream case
+  needs the new variant instead; the enum is `#[non_exhaustive]`, so
+  existing wildcard arms keep compiling. In Python the matching
+  exception is `AaroniaStreamClosed`, a subclass of
+  `AaroniaConnectionError`, so existing handlers are unaffected. It is
+  what lets `blocks()` end a loop on a finished stream while still
+  raising on a timeout or a transport failure, which would otherwise
+  make a truncated capture look like one that simply ran out.
+- **An installer in every SoapySDR release archive.** `install.sh`
+  (`install.ps1` on Windows) finds SoapySDR's module directory, clears
+  the macOS quarantine flag, copies the module in, and confirms it
+  loads. It prints instructions rather than guessing when SoapySDR is
+  missing.
+- **A Homebrew formula for the SoapySDR plugin**, in
+  `packaging/homebrew`. The release workflow renders it against the
+  published archives, checksums included, and attaches it to the
+  release, so updating a tap is a copy.
+
+### Fixed
+- The SoapySDR application guide still listed the old invented sample
+  rates for GQRX. It now describes the real ladder.
+
 ## [v0.6.2] - 2026-08-12
 
 ## [v0.6.1] - 2026-08-12

{python_aaronia-0.6.2 → python_aaronia-0.7.1}/Cargo.lock

@@ -3027,7 +3027,7 @@ dependencies = [
 
 [[package]]
 name = "python-aaronia"
-version = "0.6.2"
+version = "0.7.1"
 dependencies = [
  "arrow",
  "num-complex",
@@ -3556,7 +3556,7 @@ checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
 
 [[package]]
 name = "sdr-aaronia-rs"
-version = "0.6.2"
+version = "0.7.1"
 dependencies = [
  "anyhow",
  "bitflags 2.13.1",

{python_aaronia-0.6.2 → python_aaronia-0.7.1}/Cargo.toml

@@ -2,7 +2,7 @@
 name = "sdr-aaronia-rs"
 description = "Unified Rust interface for Aaronia Spectran Spectrum Analyzers / SDRs, featuring Python bindings, a SoapySDR plugin, HTTP streaming, and native SDK support."
 license = "GPL-3.0-or-later"
-version = "0.6.2"
+version = "0.7.1"
 edition = "2024"
 repository = "https://github.com/isaacbentley/sdr-aaronia-rs"
 readme = "README.md"

{python_aaronia-0.6.2 → python_aaronia-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aaronia
-Version: 0.6.2
+Version: 0.7.1
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
@@ -40,37 +40,66 @@ cd python-aaronia
 maturin develop --release
 ```
 
+Check your setup before writing any code:
+
+```bash
+aaronia-doctor http://localhost:54664
+```
+
+It reports whether the server is reachable, whether the mission has an
+input carrying IQ, and what rate the device is running, and names the
+fix for each failure.
+
 ## Quickstart
 
 ```python
 import aaronia
 
-cfg = aaronia.AaroniaConfig()
-cfg.http_base_url = "http://localhost:54664"  # RTSA-Suite HTTP server block
-cfg.center_freq = 2.44e9                      # Hz
-cfg.sample_rate = 15.36e6                     # Hz
-cfg.format = "F32"                            # wire format: F32, F16, or I16
+with aaronia.open("http://localhost:54664", freq=2.44e9, bandwidth=10e6) as src:
+    for block in src.blocks(65536):           # numpy complex64 arrays
+        process(block)
+```
+
+`aaronia.open()` connects and starts streaming in one call. `bandwidth`
+asks for that much usable spectrum and picks a sample rate the hardware
+can actually run; pass `rate=` instead to name one exactly. Use
+`file="capture.rtsa"` in place of the URL to play back a recording.
 
-src = aaronia.AaroniaSource()
-src.start_streaming(cfg)
+Iterating with `blocks()` ends when the stream closes. To read on your
+own schedule, or for Apache Arrow:
 
+```python
+src = aaronia.open(freq=2.44e9, rate=15.36e6, format="I16")
 samples = src.read_samples_numpy(65536)       # numpy complex64 array
 batch = src.read_samples_arrow(65536)         # pyarrow FixedSizeListArray of [re, im]
-
 src.set_center_frequency(2.41e9)              # live retune, no teardown
-
 print(src.cumulative_drops(), src.take_overrun(), src.last_timestamp_ns())
 src.stop_streaming()
 ```
 
-File playback: set `cfg.file_path = "capture.rtsa"` instead of
-`http_base_url`.
+For full control, build an `AaroniaConfig` and pass it to
+`AaroniaSource.start_streaming()`; `open()` is a shorthand for the
+common fields.
 
 The
 [quickstart](https://github.com/isaacbentley/sdr-aaronia-rs/blob/main/docs/QUICKSTART.md)
 covers configuring the RTSA-Suite HTTP Server block, which everything
 above depends on.
 
+## Sample rates
+
+The device runs a fixed ladder of rates: 61.44 MHz halved down to
+120 kHz. Ask for anything else and it quietly uses the nearest rung,
+leaving your program computing against a rate that is not in use.
+
+```python
+aaronia.sample_rates()                  # every rate, highest first
+aaronia.sample_rate_for_bandwidth(8e6)  # 15.36e6: the lowest rate covering 8 MHz
+```
+
+A rate carries only 80% of itself as alias-free bandwidth, which is why
+8 MHz of spectrum needs 15.36 MHz of sampling.
+
 ## Configuration (`AaroniaConfig`)
 
 Every field is readable and writable.
@@ -107,11 +136,14 @@ silently defaulting.
   enabled, which is the default. The reader reopens the stream,
   re-applies the current tuning, and flags the first read after the gap
   through `take_overrun()`. After five failed attempts the stream ends
-  and reads raise `AaroniaConnectionError`.
+  and reads raise `AaroniaStreamClosed`.
 - **Typed exceptions.** `AaroniaConnectionError` (unreachable endpoint),
   `AaroniaTimeoutError`, `AaroniaHardwareError` (device and SDK errors)
   and `ValueError` (invalid configuration), mapped from the Rust error
   enum with the full cause chain in the message.
+  `AaroniaStreamClosed` subclasses `AaroniaConnectionError` and means
+  the stream finished rather than failed; `blocks()` ends on it, while
+  a timeout or transport failure still raises.
 - **Dual-channel** reads (`receiver_channel = "Rx1And2"` with
   `read_samples_dual_numpy(count)`, returning two time-aligned arrays)
   require the native-SDK backend: Windows or Linux with the Aaronia SDK
@@ -123,6 +155,8 @@ silently defaulting.
 | Method | Purpose |
 | --- | --- |
 | `start_streaming(cfg)` / `stop_streaming()` | Session lifecycle |
+| `with src: ...` | Stops streaming on the way out, including after an exception |
+| `blocks(count)` | Iterate `count`-sample arrays until the stream closes |
 | `read_samples_numpy(count)` | NumPy `complex64` array |
 | `read_samples_arrow(count)` | PyArrow `FixedSizeListArray` of `[re, im]` float32 pairs |
 | `read_samples_dual_numpy(count)` | `(rx1, rx2)` NumPy arrays (dual-channel captures) |
@@ -131,3 +165,12 @@ silently defaulting.
 | `take_overrun()` | True once per detected receive-side overrun |
 | `last_timestamp_ns()` | Epoch-ns timestamp of the last received block (HTTP backend; 0 otherwise) |
 
+## Module functions
+
+| Function | Purpose |
+| --- | --- |
+| `open(url=None, *, freq, rate, bandwidth, ref_level, file, format, read_timeout)` | Configure, connect and start streaming in one call |
+| `sample_rates()` | Every sample rate the hardware can run |
+| `sample_rate_for_bandwidth(hz)` | Lowest rate covering that much spectrum |
+| `diagnose(url)` | `(ok, message, fix)` for each setup check; what `aaronia-doctor` prints |
+

{python_aaronia-0.6.2 → python_aaronia-0.7.1}/README.md

@@ -102,21 +102,17 @@ pip install python-aaronia
 ```python
 import aaronia
 
-cfg = aaronia.AaroniaConfig()
-cfg.http_base_url = "http://localhost:54664"
-cfg.center_freq = 2.44e9
-cfg.sample_rate = 15.36e6
-
-src = aaronia.AaroniaSource()
-src.start_streaming(cfg)
-samples = src.read_samples_numpy(65536)   # numpy complex64
-src.stop_streaming()
+with aaronia.open("http://localhost:54664", freq=2.44e9, bandwidth=10e6) as src:
+    for block in src.blocks(65536):   # numpy complex64 arrays
+        process(block)
 ```
 
 Reads land in NumPy or PyArrow with one copy out of the receive buffer.
 Blocking calls release the GIL, errors arrive as typed exceptions, and
 the package ships type stubs. Wheels are abi3 for CPython 3.9 and
-later. Full reference: [python-aaronia/README.md](python-aaronia/README.md).
+later. The bundled `aaronia-doctor` command checks a server and names
+the fix for whatever is wrong. Full reference:
+[python-aaronia/README.md](python-aaronia/README.md).
 
 ### SoapySDR: GQRX, SDR++, GNU Radio and others
 

{python_aaronia-0.6.2 → python_aaronia-0.7.1}/docs/APPS.md

@@ -1,14 +1,20 @@
 # Using a SPECTRAN from existing SDR applications
 
 Any SoapySDR-capable application can drive a SPECTRAN through the
-[`soapy-aaronia`](../soapy-aaronia/README.md) plugin. Install the plugin
-first. Prebuilt binaries are attached to each release. Confirm it is
-visible:
+[`soapy-aaronia`](../soapy-aaronia/README.md) plugin. Install it first:
+download the archive for your platform from a
+[release](https://github.com/isaacbentley/sdr-aaronia-rs/releases),
+unpack it, and run the bundled installer (`./install.sh`, or
+`.\install.ps1` in PowerShell on Windows). It finds SoapySDR's module
+directory, copies the plugin in, and confirms it loads:
 
 ```bash
 SoapySDRUtil --check=aaronia
 ```
 
+The [plugin README](../soapy-aaronia/README.md#install-a-prebuilt-module)
+covers installing by hand and building from source.
+
 Every application below uses the same device string. In most cases the
 RTSA-Suite HTTP server URL is the only argument needed:
 
@@ -43,11 +49,10 @@ GQRX accepts a device string directly in its configuration dialog:
 driver=aaronia,url=http://localhost:54664
 ```
 
-Select the sample rate from GQRX's list. The plugin advertises 250 kHz,
-500 kHz, 1, 2, 5, 10, 15.36, 20, 30.72 and 61.44 MHz for applications
-that build dropdowns from `listSampleRates`. Rates within the reported
-range also work over HTTP, so a rate absent from the list is not
-necessarily unsupported.
+Select the sample rate from GQRX's list. The plugin advertises the
+device's real ladder: 61.44 MHz halved down to 120 kHz, which the RTSA
+GUI labels Full through 1/512. The hardware produces no other rate, so a
+request in between snaps to the nearest rung and logs a warning.
 
 The single gain element is `REF`, the Aaronia reference level in dBm. It
 is not an amplifier gain: raising it reduces sensitivity. Start near

{python_aaronia-0.6.2 → python_aaronia-0.7.1}/docs/QUICKSTART.md

@@ -86,30 +86,39 @@ cargo run --example http_iq_quickstart --features http -- 2440e6 15.36e6 http://
 pip install python-aaronia
 ```
 
+Check the server first. The command ships with the package and reports
+what is wrong, and how to fix it:
+
+```bash
+aaronia-doctor http://localhost:54664
+```
+
 ```python
 import aaronia
 
-cfg = aaronia.AaroniaConfig()
-cfg.http_base_url = "http://localhost:54664"
-cfg.center_freq = 2.44e9
-cfg.sample_rate = 15.36e6
-
-src = aaronia.AaroniaSource()
-src.start_streaming(cfg)
-samples = src.read_samples_numpy(65536)   # numpy complex64
-print(samples[:4], src.cumulative_drops())
-src.stop_streaming()
+with aaronia.open("http://localhost:54664", freq=2.44e9, bandwidth=10e6) as src:
+    samples = src.read_samples_numpy(65536)   # numpy complex64
+    print(samples[:4], src.cumulative_drops())
 ```
 
+`bandwidth` picks a sample rate the hardware can run. Pass `rate=` to
+name one exactly, or build an `AaroniaConfig` for the full set of
+options.
+
 ### SoapySDR
 
+Download the plugin archive for your platform from a
+[release](https://github.com/isaacbentley/sdr-aaronia-rs/releases),
+unpack it, and run the bundled installer:
+
 ```bash
+./install.sh
 SoapySDRUtil --probe="driver=aaronia,url=http://localhost:54664"
 ```
 
 [APPS.md](APPS.md) covers GQRX, SDR++ and GNU Radio.
 [../soapy-aaronia/README.md](../soapy-aaronia/README.md) covers
-installing the plugin.
+installing by hand and building from source.
 
 ## 4. Troubleshooting
 

python_aaronia-0.7.1/packaging/homebrew/README.md

@@ -0,0 +1,43 @@
+# Homebrew tap
+
+`soapy-aaronia.rb` installs the prebuilt SoapySDR plugin from a GitHub
+release. It is kept here so it is versioned alongside the code it
+installs, and published from a tap repository.
+
+## One-time setup
+
+Create a public repository named `homebrew-tap` under the same owner as
+this one. The name is fixed: Homebrew maps `owner/tap` to
+`github.com/owner/homebrew-tap`. Add the formula as
+`Formula/soapy-aaronia.rb`.
+
+Users then install with:
+
+```bash
+brew install isaacbentley/tap/soapy-aaronia
+```
+
+Homebrew pulls in SoapySDR, drops the module into
+`lib/SoapySDR/modules0.8`, and its `brew test` step confirms
+`SoapySDRUtil --check=aaronia` reports the driver as present.
+
+## Each release
+
+The release workflow renders this file against the published archives
+and attaches the result to the release as `soapy-aaronia.rb`, with the
+version and both SHA-256 checksums filled in. Copy that file into the
+tap repository as `Formula/soapy-aaronia.rb` and commit. Nothing needs
+hashing by hand.
+
+Before pushing, `brew audit --strict --online soapy-aaronia` checks the
+formula, and `brew install --build-from-source` proves it works.
+
+## Coverage
+
+The formula covers macOS on Apple silicon and Linux on x86-64, matching
+the platforms the release builds. Elsewhere, `brew` has nothing to
+install and the plugin has to be built from source; see
+[soapy-aaronia/README.md](../../soapy-aaronia/README.md).
+
+The module directory is pinned to `modules0.8`, which is SoapySDR's ABI
+0.8 path. A future SoapySDR ABI bump requires changing that line.

python_aaronia-0.7.1/packaging/homebrew/soapy-aaronia.rb

@@ -0,0 +1,47 @@
+# Homebrew formula for the Aaronia SoapySDR plugin.
+#
+# Lives here so it is versioned with the code it installs. To publish it,
+# copy this file into a tap repository named homebrew-tap, as
+# Formula/soapy-aaronia.rb, and users get:
+#
+#     brew install <owner>/tap/soapy-aaronia
+#
+# At each release, update `version`, both `sha256` values (from the
+# release archives) and nothing else. `brew audit --strict soapy-aaronia`
+# checks the formula before publishing.
+class SoapyAaronia < Formula
+  desc "SoapySDR plugin for Aaronia SPECTRAN V6 spectrum analyzers"
+  homepage "https://github.com/isaacbentley/sdr-aaronia-rs"
+  version "0.7.1"
+  license "GPL-3.0-or-later"
+
+  # Prebuilt modules: the plugin statically links its Rust core, so there
+  # is nothing to build here and no Rust toolchain to depend on.
+  on_macos do
+    on_arm do
+      url "https://github.com/isaacbentley/sdr-aaronia-rs/releases/download/v#{version}/SoapyAaronia-#{version}-macos-arm64.tar.gz"
+      sha256 "REPLACE_WITH_SHA256_OF_MACOS_ARM64_ARCHIVE"
+    end
+  end
+
+  on_linux do
+    on_intel do
+      url "https://github.com/isaacbentley/sdr-aaronia-rs/releases/download/v#{version}/SoapyAaronia-#{version}-linux-x86_64.tar.gz"
+      sha256 "REPLACE_WITH_SHA256_OF_LINUX_X86_64_ARCHIVE"
+    end
+  end
+
+  depends_on "soapysdr"
+
+  def install
+    # SoapySDR loads modules from a versioned directory under its own
+    # prefix; Homebrew links this into place for us.
+    (lib/"SoapySDR/modules0.8").install "libaaroniaSupport.so"
+    doc.install "INSTALL.md"
+  end
+
+  test do
+    # Proves the module loads into SoapySDR rather than merely existing.
+    assert_match "aaronia", shell_output("#{Formula["soapysdr"].bin}/SoapySDRUtil --check=aaronia")
+  end
+end

{python_aaronia-0.6.2 → python_aaronia-0.7.1}/pyproject.toml

@@ -18,6 +18,11 @@ classifiers = [
 # Version comes from python-aaronia/Cargo.toml (single source of truth).
 dynamic = ["version"]
 
+# A real command, so checking a setup needs no code:
+#   aaronia-doctor http://localhost:54664
+[project.scripts]
+aaronia-doctor = "aaronia:doctor_cli"
+
 [project.urls]
 Repository = "https://github.com/isaacbentley/sdr-aaronia-rs"
 Changelog = "https://github.com/isaacbentley/sdr-aaronia-rs/blob/main/CHANGELOG.md"

{python_aaronia-0.6.2 → python_aaronia-0.7.1}/python-aaronia/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "python-aaronia"
-version = "0.6.2"
+version = "0.7.1"
 edition = "2024"
 description = "Python bindings for sdr-aaronia-rs (Aaronia SPECTRAN V6 SDR source)"
 license = "GPL-3.0-or-later"

{python_aaronia-0.6.2 → python_aaronia-0.7.1}/python-aaronia/README.md

@@ -25,37 +25,66 @@ cd python-aaronia
 maturin develop --release
 ```
 
+Check your setup before writing any code:
+
+```bash
+aaronia-doctor http://localhost:54664
+```
+
+It reports whether the server is reachable, whether the mission has an
+input carrying IQ, and what rate the device is running, and names the
+fix for each failure.
+
 ## Quickstart
 
 ```python
 import aaronia
 
-cfg = aaronia.AaroniaConfig()
-cfg.http_base_url = "http://localhost:54664"  # RTSA-Suite HTTP server block
-cfg.center_freq = 2.44e9                      # Hz
-cfg.sample_rate = 15.36e6                     # Hz
-cfg.format = "F32"                            # wire format: F32, F16, or I16
+with aaronia.open("http://localhost:54664", freq=2.44e9, bandwidth=10e6) as src:
+    for block in src.blocks(65536):           # numpy complex64 arrays
+        process(block)
+```
+
+`aaronia.open()` connects and starts streaming in one call. `bandwidth`
+asks for that much usable spectrum and picks a sample rate the hardware
+can actually run; pass `rate=` instead to name one exactly. Use
+`file="capture.rtsa"` in place of the URL to play back a recording.
 
-src = aaronia.AaroniaSource()
-src.start_streaming(cfg)
+Iterating with `blocks()` ends when the stream closes. To read on your
+own schedule, or for Apache Arrow:
 
+```python
+src = aaronia.open(freq=2.44e9, rate=15.36e6, format="I16")
 samples = src.read_samples_numpy(65536)       # numpy complex64 array
 batch = src.read_samples_arrow(65536)         # pyarrow FixedSizeListArray of [re, im]
-
 src.set_center_frequency(2.41e9)              # live retune, no teardown
-
 print(src.cumulative_drops(), src.take_overrun(), src.last_timestamp_ns())
 src.stop_streaming()
 ```
 
-File playback: set `cfg.file_path = "capture.rtsa"` instead of
-`http_base_url`.
+For full control, build an `AaroniaConfig` and pass it to
+`AaroniaSource.start_streaming()`; `open()` is a shorthand for the
+common fields.
 
 The
 [quickstart](https://github.com/isaacbentley/sdr-aaronia-rs/blob/main/docs/QUICKSTART.md)
 covers configuring the RTSA-Suite HTTP Server block, which everything
 above depends on.
 
+## Sample rates
+
+The device runs a fixed ladder of rates: 61.44 MHz halved down to
+120 kHz. Ask for anything else and it quietly uses the nearest rung,
+leaving your program computing against a rate that is not in use.
+
+```python
+aaronia.sample_rates()                  # every rate, highest first
+aaronia.sample_rate_for_bandwidth(8e6)  # 15.36e6: the lowest rate covering 8 MHz
+```
+
+A rate carries only 80% of itself as alias-free bandwidth, which is why
+8 MHz of spectrum needs 15.36 MHz of sampling.
+
 ## Configuration (`AaroniaConfig`)
 
 Every field is readable and writable.
@@ -92,11 +121,14 @@ silently defaulting.
   enabled, which is the default. The reader reopens the stream,
   re-applies the current tuning, and flags the first read after the gap
   through `take_overrun()`. After five failed attempts the stream ends
-  and reads raise `AaroniaConnectionError`.
+  and reads raise `AaroniaStreamClosed`.
 - **Typed exceptions.** `AaroniaConnectionError` (unreachable endpoint),
   `AaroniaTimeoutError`, `AaroniaHardwareError` (device and SDK errors)
   and `ValueError` (invalid configuration), mapped from the Rust error
   enum with the full cause chain in the message.
+  `AaroniaStreamClosed` subclasses `AaroniaConnectionError` and means
+  the stream finished rather than failed; `blocks()` ends on it, while
+  a timeout or transport failure still raises.
 - **Dual-channel** reads (`receiver_channel = "Rx1And2"` with
   `read_samples_dual_numpy(count)`, returning two time-aligned arrays)
   require the native-SDK backend: Windows or Linux with the Aaronia SDK
@@ -108,6 +140,8 @@ silently defaulting.
 | Method | Purpose |
 | --- | --- |
 | `start_streaming(cfg)` / `stop_streaming()` | Session lifecycle |
+| `with src: ...` | Stops streaming on the way out, including after an exception |
+| `blocks(count)` | Iterate `count`-sample arrays until the stream closes |
 | `read_samples_numpy(count)` | NumPy `complex64` array |
 | `read_samples_arrow(count)` | PyArrow `FixedSizeListArray` of `[re, im]` float32 pairs |
 | `read_samples_dual_numpy(count)` | `(rx1, rx2)` NumPy arrays (dual-channel captures) |
@@ -115,3 +149,12 @@ silently defaulting.
 | `cumulative_drops()` | Total server-reported dropped samples |
 | `take_overrun()` | True once per detected receive-side overrun |
 | `last_timestamp_ns()` | Epoch-ns timestamp of the last received block (HTTP backend; 0 otherwise) |
+
+## Module functions
+
+| Function | Purpose |
+| --- | --- |
+| `open(url=None, *, freq, rate, bandwidth, ref_level, file, format, read_timeout)` | Configure, connect and start streaming in one call |
+| `sample_rates()` | Every sample rate the hardware can run |
+| `sample_rate_for_bandwidth(hz)` | Lowest rate covering that much spectrum |
+| `diagnose(url)` | `(ok, message, fix)` for each setup check; what `aaronia-doctor` prints |