Skip to content

Commit 8fca619

Browse files
bruno-f-cruzbruno-f-cruz
committed
Document methods
1 parent 2c6082d commit 8fca619

1 file changed

Lines changed: 149 additions & 24 deletions

File tree

‎harp/reader.py‎

Lines changed: 149 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -80,11 +80,37 @@ def __getattr__(self, __name: str) -> RegisterReader:
8080

8181
@staticmethod
8282
def from_file(
83-
filepath: PathLike,
84-
base_path: Optional[PathLike] = None,
85-
include_common_registers: bool = True,
86-
epoch: Optional[datetime] = None,
87-
keep_type: bool = False) -> "DeviceReader":
83+
filepath: PathLike,
84+
base_path: Optional[PathLike] = None,
85+
include_common_registers: bool = True,
86+
epoch: Optional[datetime] = None,
87+
keep_type: bool = False,
88+
) -> "DeviceReader":
89+
"""Creates a device reader object from the specified schema yml file.
90+
91+
Parameters
92+
----------
93+
filepath
94+
A path to the device yml schema describing the device.
95+
base_path
96+
The path to attempt to resolve the location of data files.
97+
include_common_registers
98+
Specifies whether to include the set of Harp common registers in the
99+
parsed device schema object. If a parsed device schema object is provided,
100+
this parameter is ignored.
101+
epoch
102+
The default reference datetime at which time zero begins. If specified,
103+
the data frames returned by each register reader will have a datetime index.
104+
keep_type
105+
Specifies whether to include a column with the message type by default.
106+
107+
Returns
108+
-------
109+
A device reader object which can be used to read binary data for each
110+
register or to access metadata about each register. Individual registers
111+
can be accessed using dot notation using the name of the register as the
112+
key.
113+
"""
88114

89115
device = read_schema(filepath, include_common_registers)
90116
if base_path is None:
@@ -103,12 +129,39 @@ def from_file(
103129

104130
@staticmethod
105131
def from_url(
106-
url: str,
107-
base_path: Optional[PathLike] = None,
108-
include_common_registers: bool = True,
109-
epoch: Optional[datetime] = None,
110-
keep_type: bool = False,
111-
timeout: int = 5) -> "DeviceReader":
132+
url: str,
133+
base_path: Optional[PathLike] = None,
134+
include_common_registers: bool = True,
135+
epoch: Optional[datetime] = None,
136+
keep_type: bool = False,
137+
timeout: int = 5,
138+
) -> "DeviceReader":
139+
"""Creates a device reader object from a url pointing to a device.yml file.
140+
141+
Parameters
142+
----------
143+
url
144+
The url pointing to the device.yml schema describing the device.
145+
base_path
146+
The path to attempt to resolve the location of data files.
147+
include_common_registers
148+
Specifies whether to include the set of Harp common registers in the
149+
parsed device schema object. If a parsed device schema object is provided,
150+
this parameter is ignored.
151+
epoch
152+
The default reference datetime at which time zero begins. If specified,
153+
the data frames returned by each register reader will have a datetime index.
154+
keep_type
155+
Specifies whether to include a column with the message type by default.
156+
timeout
157+
The number of seconds to wait for the server to send data before giving up.
158+
Returns
159+
-------
160+
A device reader object which can be used to read binary data for each
161+
register or to access metadata about each register. Individual registers
162+
can be accessed using dot notation using the name of the register as the
163+
key.
164+
"""
112165

113166
response = requests.get(url, timeout=timeout)
114167
text = response.text
@@ -129,11 +182,37 @@ def from_url(
129182

130183
@staticmethod
131184
def from_str(
132-
schema: str,
133-
base_path: Optional[PathLike] = None,
134-
include_common_registers: bool = True,
135-
epoch: Optional[datetime] = None,
136-
keep_type: bool = False) -> "DeviceReader":
185+
schema: str,
186+
base_path: Optional[PathLike] = None,
187+
include_common_registers: bool = True,
188+
epoch: Optional[datetime] = None,
189+
keep_type: bool = False,
190+
) -> "DeviceReader":
191+
"""Creates a device reader object from a string containing a device.yml schema.
192+
193+
Parameters
194+
----------
195+
schema
196+
The string containing the device.yml schema describing the device.
197+
base_path
198+
The path to attempt to resolve the location of data files.
199+
include_common_registers
200+
Specifies whether to include the set of Harp common registers in the
201+
parsed device schema object. If a parsed device schema object is provided,
202+
this parameter is ignored.
203+
epoch
204+
The default reference datetime at which time zero begins. If specified,
205+
the data frames returned by each register reader will have a datetime index.
206+
keep_type
207+
Specifies whether to include a column with the message type by default.
208+
209+
Returns
210+
-------
211+
A device reader object which can be used to read binary data for each
212+
register or to access metadata about each register. Individual registers
213+
can be accessed using dot notation using the name of the register as the
214+
key.
215+
"""
137216

138217
device = read_schema(schema, include_common_registers)
139218
if base_path is None:
@@ -151,10 +230,32 @@ def from_str(
151230

152231
@staticmethod
153232
def from_model(
154-
model: Model,
155-
base_path: Optional[PathLike] = None,
156-
epoch: Optional[datetime] = None,
157-
keep_type: bool = False) -> "DeviceReader":
233+
model: Model,
234+
base_path: Optional[PathLike] = None,
235+
epoch: Optional[datetime] = None,
236+
keep_type: bool = False,
237+
) -> "DeviceReader":
238+
"""Creates a device reader object from a parsed device schema object.
239+
240+
Parameters
241+
----------
242+
model
243+
The parsed device schema object describing the device.
244+
base_path
245+
The path to attempt to resolve the location of data files.
246+
epoch
247+
The default reference datetime at which time zero begins. If specified,
248+
the data frames returned by each register reader will have a datetime index.
249+
keep_type
250+
Specifies whether to include a column with the message type by default.
251+
252+
Returns
253+
-------
254+
A device reader object which can be used to read binary data for each
255+
register or to access metadata about each register. Individual registers
256+
can be accessed using dot notation using the name of the register as the
257+
key.
258+
"""
158259

159260
if base_path is None:
160261
base_path = Path(model.device).absolute().resolve()
@@ -171,10 +272,34 @@ def from_model(
171272

172273
@staticmethod
173274
def from_dataset(
174-
dataset: PathLike,
175-
include_common_registers: bool = True,
176-
epoch: Optional[datetime] = None,
177-
keep_type: bool = False) -> "DeviceReader":
275+
dataset: PathLike,
276+
include_common_registers: bool = True,
277+
epoch: Optional[datetime] = None,
278+
keep_type: bool = False,
279+
) -> "DeviceReader":
280+
"""Creates a device reader object from the specified dataset folder.
281+
282+
Parameters
283+
----------
284+
dataset
285+
A path to the dataset folder containing a device.yml schema describing the device.
286+
include_common_registers
287+
Specifies whether to include the set of Harp common registers in the
288+
parsed device schema object. If a parsed device schema object is provided,
289+
this parameter is ignored.
290+
epoch
291+
The default reference datetime at which time zero begins. If specified,
292+
the data frames returned by each register reader will have a datetime index.
293+
keep_type
294+
Specifies whether to include a column with the message type by default.
295+
296+
Returns
297+
-------
298+
A device reader object which can be used to read binary data for each
299+
register or to access metadata about each register. Individual registers
300+
can be accessed using dot notation using the name of the register as the
301+
key.
302+
"""
178303

179304
path = Path(dataset).absolute().resolve()
180305
is_dir = os.path.isdir(path)

0 commit comments

Comments
 (0)