Skip to content

Commit 1b3d438

Browse files
bruno-f-cruzbruno-f-cruz
committed
Document methods
1 parent a890991 commit 1b3d438

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

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

85111
device = read_schema(filepath, include_common_registers)
86112
if base_path is None:
@@ -99,12 +125,39 @@ def from_file(
99125

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

109162
response = requests.get(url, timeout=timeout)
110163
text = response.text
@@ -125,11 +178,37 @@ def from_url(
125178

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

134213
device = read_schema(schema, include_common_registers)
135214
if base_path is None:
@@ -147,10 +226,32 @@ def from_str(
147226

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

155256
if base_path is None:
156257
base_path = Path(model.device).absolute().resolve()
@@ -167,10 +268,34 @@ def from_model(
167268

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

175300
path = Path(dataset).absolute().resolve()
176301
is_dir = os.path.isdir(path)

0 commit comments

Comments
 (0)