Python Capture I/O API — Reader / Writer¶

Convert and write a block of samples.

Takes complex64 at unit scale and emits it in the writer's wire type. Call as many times as you like; the capture is the concatenation.

Parameters:

Returns:

Examples:

>>> import pathlib, tempfile
>>> from doppler.wfm import Composer, Reader, Segment, Writer
>>> tmp = tempfile.TemporaryDirectory()
>>> p = pathlib.Path(tmp.name) / "capture.blue"
>>> x = Composer([Segment("qpsk", sps=8, num_samples=1024)]).compose()
>>> with Writer(p, file_type="blue", sample_type="ci16",
...             fs=2.4e6, fc=1.2e9) as w:
...     w.write(x)
1024
>>> r = Reader(p)
>>> r.fs, r.fc, r.num_samples
(2400000.0, 1200000000.0, 1024)
>>> r.close()
>>> tmp.cleanup()   # directory and contents removed

Make every sample written so far durable and observable to a concurrent reader, without ending the capture. Leaves the file on a sample boundary, which is what lets a follower read it without meeting a partial sample. Raises OSError if this or any earlier write failed; a capture is not finished until close().

Leaves the file on a sample boundary -- write() emits whole samples, so a flush BETWEEN write calls is what lets a follower read the capture without meeting a partial one. Raises OSError if this or any earlier write failed; a capture is not complete until close().

Raises:

Examples:

>>> import pathlib, tempfile
>>> import numpy as np
>>> from doppler.wfm import Reader, Writer
>>> tmp = tempfile.TemporaryDirectory()
>>> p = pathlib.Path(tmp.name) / "live.blue"
>>> w = Writer(p, file_type="blue", sample_type="ci16", fs=2.4e6)
>>> _ = w.write(np.zeros(16, dtype=np.complex64))
>>> w.flush()                    # the samples are on disk now
>>> Reader(p).read_follow(16).size
16
>>> w.close()
>>> tmp.cleanup()

Enable the per-component clip counter (off by default; peak is always on).

Parameters:

Attach a BLUE extended-header keyword (BLUE captures only). type is a single character (B/I/L/X int, F/D float, A string, T deprecated int); value is a str for A, a single int/float, or a sequence of them. Keywords are buffered and written at close(). The read side is Reader.keywords.

Release the underlying C resources immediately.

Ordinarily unnecessary: the resources are freed when the object is garbage-collected. Call this to release them at a definite point instead, or use the object as a context manager, which calls it on exit.

Idempotent: calling it again on an already-released object does nothing. Every other method raises RuntimeError once it has run.

Raises:

Release the underlying C resources immediately.

Ordinarily unnecessary: the resources are freed when the object is garbage-collected. Call this to release them at a definite point instead, or use the object as a context manager, which calls it on exit.

Idempotent: calling it again on an already-released object does nothing. Every other method raises RuntimeError once it has run.

Raises:

Enter a context manager, returning this object.

Lets a Writer be used in a with statement so its C resources are released deterministically on exit rather than at collection time.

Returns:

Exit a context manager, releasing the Writer.

Equivalent to calling close(). Returns None, so an exception raised inside the with body propagates normally; this never suppresses one.

Parameters:

Raises:

Rewind to the first sample of the capture.

seek() at index 0, and nothing else — one implementation of "put the read position at sample k" rather than two that can drift. It lands where the payload starts (512 bytes into an attached BLUE file, byte 0 of a .det or a raw/SigMF payload), so the capture reads again from the top. The file's metadata and decoded keywords are unaffected: they came from the header and do not change.

Read up to count samples, returning them as complex64.

Samples come out at unit scale whatever the wire type was: a float type is reinterpreted, an integer type is divided by its full scale. Returns fewer than asked at the end of the capture, and 0 once it is exhausted, so a while over the result terminates. Never returns more than the file's declared payload — trailing bytes past data_size (an extended header, X-Midas slack) are not samples.

Parameters:

Returns:

Examples:

