Skip to content

Commit ceaa56d

Browse files
bruno-f-cruzbruno-f-cruz
committed
Document methods
1 parent 7662754 commit ceaa56d

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
@@ -78,11 +78,37 @@ def __getattr__(self, __name: str) -> RegisterReader:
7878

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

87113
device = read_schema(filepath, include_common_registers)
88114
if base_path is None:
@@ -101,12 +127,39 @@ def from_file(
101127

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

111164
response = requests.get(url, timeout=timeout)
112165
text = response.text
@@ -127,11 +180,37 @@ def from_url(
127180

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

136215
device = read_schema(schema, include_common_registers)
137216
if base_path is None:
@@ -149,10 +228,32 @@ def from_str(
149228

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

157258
if base_path is None:
158259
base_path = Path(model.device).absolute().resolve()
@@ -169,10 +270,34 @@ def from_model(
169270

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

177302
path = Path(dataset).absolute().resolve()
178303
is_dir = os.path.isdir(path)

0 commit comments

Comments
 (0)