Skip to content

Commit 2d0fb83

Browse files
Teque5Teque5
committed
fix docstring & blacken-docs on RST
1 parent 1435246 commit 2d0fb83

5 files changed

Lines changed: 96 additions & 68 deletions

File tree

‎docs/source/advanced.rst‎

Lines changed: 50 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ the recording of the SigMF logo used in this example `from the specification
1818
from sigmf import SigMFFile, sigmffile
1919
2020
# Load a dataset
21-
path = 'logo/sigmf_logo' # extension is optional
21+
path = "logo/sigmf_logo" # extension is optional
2222
signal = sigmffile.fromfile(path)
2323
2424
# Get some metadata and all annotations
@@ -31,13 +31,15 @@ the recording of the SigMF logo used in this example `from the specification
3131
for adx, annotation in enumerate(annotations):
3232
annotation_start_idx = annotation[SigMFFile.START_INDEX_KEY]
3333
annotation_length = annotation[SigMFFile.LENGTH_INDEX_KEY]
34-
annotation_comment = annotation.get(SigMFFile.COMMENT_KEY, "[annotation {}]".format(adx))
34+
annotation_comment = annotation.get(
35+
SigMFFile.COMMENT_KEY, "[annotation {}]".format(adx)
36+
)
3537
3638
# Get capture info associated with the start of annotation
3739
capture = signal.get_capture_info(annotation_start_idx)
3840
freq_center = capture.get(SigMFFile.FREQUENCY_KEY, 0)
39-
freq_min = freq_center - 0.5*sample_rate
40-
freq_max = freq_center + 0.5*sample_rate
41+
freq_min = freq_center - 0.5 * sample_rate
42+
freq_max = freq_center + 0.5 * sample_rate
4143
4244
# Get frequency edges of annotation (default to edges of capture)
4345
freq_start = annotation.get(SigMFFile.FLO_KEY)
@@ -66,34 +68,41 @@ First, create a single SigMF Recording and save it to disk:
6668
data = np.zeros(1024, dtype=np.complex64)
6769
6870
# write those samples to file in cf32_le
69-
data.tofile('example_cf32.sigmf-data')
71+
data.tofile("example_cf32.sigmf-data")
7072
7173
# create the metadata
7274
meta = SigMFFile(
73-
data_file='example_cf32.sigmf-data', # extension is optional
74-
global_info = {
75+
data_file="example_cf32.sigmf-data", # extension is optional
76+
global_info={
7577
SigMFFile.DATATYPE_KEY: get_data_type_str(data), # in this case, 'cf32_le'
7678
SigMFFile.SAMPLE_RATE_KEY: 48000,
77-
SigMFFile.AUTHOR_KEY: 'jane.doe@domain.org',
78-
SigMFFile.DESCRIPTION_KEY: 'All zero complex float32 example file.',
79-
}
79+
SigMFFile.AUTHOR_KEY: "jane.doe@domain.org",
80+
SigMFFile.DESCRIPTION_KEY: "All zero complex float32 example file.",
81+
},
8082
)
8183
8284
# create a capture key at time index 0
83-
meta.add_capture(0, metadata={
84-
SigMFFile.FREQUENCY_KEY: 915000000,
85-
SigMFFile.DATETIME_KEY: get_sigmf_iso8601_datetime_now(),
86-
})
85+
meta.add_capture(
86+
0,
87+
metadata={
88+
SigMFFile.FREQUENCY_KEY: 915000000,
89+
SigMFFile.DATETIME_KEY: get_sigmf_iso8601_datetime_now(),
90+
},
91+
)
8792
8893
# add an annotation at sample 100 with length 200 & 10 KHz width
89-
meta.add_annotation(100, 200, metadata = {
90-
SigMFFile.FLO_KEY: 914995000.0,
91-
SigMFFile.FHI_KEY: 915005000.0,
92-
SigMFFile.COMMENT_KEY: 'example annotation',
93-
})
94+
meta.add_annotation(
95+
100,
96+
200,
97+
metadata={
98+
SigMFFile.FLO_KEY: 914995000.0,
99+
SigMFFile.FHI_KEY: 915005000.0,
100+
SigMFFile.COMMENT_KEY: "example annotation",
101+
},
102+
)
94103
95104
# check for mistakes & write to disk
96-
meta.tofile('example_cf32.sigmf-meta') # extension is optional
105+
meta.tofile("example_cf32.sigmf-meta") # extension is optional
97106
98107
Now lets add another SigMF Recording and associate them with a SigMF Collection:
99108

