From 5006b9f466d706560f8599a1c84b5624ae79d466 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maciej=20D=C4=85browski?= Date: Sun, 8 Dec 2024 13:45:28 +0100 Subject: [PATCH] update docstrings --- uds/database/abstract_database.py | 14 ----- .../data_record/abstract_data_record.py | 43 ++++++++++++--- uds/database/services/abstract_service.py | 54 +++++++------------ 3 files changed, 54 insertions(+), 57 deletions(-) diff --git a/uds/database/abstract_database.py b/uds/database/abstract_database.py index 071dc4d..eb3bd90 100644 --- a/uds/database/abstract_database.py +++ b/uds/database/abstract_database.py @@ -34,20 +34,6 @@ def encode(self, :param sid: Service Identifier of a diagnostic message. :param data_records_values: Value for each Data Record that is part a service message. - Each type represent other data: - - - int type - raw value of a Data Record - - float type - physical value of a Data Record - - str type - text value of a Data Record - - iterable type - contains values for children Data Records - - dict type - values of children Data Records - - .. warning:: Providing physical value as float might sometime cause issues due - `floating-point precision `_. - The closest raw value would be evaluated and put into a payload. - - To avoid rounding, provide raw value (int type). - :raise TypeError: Provided SID value is neither int, RequestSID nor ResponseSID type. :raise ValueError: This database has no implementation for provided SID value. diff --git a/uds/database/data_record/abstract_data_record.py b/uds/database/data_record/abstract_data_record.py index 7822dff..2998812 100644 --- a/uds/database/data_record/abstract_data_record.py +++ b/uds/database/data_record/abstract_data_record.py @@ -5,22 +5,51 @@ from abc import ABC, abstractmethod from typing import Dict, Optional, Sequence, Tuple, TypedDict, Union + DataRecordValueAlias = Union[ int, # raw value - float, # physical value calculated through formula (the closest raw value would be encoded) - str, # carried text value + float, # physical value calculated through formula + str, # text (physical) value from either Text Table or Text encoding Dict[str, "DataRecordValueAlias"], # value of container's children - Sequence[Dict[str, "DataRecordValueAlias"]], # values for reoccurring container (or its children) + Sequence[Union[int, Dict[str, "DataRecordValueAlias"]]], # values for reoccurring container ] -"""Alias of Data Records' input value.""" +""" +Alias of Data Records' input value. + +Each type represent other data: + +- int type - raw value of a data record +- float type - physical value of a formula data record + + .. warning:: Providing physical value as float might sometime cause issues due + `floating-point precision `_. + The closest raw value would be evaluated and put into a payload. + + To avoid rounding, provide raw value (int type). -DataRecordPhysicalValueAlias =Union[ +- str type - text (physical) value of either text table or text data record +- dict type - values for children of a container data records +- sequence type - values for following occurrences of a container data record +""" + +DataRecordPhysicalValueAlias = Union[ int, # physical value is the same as raw value float, # physical value calculated through formula str, # decoded text value Tuple[Tuple["DecodedDataRecord", ...], ...] # decoded container value, each element is another record ] -"""Alias of Data Records' physical value.""" +""" +Alias of Data Records' physical value. + +Each type represent other data: + +- int type - physical value is the same as raw value +- float type - value received through formula calculation +- str type - text value received either through encoding (e.g. ASCII, UTF-8) + or mapping (each value has specific meaning) +- tuple type - one element for each container occurrence; each element is a tuple with values for children data records +""" + class DecodedDataRecord(TypedDict): """Structure of decoded Data Record.""" @@ -63,7 +92,7 @@ def max_raw_value(self): :return: Maximum value that can be represented by `length` bits. """ return (1 << self.length) - 1 - + @property # noqa: F841 @abstractmethod def is_reoccurring(self) -> bool: diff --git a/uds/database/services/abstract_service.py b/uds/database/services/abstract_service.py index a86a125..f09d46c 100644 --- a/uds/database/services/abstract_service.py +++ b/uds/database/services/abstract_service.py @@ -35,57 +35,39 @@ def decode(self, payload: RawBytesAlias) -> List[DecodedDataRecord]: """ def encode(self, sid: int, **data_records_values: DataRecordValueAlias) -> RawBytesListAlias: - # TODO + """ + Encode diagnostic message payload for this service. + + :param sid: Value of Service Identifier. It should be either equal to either `request_sid` or `response_sid`. + :param data_records_values: Value for each data record that is part of a service message. + + :raise ValueError: Provided `sid` value is neither equal to request SID value nor response SID value for this + diagnostic service. + + :return: Payload of a diagnostic message. + """ if sid == self.request_sid: return self.encode_request(**data_records_values) if sid == self.response_sid: return self.encode_response(**data_records_values) - raise ValueError + raise ValueError("Provided SID value is neither request or response SID value for this service.") @abstractmethod def encode_request(self, **data_records_values: DataRecordValueAlias) -> RawBytesListAlias: """ - Encode diagnostic message payload from data records values. - - :param data_records_values: Value for each Data Record that is part a service message. - - Each type represent other data: + Encode diagnostic message payload for this service's request message. - - int type - raw value of a Data Record - - float type - physical value of a Data Record - - str type - text value of a Data Record - - sequence - contains values for children Data Records - - dict type - values of children Data Records + :param data_records_values: Value for each data record that is part of a service message. - .. warning:: Providing physical value as float might sometime cause issues due - `floating-point precision `_. - The closest raw value would be evaluated and put into a payload. - - To avoid rounding, provide raw value (int type). - - :return: Payload of a diagnostic message. + :return: Payload of a request diagnostic message. """ @abstractmethod def encode_response(self, **data_records_values: DataRecordValueAlias) -> RawBytesListAlias: """ - Encode diagnostic message payload from data records values. - - :param data_records_values: Value for each Data Record that is part a service message. + Encode diagnostic message payload for this service's response message. - Each type represent other data: + :param data_records_values: Value for each data record that is part of a service message. - - int type - raw value of a Data Record - - float type - physical value of a Data Record - - str type - text value of a Data Record - - sequence - contains values for children Data Records - - dict type - values of children Data Records - - .. warning:: Providing physical value as float might sometime cause issues due - `floating-point precision `_. - The closest raw value would be evaluated and put into a payload. - - To avoid rounding, provide raw value (int type). - - :return: Payload of a diagnostic message. + :return: Payload of a response diagnostic message. """