From b2d7d92be71f599fda31d4debe1ed8877d54f0ba Mon Sep 17 00:00:00 2001 From: Igor Derkach Date: Sat, 26 Oct 2024 17:59:45 +0400 Subject: [PATCH] Fix func documentation --- pyzkaccess/cli.py | 4 +-- pyzkaccess/common.py | 4 +-- pyzkaccess/device.py | 4 +-- pyzkaccess/device_data/model.py | 42 ++++++++++++++++-------------- pyzkaccess/device_data/queryset.py | 8 +++--- pyzkaccess/door.py | 2 -- pyzkaccess/event.py | 8 +++--- pyzkaccess/main.py | 8 +++--- pyzkaccess/relay.py | 4 +-- pyzkaccess/sdk.py | 23 +++++++--------- 10 files changed, 51 insertions(+), 56 deletions(-) diff --git a/pyzkaccess/cli.py b/pyzkaccess/cli.py index cea9105..76ba714 100644 --- a/pyzkaccess/cli.py +++ b/pyzkaccess/cli.py @@ -1113,8 +1113,8 @@ def setup(self, *, yes: bool = False, path: str = None) -> None: It is recommended to run this command before using other commands. Args: - yes(bool): assume yes for all questions. Default is False - path(str): URL, path to zip or path to directory with PULL SDK dll files. + yes (bool): assume yes for all questions. Default is False + path (str): URL, path to zip or path to directory with PULL SDK dll files. """ sys.stdout.write("Setting up the environment...\n") setup(not yes, path) diff --git a/pyzkaccess/common.py b/pyzkaccess/common.py index e89c530..8ded69c 100644 --- a/pyzkaccess/common.py +++ b/pyzkaccess/common.py @@ -144,7 +144,7 @@ def __init__(self, value: _DocValueValueT, doc: str) -> None: """DocValue constructor Args: - value (DocValueT): value which was exposed by this object + value (_DocValueValueT): value which was exposed by this object doc (str): documentation string which will be put to __doc__ """ super().__init__(value) @@ -397,7 +397,7 @@ def zktimemoment_to_datetime(zktm: Union[str, int]) -> Optional[datetime]: integer or as number in string Returns: - datetime: decoded datetime object + Optional[datetime]: decoded datetime object """ if zktm in ("0", 0): return None diff --git a/pyzkaccess/device.py b/pyzkaccess/device.py index 6ea8f29..3d65009 100644 --- a/pyzkaccess/device.py +++ b/pyzkaccess/device.py @@ -154,8 +154,8 @@ def __init__(self, s: Optional[str] = None, **params: Any) -> None: attributes as params. Args: - s (Optional[str]): raw device string - **params: device attributes + s (str, optional): raw device string + **params (Any): device attributes Examples: >>> ZKDevice( diff --git a/pyzkaccess/device_data/model.py b/pyzkaccess/device_data/model.py index 8ff10e8..08ff78d 100644 --- a/pyzkaccess/device_data/model.py +++ b/pyzkaccess/device_data/model.py @@ -26,10 +26,10 @@ models_registry: MutableMapping[str, Type["Model"]] = {} -FieldDataT = TypeVar("FieldDataT") +_FieldDataT = TypeVar("_FieldDataT") -class Field(Generic[FieldDataT]): +class Field(Generic[_FieldDataT]): """This class is internal and used to define a field in data table model. @@ -40,16 +40,16 @@ class Field(Generic[FieldDataT]): """ @overload - def __init__(self, raw_name: str, field_datatype: Type[FieldDataT]): ... + def __init__(self, raw_name: str, field_datatype: Type[_FieldDataT]): ... @overload - def __init__(self, raw_name: str, field_datatype: Type[FieldDataT], get_cb: Optional[Callable[[str], Any]]): ... + def __init__(self, raw_name: str, field_datatype: Type[_FieldDataT], get_cb: Optional[Callable[[str], Any]]): ... @overload def __init__( self, raw_name: str, - field_datatype: Type[FieldDataT], + field_datatype: Type[_FieldDataT], get_cb: Optional[Callable[[str], Any]], set_cb: Optional[Callable[[Any], Any]], ): ... @@ -58,27 +58,26 @@ def __init__( def __init__( # pylint: disable=too-many-arguments self, raw_name: str, - field_datatype: Type[FieldDataT], + field_datatype: Type[_FieldDataT], get_cb: Optional[Callable[[str], Any]], set_cb: Optional[Callable[[Any], Any]], - validation_cb: Optional[Callable[[FieldDataT], bool]], + validation_cb: Optional[Callable[[_FieldDataT], bool]], ): ... def __init__( # pylint: disable=too-many-arguments self, raw_name: str, - field_datatype: Type[FieldDataT], + field_datatype: Type[_FieldDataT], get_cb: Optional[Callable[[str], Any]] = None, set_cb: Optional[Callable[[Any], Any]] = None, - validation_cb: Optional[Callable[[FieldDataT], bool]] = None, + validation_cb: Optional[Callable[[_FieldDataT], bool]] = None, ): """Construct a Model field. Args: raw_name (str): field name in device table which this field associated to - field_datatype (Type): type of data of this field. `str` by - default + field_datatype (Type[FieldDataT]): type of data of this field. get_cb (Callable[[str], Any], optional): callback that is called on field get before a raw string value will be converted to `field_datatype` @@ -93,7 +92,7 @@ def __init__( # pylint: disable=too-many-arguments """ self._raw_name = raw_name - self._field_datatype: Type[FieldDataT] = field_datatype + self._field_datatype: Type[_FieldDataT] = field_datatype self._get_cb = get_cb self._set_cb = set_cb self._validation_cb = validation_cb @@ -106,7 +105,7 @@ def raw_name(self) -> str: return self._raw_name @property - def field_datatype(self) -> Type[FieldDataT]: + def field_datatype(self) -> Type[_FieldDataT]: """Field data type""" return self._field_datatype @@ -139,7 +138,7 @@ def to_raw_value(self, value: Any) -> str: return str(value) - def to_field_value(self, value: str) -> Optional[FieldDataT]: + def to_field_value(self, value: str) -> Optional[_FieldDataT]: """Convert raw string value to a value of `field_datatype`. This function typically calls on field get. @@ -151,7 +150,7 @@ def to_field_value(self, value: str) -> Optional[FieldDataT]: value (str): raw string representation Returns: - value of `field_datatype` + Optional[_FieldDataT]: value of `field_datatype` """ new_value = value @@ -165,7 +164,7 @@ def to_field_value(self, value: str) -> Optional[FieldDataT]: def __hash__(self) -> int: return hash(self._raw_name) - def __get__(self, instance: Optional["Model"], _: Any) -> Optional[FieldDataT]: + def __get__(self, instance: Optional["Model"], _: Any) -> Optional[_FieldDataT]: """Model field getter. It does the following: 1. Retrieve raw field value of `raw_name`. If nothing then @@ -237,6 +236,9 @@ def __new__(mcs: Type["ModelMeta"], name: str, bases: tuple, attrs: dict) -> Any return klass +_ModelT = TypeVar("_ModelT", bound="Model") + + class Model(metaclass=ModelMeta): """Model base class. Derived classes must define fields and set table_name. @@ -269,7 +271,7 @@ def __init__(self, **fields: Any) -> None: } @property - def dict(self) -> Dict[str, FieldDataT]: + def dict(self) -> Dict[str, _FieldDataT]: return {field: getattr(self, field) for field in self._fields_mapping.keys()} @property @@ -312,16 +314,16 @@ def save(self) -> None: self._dirty = False - def with_raw_data(self, raw_data: MutableMapping[str, str], dirty: bool = True) -> "Model": + def with_raw_data(self: _ModelT, raw_data: MutableMapping[str, str], dirty: bool = True) -> _ModelT: self._raw_data = raw_data self._dirty = dirty return self - def with_sdk(self, sdk: "ZKSDK") -> "Model": + def with_sdk(self: _ModelT, sdk: "ZKSDK") -> _ModelT: self._sdk = sdk return self - def with_zk(self, zk: "ZKAccess") -> "Model": + def with_zk(self: _ModelT, zk: "ZKAccess") -> _ModelT: """Bind current object with ZKAccess connection Args: diff --git a/pyzkaccess/device_data/queryset.py b/pyzkaccess/device_data/queryset.py index 56526cb..1945afb 100644 --- a/pyzkaccess/device_data/queryset.py +++ b/pyzkaccess/device_data/queryset.py @@ -134,7 +134,7 @@ def where(self: _QuerySetT, **kwargs: Any) -> _QuerySetT: zk.table('User').where(card='123456').where(card='111', super_authorize=False) Args: - **kwargs (Any): field conditions + **kwargs (Any): field filters Returns: QuerySet: a copy of current object with filters @@ -162,8 +162,6 @@ def unread(self: _QuerySetT) -> _QuerySetT: Once a table is read, the pointer is moved to the last record. We use this to track the unread records. - Args: - Returns: QuerySet: a copy of current object with unread flag @@ -190,7 +188,7 @@ def upsert(self, records: Union[Iterable[RecordType], RecordType]) -> None: zk.table(User).upsert([User(pin='0', card='123456'), User(pin='1', card='654321')]) Args: - records (Union[Iterable[_ModelArgT], _ModelArgT]): record + records (Union[Iterable[RecordType], RecordType]): record dict, Model instance or a sequence of those """ if not isinstance(records, (Iterable, Model, Mapping)): @@ -213,7 +211,7 @@ def delete(self, records: Union[Iterable[RecordType], RecordType]) -> None: zk.table(User).delete([User(pin='0', card='123456'), User(pin='1', card='654321')]) Args: - records (Union[Sequence[_ModelArgT], _ModelArgT]): record + records (Union[Sequence[RecordType], RecordType]): record dict, Model instance or a sequence of those """ if not isinstance(records, (Iterable, Model, Mapping)): diff --git a/pyzkaccess/door.py b/pyzkaccess/door.py index d99337d..bc89854 100644 --- a/pyzkaccess/door.py +++ b/pyzkaccess/door.py @@ -17,8 +17,6 @@ def events(self) -> EventLog: """Event log of current door. This includes events of its relays, readers, aux inputs and so forth - Args: - Returns: EventLog: event log object """ diff --git a/pyzkaccess/event.py b/pyzkaccess/event.py index 1c30dd1..c4de474 100644 --- a/pyzkaccess/event.py +++ b/pyzkaccess/event.py @@ -4,7 +4,7 @@ from collections import deque from copy import deepcopy from datetime import datetime -from typing import Any, Iterable, Iterator, List, Optional, Sequence, TypeVar, Union +from typing import Any, Iterable, Iterator, List, Optional, TypeVar, Union from .common import DocValue, ZKDatetimeUtils from .enums import EVENT_TYPES, PassageDirection, VerifyMode @@ -43,14 +43,14 @@ def description(self) -> str: return msg @staticmethod - def parse(event_line: str) -> Sequence[str]: + def parse(event_line: str) -> List[str]: """Split a raw event string into parts Args: event_line (str): event string Returns: - Sequence[str]: parsed string parts of event string + List[str]: parsed string parts of event string """ event_line = event_line.replace("\r\n", "") @@ -203,7 +203,7 @@ def poll(self, timeout: float = 60, polling_interval: float = 1) -> List[Event]: in seconds Returns: - Iterable[Event]: events iterable with new events if any + List[Event]: events iterable with new events if any or empty iterable if timeout has expired """ diff --git a/pyzkaccess/main.py b/pyzkaccess/main.py index 4a432fa..86303e4 100644 --- a/pyzkaccess/main.py +++ b/pyzkaccess/main.py @@ -345,7 +345,7 @@ def search_devices( return tuple(ZKDevice(line) for line in devices) @classmethod - def change_ip( + def change_ip( # pylint: disable=missing-param-doc cls, mac_address: str, new_ip_address: str, @@ -378,11 +378,11 @@ def change_ip( Args: mac_address (str): device MAC address new_ip_address (str): new IP address to be set on a device - broadcast_address (str): broadcast + broadcast_address (str, default=255.255.255.255): broadcast network address - protocol (ChangeIPProtocol): a + protocol (ChangeIPProtocol, default=ChangeIPProtocol.udp): a protocol to use for sending broadcast packets - dllpath (str): path to a PULL + dllpath (str, default="plcommpro.dll"): path to a PULL SDK DLL """ sdk = pyzkaccess.sdk.ZKSDK(dllpath) diff --git a/pyzkaccess/relay.py b/pyzkaccess/relay.py index 5ef39c5..33bbe9c 100644 --- a/pyzkaccess/relay.py +++ b/pyzkaccess/relay.py @@ -107,7 +107,7 @@ def __getitem__(self: _RelayListT, item: Union[int, slice]) -> Union[Relay, _Rel return self.data[item] - def by_mask(self, mask: Iterable[Union[int, bool]]) -> "RelayList": + def by_mask(self, mask: Iterable[Any]) -> "RelayList": """Return only relays starting from 0 which are matched by given mask. E.g. for mask `[1, 0, 0, 1, 0, 0, 1, 0]` this function returns 1, 4 and 7 relays of all eight relays. @@ -122,7 +122,7 @@ def by_mask(self, mask: Iterable[Union[int, bool]]) -> "RelayList": of 8 relays, a mask `[1, 0, 0]` will return only relay 1. Args: - mask (Iterable[Union[int, bool]]): mask is a list of + mask (Iterable[Any]): mask is a list of ints or bools Returns: diff --git a/pyzkaccess/sdk.py b/pyzkaccess/sdk.py index 83e519c..f231b54 100644 --- a/pyzkaccess/sdk.py +++ b/pyzkaccess/sdk.py @@ -1,6 +1,6 @@ __all__ = ["ZKSDK"] -from typing import Any, Dict, Generator, Mapping, Optional, Sequence +from typing import Any, Dict, Generator, List, Mapping, Optional, Sequence import pyzkaccess.ctypes_ as ctypes @@ -87,7 +87,7 @@ def control_device( return err - def get_rt_log(self, buffer_size: int) -> Sequence[str]: + def get_rt_log(self, buffer_size: int) -> List[str]: """Retrieve unread realtime events from a device SDK: GetRTLog() @@ -97,7 +97,7 @@ def get_rt_log(self, buffer_size: int) -> Sequence[str]: with contents Returns: - Sequence[str]: event string lines + List[str]: event string lines Raises: ZKSDKError: on SDK error @@ -116,7 +116,7 @@ def get_rt_log(self, buffer_size: int) -> Sequence[str]: *lines, _ = raw.split("\r\n") return lines - def search_device(self, broadcast_address: str, buffer_size: int) -> Sequence[str]: + def search_device(self, broadcast_address: str, buffer_size: int) -> List[str]: """Perform network scan in order to collect available ZK devices SDK: SearchDevice() @@ -127,7 +127,7 @@ def search_device(self, broadcast_address: str, buffer_size: int) -> Sequence[st with contents Returns: - Sequence[str]: device string lines + List[str]: device string lines Raises: ZKSDKError: on SDK error @@ -218,7 +218,7 @@ def set_device_param(self, parameters: Mapping[str, Any]) -> None: if err < 0: raise ZKSDKError("SetDeviceParam failed", err) - def get_device_data( # pylint: disable=too-many-locals + def get_device_data( # pylint: disable=too-many-locals,missing-param-doc self, table_name: str, fields: Sequence[str], @@ -237,7 +237,7 @@ def get_device_data( # pylint: disable=too-many-locals filters (Mapping[str, str]): query conditions to apply buffer_size (int): size in bytes of buffer which is filled with contents - new_records_only (bool): true means to + new_records_only (bool, default=False): true means to consider only unread records in table, otherwise all records will be considered @@ -386,8 +386,8 @@ def get_device_file_data(self, remote_filename: str, buffer_size: int) -> bytes: SDK: GetDeviceFileData() Args: - remote_filename: file name to download - buffer_size: buffer size in bytes for incoming file data + remote_filename (str): file name to download + buffer_size (int): buffer size in bytes for incoming file data Returns: bytes: bytes with file data @@ -412,9 +412,6 @@ def set_device_file_data(self, remote_filename: str, file_data: bytes, size: int remote_filename (str): file name to upload file_data (bytes): file data bytes size (int): data size in bytes to write - - Returns: - """ query_filename = remote_filename.encode() @@ -436,11 +433,11 @@ def modify_ip_address( SDK: ModifyIPAddress() Args: - protocol (str): protocol name to use mac_address (str): mac address of a device new_ip_address (str): new ip address that will be set on a device with given mac address broadcast_address (str): network broadcast address + protocol (str): protocol name to use """ query_parameters = f"MAC={mac_address},IPAddress={new_ip_address}".encode()