@@ -103,41 +112,44 @@ Now lets add another SigMF Recording and associate them with a SigMF Collection:
103112
104113
data_ci16 = np.zeros(1024, dtype=np.complex64)
105114
106-
#rescale and save as a complex int16 file:
115+
# rescale and save as a complex int16 file:
107116
data_ci16 *= pow(2, 15)
108-
data_ci16.view(np.float32).astype(np.int16).tofile('example_ci16.sigmf-data')
117+
data_ci16.view(np.float32).astype(np.int16).tofile("example_ci16.sigmf-data")
109118
110119
# create the metadata for the second file
111120
meta_ci16 = SigMFFile(
112-
data_file='example_ci16.sigmf-data', # extension is optional
113-
global_info = {
114-
SigMFFile.DATATYPE_KEY: 'ci16_le', # get_data_type_str() is only valid for numpy types
121+
data_file="example_ci16.sigmf-data", # extension is optional
122+
global_info={
123+
SigMFFile.DATATYPE_KEY: "ci16_le", # get_data_type_str() is only valid for numpy types
115124
SigMFFile.SAMPLE_RATE_KEY: 48000,
116-
SigMFFile.DESCRIPTION_KEY: 'All zero complex int16 file.',
117-
}
125+
SigMFFile.DESCRIPTION_KEY: "All zero complex int16 file.",
126+
},
118127
)
119128
meta_ci16.add_capture(0, metadata=meta.get_capture_info(0))
120-
meta_ci16.tofile('example_ci16.sigmf-meta')
121-
122-
collection = SigMFCollection(['example_cf32.sigmf-meta', 'example_ci16.sigmf-meta'],
123-
metadata = {'collection': {
124-
SigMFCollection.AUTHOR_KEY: 'sigmf@sigmf.org',
125-
SigMFCollection.DESCRIPTION_KEY: 'Collection of two all zero files.',
129+
meta_ci16.tofile("example_ci16.sigmf-meta")
130+
131+
collection = SigMFCollection(
132+
["example_cf32.sigmf-meta", "example_ci16.sigmf-meta"],
133+
metadata={
134+
"collection": {
135+
SigMFCollection.AUTHOR_KEY: "sigmf@sigmf.org",
136+
SigMFCollection.DESCRIPTION_KEY: "Collection of two all zero files.",
126137
}
127-
}
138+
},
128139
)
129140
streams = collection.get_stream_names()
130141
sigmf = [collection.get_SigMFFile(stream) for stream in streams]
131-
collection.tofile('example_zeros.sigmf-collection')
142+
collection.tofile("example_zeros.sigmf-collection")
132143
133144
The SigMF Collection and its associated Recordings can now be loaded like this:
134145

135146
.. code-block:: python
136147
137148
import sigmf
138-
collection = sigmf.fromfile('example_zeros')
139-
ci16_sigmffile = collection.get_SigMFFile(stream_name='example_ci16')
140-
cf32_sigmffile = collection.get_SigMFFile(stream_name='example_cf32')
149+
150+
collection = sigmf.fromfile("example_zeros")
151+
ci16_sigmffile = collection.get_SigMFFile(stream_name="example_ci16")
152+
cf32_sigmffile = collection.get_SigMFFile(stream_name="example_cf32")
141153
142154
-----------------------------------------------
143155
Load a SigMF Archive and slice without untaring

‎docs/source/converters.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,8 +29,8 @@ formats and reads without writing any output files:
2929
3030
# auto-detect and create NCD for any supported format
3131
meta = sigmf.fromfile("recording.cdif") # BLUE file
32-
meta = sigmf.fromfile("recording.wav") # WAV file
33-
meta = sigmf.fromfile("recording.xml") # Signal Hound Spike file
32+
meta = sigmf.fromfile("recording.wav") # WAV file
33+
meta = sigmf.fromfile("recording.xml") # Signal Hound Spike file
3434
meta = sigmf.fromfile("recording.sigmf") # SigMF archive
3535
3636
all_samples = meta.read_samples()

‎docs/source/quickstart.rst‎

Lines changed: 27 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -23,15 +23,16 @@ Read a SigMF Recording
2323
.. code-block:: python
2424
2525
import sigmf
26+
2627
handle = sigmf.fromfile("example.sigmf")
2728
# reading data
28-
handle.read_samples() # read all timeseries data
29-
handle[10:50] # read memory slice of samples 10 through 50
29+
handle.read_samples() # read all timeseries data
30+
handle[10:50] # read memory slice of samples 10 through 50
3031
# accessing metadata
31-
handle.sample_rate # get sample rate attribute
32-
handle.get_global_info() # returns 'global' dictionary
33-
handle.get_captures() # returns list of 'captures' dictionaries
34-
handle.get_annotations() # returns list of all annotations
32+
handle.sample_rate # get sample rate attribute
33+
handle.get_global_info() # returns 'global' dictionary
34+
handle.get_captures() # returns list of 'captures' dictionaries
35+
handle.get_annotations() # returns list of all annotations
3536
3637
-----------------------------------
3738
Verify SigMF Integrity & Compliance
@@ -88,30 +89,37 @@ For full control over global fields, captures, and annotations:
8889
8990
# create the metadata
9091
meta = SigMFFile(
91-
data_file="example.sigmf-data", # extension is optional
92-
global_info = {
92+
data_file="example.sigmf-data", # extension is optional
93+
global_info={
9394
SigMFFile.DATATYPE_KEY: get_data_type_str(data), # in this case, "cf32_le"
9495
SigMFFile.SAMPLE_RATE_KEY: 48000,
9596
SigMFFile.AUTHOR_KEY: "jane.doe@domain.org",
9697
SigMFFile.DESCRIPTION_KEY: "All zero complex float32 example file.",
97-
}
98+
},
9899
)
99100
100101
# create a capture key at time index 0
101-
meta.add_capture(0, metadata={
102-
SigMFFile.FREQUENCY_KEY: 915000000,
103-
SigMFFile.DATETIME_KEY: get_sigmf_iso8601_datetime_now(),
104-
})
102+
meta.add_capture(
103+
0,
104+
metadata={
105+
SigMFFile.FREQUENCY_KEY: 915000000,
106+
SigMFFile.DATETIME_KEY: get_sigmf_iso8601_datetime_now(),
107+
},
108+
)
105109
106110
# add an annotation at sample 100 with length 200 & 10 KHz width
107-
meta.add_annotation(100, 200, metadata = {
108-
SigMFFile.FLO_KEY: 914995000.0,
109-
SigMFFile.FHI_KEY: 915005000.0,
110-
SigMFFile.COMMENT_KEY: "example annotation",
111-
})
111+
meta.add_annotation(
112+
100,
113+
200,
114+
metadata={
115+
SigMFFile.FLO_KEY: 914995000.0,
116+
SigMFFile.FHI_KEY: 915005000.0,
117+
SigMFFile.COMMENT_KEY: "example annotation",
118+
},
119+
)
112120
113121
# validate & write to disk
114-
meta.tofile("example.sigmf-meta") # extension is optional
122+
meta.tofile("example.sigmf-meta") # extension is optional
115123
116124
----------------------------------
117125
Attribute Access for Global Fields

‎docs/source/siggen.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -64,8 +64,8 @@ A seed ensures reproducibility across runs.
6464
signal = SigMFGenerator(seed=0xDEADBEEF).generate()
6565
6666
# the number and type of components are randomly chosen
67-
print(signal.description) # e.g. "synthetic signal with 3 tones and 2 sweeps"
68-
print(signal.get_annotations()) # one annotation per component
67+
print(signal.description) # e.g. "synthetic signal with 3 tones and 2 sweeps"
68+
print(signal.get_annotations()) # one annotation per component
6969
7070
Without a seed, each call produces a different signal.
7171

‎sigmf/sigmffile.py‎

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -850,10 +850,15 @@ def tofile(self, file_path, pretty=True, toarchive=False, compression=None, skip
850850
851851
Examples
852852
--------
853-
>>> meta.tofile('recording') # creates recording.sigmf-meta
854-
>>> meta.tofile('recording.sigmf') # creates recording.sigmf (archive)
855-
>>> meta.tofile('recording.sigmf.gz') # creates recording.sigmf.gz (compressed)
856-
>>> meta.tofile('recording', compression='xz') # creates recording.sigmf.xz
853+
>>> from sigmf.siggen import SigMFGenerator
854+
>>> import tempfile
855+
>>> from pathlib import Path
856+
>>> meta = SigMFGenerator().generate()
857+
>>> tmpdir = Path(tempfile.mkdtemp())
858+
>>> meta.tofile(tmpdir / 'recording') # creates recording.sigmf-meta and recording.sigmf-data pair
859+
>>> meta.tofile(tmpdir / 'recording.sigmf') # creates recording.sigmf (archive)
860+
>>> meta.tofile(tmpdir / 'recording.sigmf.gz') # creates recording.sigmf.gz (compressed)
861+
>>> meta.tofile(tmpdir / 'other', compression='xz') # creates other.sigmf.xz
857862
"""
858863
if not skip_validate:
859864
self.validate()
@@ -1330,10 +1335,13 @@ def fromarray(data, sample_rate, frequency=None, global_info=None):
13301335
Examples
13311336
--------
13321337
>>> import numpy as np
1338+
>>> import tempfile
1339+
>>> from pathlib import Path
13331340
>>> data = np.random.randn(1000) + 1j * np.random.randn(1000)
1334-
>>> meta = fromarray(data, sample_rate=1e6, frequency=915e6)
1335-
>>> meta.tofile('recording') # creates recording.sigmf-meta and recording.sigmf-data
1336-
>>> meta.tofile('recording.sigmf') # creates recording.sigmf archive
1341+
>>> meta = fromarray(data, sample_rate=1e6, frequency=915e6) # returns SigMFFile
1342+
>>> tmpdir = Path(tempfile.mkdtemp())
1343+
>>> meta.tofile(tmpdir / 'recording') # creates recording.sigmf-meta and recording.sigmf-data
1344+
>>> meta.tofile(tmpdir / 'recording.sigmf') # creates recording.sigmf archive
13371345
"""
13381346
import io
13391347

0 commit comments

Comments
 (0)