Fix func documentation

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)

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

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(

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:

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)):

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
         """

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
 
         """

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)

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: