add part of docstrings

ormar/decorators/__init__.py

@@ -1,3 +1,11 @@
+"""
+Module with all decorators that are exposed for users.
+
+Currently only:
+* property_field - exposing @property like function as field in Model.dict()
+* predefined signals decorators (pre/post + save/update/delete)
+
+"""
 from ormar.decorators.property_field import property_field
 from ormar.decorators.signals import (
     post_delete,

ormar/decorators/property_field.py

@@ -6,6 +6,19 @@ from ormar.exceptions import ModelDefinitionError
 
 
 def property_field(func: Callable) -> Union[property, Callable]:
+    """
+    Decorator to set a property like function on Model to be exposed
+    as field in dict() and fastapi response.
+    Although you can decorate a @property field like this and this will work,
+    mypy validation will complain about this.
+    Note that "fields" exposed like this do not go through validation.
+
+    :raises: ModelDefinitionError if method has any other argument than self.
+    :param func: decorated function to be exposed
+    :type func: Callable
+    :return: decorated function passed in func param, with set __property_field__ = True
+    :rtype: Union[property, Callable]
+    """
     if isinstance(func, property):  # pragma: no cover
         func.fget.__property_field__ = True
     else:

ormar/decorators/signals.py

@@ -7,7 +7,28 @@ if TYPE_CHECKING:  # pragma: no cover
 def receiver(
     signal: str, senders: Union[Type["Model"], List[Type["Model"]]]
 ) -> Callable:
+    """
+    Connect given function to all senders for given signal name.
+
+    :param signal: name of the signal to register to
+    :type signal: str
+    :param senders: one or a list of "Model" classes
+    that should have the signal receiver registered
+    :type senders: Union[Type["Model"], List[Type["Model"]]]
+    :return: returns the original function untouched
+    :rtype: Callable
+    """
+
     def _decorator(func: Callable) -> Callable:
+        """
+
+        Internal decorator that does all the registeriing.
+
+        :param func: function to register as receiver
+        :type func: Callable
+        :return: untouched function already registered for given signal
+        :rtype: Callable
+        """
         if not isinstance(senders, list):
             _senders = [senders]
         else:
@@ -21,24 +42,78 @@ def receiver(
 
 
 def post_save(senders: Union[Type["Model"], List[Type["Model"]]],) -> Callable:
+    """
+    Connect given function to all senders for post_save signal.
+
+    :param senders: one or a list of "Model" classes
+    that should have the signal receiver registered
+    :type senders: Union[Type["Model"], List[Type["Model"]]]
+    :return: returns the original function untouched
+    :rtype: Callable
+    """
     return receiver(signal="post_save", senders=senders)
 
 
 def post_update(senders: Union[Type["Model"], List[Type["Model"]]],) -> Callable:
+    """
+    Connect given function to all senders for post_update signal.
+
+    :param senders: one or a list of "Model" classes
+    that should have the signal receiver registered
+    :type senders: Union[Type["Model"], List[Type["Model"]]]
+    :return: returns the original function untouched
+    :rtype: Callable
+    """
     return receiver(signal="post_update", senders=senders)
 
 
 def post_delete(senders: Union[Type["Model"], List[Type["Model"]]],) -> Callable:
+    """
+    Connect given function to all senders for post_delete signal.
+
+    :param senders: one or a list of "Model" classes
+    that should have the signal receiver registered
+    :type senders: Union[Type["Model"], List[Type["Model"]]]
+    :return: returns the original function untouched
+    :rtype: Callable
+    """
     return receiver(signal="post_delete", senders=senders)
 
 
 def pre_save(senders: Union[Type["Model"], List[Type["Model"]]],) -> Callable:
+    """
+    Connect given function to all senders for pre_save signal.
+
+    :param senders: one or a list of "Model" classes
+    that should have the signal receiver registered
+    :type senders: Union[Type["Model"], List[Type["Model"]]]
+    :return: returns the original function untouched
+    :rtype: Callable
+    """
     return receiver(signal="pre_save", senders=senders)
 
 
 def pre_update(senders: Union[Type["Model"], List[Type["Model"]]]) -> Callable:
+    """
+    Connect given function to all senders for pre_update signal.
+
+    :param senders: one or a list of "Model" classes
+    that should have the signal receiver registered
+    :type senders: Union[Type["Model"], List[Type["Model"]]]
+    :return: returns the original function untouched
+    :rtype: Callable
+    """
     return receiver(signal="pre_update", senders=senders)
 
 
 def pre_delete(senders: Union[Type["Model"], List[Type["Model"]]]) -> Callable:
+    """
+    Connect given function to all senders for pre_delete signal.
+
+    :param senders: one or a list of "Model" classes
+    that should have the signal receiver registered
+    :type senders: Union[Type["Model"], List[Type["Model"]]]
+    :return: returns the original function untouched
+    :rtype: Callable
+    """
     return receiver(signal="pre_delete", senders=senders)