>>> import pathlib, tempfile
>>> from doppler.wfm import Composer, Reader, Segment, Writer
>>> tmp = tempfile.TemporaryDirectory()
>>> p = pathlib.Path(tmp.name) / "capture.blue"
>>> x = Composer([Segment("qpsk", sps=8, num_samples=1024)]).compose()
>>> with Writer(p, file_type="blue", sample_type="ci16",
...             fs=2.4e6, fc=1.2e9) as w:
...     _ = w.write(x)
>>> r = Reader(p)
>>> r.file_type, r.sample_type, r.endian
('blue', 'ci16', 'le')
>>> r.fs, r.fc, r.fc_source
(2400000.0, 1200000000.0, 'FREQ')
>>> total = 0
>>> while len(block := r.read(256)):
...     total += len(block)
>>> total
1024
>>> r.close()
>>> tmp.cleanup()   # directory and contents removed

Maximum samples one read(n) yields: n (fewer at EOF).

A reader streams, so a read of n produces at most n samples; the binding

sizes its buffer to this per-call bound (gh-607) and resizes down to the

actual count, never pre-allocating the whole capture.

Parameters:

Returns:

Read whatever whole samples have arrived in a capture that is still being written, blocking until at least one does. Unlike read(), a short or empty result does not mean end-of-file: the reader waits. 0 means wait forever for both budgets, which is the default and the right answer for a stream with no end -- any finite budget fires during an ordinary quiet patch. An empty result therefore means the capture ENDED; read ending for which way. timeout_ms bounds the wait for data; grace_ms bounds how long to keep waiting for the writer's marker after a stop has been requested, and expiring it may cost you the tail. Never consumes a partial sample, so a writer flushing mid-sample cannot desynchronise the stream.

Blocks until whole samples arrive. A short or empty result does not mean end-of-file the way ::wfm_reader_read's does -- the reader waits. Zero means the capture ENDED, because with the default unbounded budgets the call does not come back for "not yet"; ::wfm_reader_get_ending says which way it ended.

Parameters:

Returns:

Examples:

>>> import pathlib, tempfile
>>> import numpy as np
>>> from doppler.wfm import Reader, Writer
>>> tmp = tempfile.TemporaryDirectory()
>>> p = pathlib.Path(tmp.name) / "capture.blue"
>>> x = np.zeros(8, dtype=np.complex64)
>>> with Writer(p, file_type="blue", sample_type="ci16", fs=2.4e6) as w:
...     _ = w.write(x)
>>> r = Reader(p)
>>> total = 0
>>> while len(block := r.read_follow(4)):   # 0 only when the capture ends
...     total += len(block)
>>> total, r.ending
(8, 'eof')
>>> r.close()
>>> tmp.cleanup()

Largest number of samples read_follow() can return for n inputs.

Size an out= buffer with this before calling read_follow(), or use it to allocate one up front. The bound is this object's own: what it depends on is a property of the algorithm, so a header block on read_follow_max_out() replaces this text.

Parameters:

Returns:

Move the read position to sample index.

Random access, in the timebase the data owns. The index is absolute — 0 is the first sample, there is no whence — and it is in SAMPLES, which is the only unit every container can answer: fs is 0.0 on a headerless capture, so a time would mean nothing there — see seek_time(), which refuses rather than pretend.

Cost follows the container. Raw, BLUE and SigMF are strided, so this is one fseek to data_start + index * bytes_per_sample. CSV is delimited rather than strided and has no byte arithmetic at all, so it is a scan: forward from the current position when seeking forward, from the first sample when seeking back. A loop that seeks forward monotonically therefore walks the file once, not once per seek.

Seeking to num_samples exactly is legal and lands at the end, where read() returns 0. Past it is refused, as is a negative index: that is a caller's arithmetic gone wrong, and a silent empty read would hide it. A refused seek does not move the read position — the bound is checked before anything moves, and the CSV scan puts the position back if it runs out.

On a capture still being written, the bound is what is on disk right now, measured at the call. A BLUE capture whose writer has not closed yet still carries the placeholder data_size it opened with, so its declared length is not used until the writer patches it in; read_follow() is the read that works on such a capture, and seeking does not change that.

Parameters:

Raises:

Examples:

