Skip to content

Commit 028a57f

Browse files
Expose and improve the docstrings of export_od and import_id (#473)
Resolves #472 * Expose and improve the docstrings of export_od and import_id * export_od(od, None, doctype) does not return a string; it writes to stdout * Clarify 'doc_type' details * Add exception info
1 parent d141e13 commit 028a57f

File tree

2 files changed

+30
-13
lines changed

2 files changed

+30
-13
lines changed

canopen/objectdictionary/__init__.py

+26-13
Original file line numberDiff line numberDiff line change
@@ -15,18 +15,27 @@
1515
logger = logging.getLogger(__name__)
1616

1717

18-
def export_od(od, dest: Union[str, TextIO, None] = None, doc_type: Optional[str] = None):
19-
""" Export :class: ObjectDictionary to a file.
18+
def export_od(
19+
od: ObjectDictionary,
20+
dest: Union[str, TextIO, None] = None,
21+
doc_type: Optional[str] = None
22+
) -> None:
23+
"""Export an object dictionary.
2024
2125
:param od:
22-
:class: ObjectDictionary object to be exported
26+
The object dictionary to be exported.
2327
:param dest:
24-
export destination. filename, or file-like object or None.
25-
if None, the document is returned as string
26-
:param doc_type: type of document to export.
27-
If a filename is given for dest, this default to the file extension.
28-
Otherwise, this defaults to "eds"
29-
:rtype: str or None
28+
The export destination as a filename, a file-like object, or ``None``.
29+
If ``None``, the document is written to :data:`sys.stdout`.
30+
:param doc_type:
31+
The type of document to export.
32+
If *dest* is a file-like object or ``None``,
33+
*doc_type* must be explicitly provided.
34+
If *dest* is a filename and its extension is ``.eds`` or ``.dcf``,
35+
*doc_type* defaults to that extension (the preceeding dot excluded);
36+
else, it defaults to ``eds``.
37+
:raises ValueError:
38+
When exporting to an unknown format.
3039
"""
3140

3241
opened_here = False
@@ -68,10 +77,14 @@ def import_od(
6877
"""Parse an EDS, DCF, or EPF file.
6978
7079
:param source:
71-
Path to object dictionary file or a file like object or an EPF XML tree.
72-
73-
:return:
74-
An Object Dictionary instance.
80+
The path to object dictionary file, a file like object, or an EPF XML tree.
81+
:param node_id:
82+
For EDS and DCF files, the node ID to use.
83+
For other formats, this parameter is ignored.
84+
:raises ObjectDictionaryError:
85+
For object dictionary errors and inconsistencies.
86+
:raises ValueError:
87+
When passed a file of an unknown format.
7588
"""
7689
if source is None:
7790
return ObjectDictionary()

doc/od.rst

+4
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,10 @@ You can access the objects using either index/subindex or names::
5454
API
5555
---
5656

57+
.. autofunction:: canopen.export_od
58+
59+
.. autofunction:: canopen.import_od
60+
5761
.. autoclass:: canopen.ObjectDictionary
5862
:members:
5963

0 commit comments

Comments
 (0)