From 9375160b348a03d2c0bdb31f5012ae07198f1db6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20=C5=A0imbera?= Date: Sat, 7 Nov 2020 12:55:16 +0100 Subject: [PATCH] documentation for measure and persist modules --- docs/api.rst | 4 ++-- docs/api_docs/api_measure.rst | 5 +++++ docs/api_docs/api_persist.rst | 6 ++++++ votelib/persist.py | 13 +++++++++++++ 4 files changed, 26 insertions(+), 2 deletions(-) create mode 100644 docs/api_docs/api_measure.rst create mode 100644 docs/api_docs/api_persist.rst diff --git a/docs/api.rst b/docs/api.rst index 396647d..8f6e51b 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -11,8 +11,8 @@ Votelib API reference api_docs/api_evaluate api_docs/api_convert + api_docs/api_measure api_docs/api_candidate api_docs/api_vote api_docs/api_component - - + api_docs/api_persist diff --git a/docs/api_docs/api_measure.rst b/docs/api_docs/api_measure.rst new file mode 100644 index 0000000..223be20 --- /dev/null +++ b/docs/api_docs/api_measure.rst @@ -0,0 +1,5 @@ +Election result measurements +--------------------------------------------------------- + +.. automodule:: votelib.measure + :members: diff --git a/docs/api_docs/api_persist.rst b/docs/api_docs/api_persist.rst new file mode 100644 index 0000000..9f085c2 --- /dev/null +++ b/docs/api_docs/api_persist.rst @@ -0,0 +1,6 @@ +Persistence of election evaluators and other objects +--------------------------------------------------------- + +.. autofunction:: votelib.persist.from_dict + +.. autofunction:: votelib.persist.to_dict diff --git a/votelib/persist.py b/votelib/persist.py index 53f6f88..29af170 100644 --- a/votelib/persist.py +++ b/votelib/persist.py @@ -18,6 +18,8 @@ def simple_serialization(class_: type) -> type: to the class's constructor parameter names. Therefore, this decorator is only useful when the class stores all its original parameters unchanged (or in any other form acceptable to its constructor). + + :param class_: The class to add the method to. ''' if hasattr(class_, 'serialize_params'): param_names = class_.serialize_params @@ -135,6 +137,10 @@ def get_object(identifier: str) -> Any: def from_dict(value: Dict[str, Any]) -> Any: + """Parse an election evaluator object from a JSON-like dictionary. + + :param value: A dictionary created by :func:`to_dict`. + """ if not isinstance(value, dict): raise ValueError('invalid votelib object def: dict expected,' f'got {value!r}') @@ -148,6 +154,13 @@ def from_dict(value: Dict[str, Any]) -> Any: def to_dict(obj: Any) -> Dict[str, Any]: + """Serialize an election evaluator object to a JSON-ready dictionary. + + :param obj: An election evaluator object or similar. It should provide + a `to_dict()` method (all the standard evaluators, converters and the + like from Votelib should have it, courtesy of the simple_serialization + decorator). + """ return serialize_value(obj)