>>> import pathlib, tempfile
>>> import numpy as np
>>> from doppler.wfm import Composer, Reader, Segment, Writer
>>> tmp = tempfile.TemporaryDirectory()
>>> p = pathlib.Path(tmp.name) / "capture.blue"
>>> x = Composer([Segment("qpsk", sps=8, num_samples=1024)]).compose()
>>> w = Writer(p, file_type="blue", sample_type="cf32", fs=2.4e6)
>>> _ = w.write(x)
>>> w.close()
>>> r = Reader(p)
>>> r.seek(600)                  # straight there, no decode first
>>> np.array_equal(r.read(424), x[600:])
True
>>> r.position                      # the read left us at the end
1024
>>> try:                            # past the end is a refusal...
...     r.seek(1025)
... except ValueError:
...     print("refused")
refused
>>> r.position                      # ...that did not move us
1024
>>> r.close()
>>> tmp.cleanup()

Move the read position to seconds into the capture.

seek() over index = round(seconds * fs), and the rounding is to nearest. The conversion is the whole method; the REFUSAL is the point of having it.

A capture that declares no sample rate reports fs == 0.0, and that is raw and CSV always — neither container has anywhere to record one. A caller computing round(t * r.fs) for itself gets sample 0 for every time, silently. So this refuses when fs_source says nothing declared a rate, rather than convert through one — the same reason the provenance accessors exist at all.

Seconds are measured from the FIRST SAMPLE of the capture, never from the UNIX epoch. A capture's absolute start is t0, and t0_source is none on every capture doppler itself writes — so an absolute face would be unusable by default. Converting is the caller's, and it is r.seek_time(t_unix - r.t0) once t0_source says there is a t0 to subtract.

Parameters:

Raises:

Examples:

>>> import pathlib, tempfile
>>> import numpy as np
>>> from doppler.wfm import Composer, Reader, Segment, Writer
>>> tmp = tempfile.TemporaryDirectory()
>>> p = pathlib.Path(tmp.name) / "capture.blue"
>>> x = Composer([Segment("qpsk", sps=8, num_samples=1024)]).compose()
>>> w = Writer(p, file_type="blue", sample_type="cf32", fs=1e6)
>>> _ = w.write(x)
>>> w.close()
>>> r = Reader(p)
>>> r.fs, r.fs_source            # the rate it converts through
(1000000.0, 'xdelta')
>>> r.seek_time(250e-6)             # 250 us at 1 MHz is sample 250
>>> r.position
250
>>> np.array_equal(r.read(774), x[250:])
True
>>> r.close()
>>> raw = pathlib.Path(tmp.name) / "capture.raw"
>>> w = Writer(raw, 0.0, file_type="raw", sample_type="cf32",
...            sidecar=False)   # no sidecar: nothing records a rate
>>> _ = w.write(x)
>>> w.close()
>>> h = Reader(raw, sample_type="cf32")
>>> h.fs, h.fs_source            # headerless: no rate declared
(0.0, 'none')
>>> try:                            # so a time cannot mean anything
...     h.seek_time(250e-6)
... except ValueError:
...     print("refused")
refused
>>> h.seek(250)                  # ...the sample index still does
>>> h.position
250
>>> h.close()
>>> tmp.cleanup()

Release the underlying C resources immediately.

Ordinarily unnecessary: the resources are freed when the object is garbage-collected. Call this to release them at a definite point instead, or use the object as a context manager, which calls it on exit.

Idempotent: calling it again on an already-released object does nothing. Every other method raises RuntimeError once it has run.

Release the underlying C resources immediately.

Ordinarily unnecessary: the resources are freed when the object is garbage-collected. Call this to release them at a definite point instead, or use the object as a context manager, which calls it on exit.

Idempotent: calling it again on an already-released object does nothing. Every other method raises RuntimeError once it has run.

Enter a context manager, returning this object.

Lets a Reader be used in a with statement so its C resources are released deterministically on exit rather than at collection time.

Returns:

Exit a context manager, releasing the Reader.

Equivalent to calling close(). Returns None, so an exception raised inside the with body propagates normally; this never suppresses one.

Parameters: