Docstrings

Author: bogdandm

rest_client_gen/dynamic_typing/string_datetime.py

@@ -1,6 +1,6 @@
 import operator
 from datetime import date, datetime, time
-from typing import Optional
+from typing import Any, Optional, Type, Union
 
 import dateutil.parser
 
@@ -11,7 +11,14 @@
 _t_args_getter = operator.attrgetter('hour', 'minute', 'second', 'microsecond', 'tzinfo')
 
 
-def _extend_datetime(d, cls: type):
+def extend_datetime(d: Union[date, time, datetime], cls: Union[Type[date], Type[time], Type[datetime]]) -> Any:
+    """
+    Wrap datetime object into datetime subclass
+
+    :param d: date/time/datetime instance
+    :param cls: datetime subclass
+    :return:
+    """
     if isinstance(d, datetime):
         args = _dt_args_getter
     elif isinstance(d, time):
@@ -28,6 +35,14 @@ def _extend_datetime(d, cls: type):
 
 
 def is_date(s: str) -> Optional[date]:
+    """
+    Return date instance if given string is a date and None otherwise
+
+    :param s: string
+    :return: date or None
+    """
+    # dateutil.parser.parse replaces missing parts of datetime with values from default value
+    # so if there is hour part in given string then d1 and d2 would be equal and string is not pure date
     d1 = dateutil.parser.parse(s, default=_check_values_date[0])
     d2 = dateutil.parser.parse(s, default=_check_values_date[1])
     return None if d1 == d2 else d1.date()
@@ -40,6 +55,12 @@ def is_date(s: str) -> Optional[date]:
 
 
 def is_time(s: str) -> Optional[time]:
+    """
+    Return time instance if given string is a time and None otherwise
+
+    :param s: string
+    :return: time or None
+    """
     d1 = dateutil.parser.parse(s, default=_check_values_time[0])
     d2 = dateutil.parser.parse(s, default=_check_values_time[1])
     return None if d1 == d2 else d1.time()
@@ -48,15 +69,15 @@ def is_time(s: str) -> Optional[time]:
 class IsoDateString(StringSerializable, date):
     """
     Parse date using dateutil.parser.isoparse. Representation format always is ``YYYY-MM-DD``.
-    You can override to_representation method to customize it. Just don't forget to call registry.remove(YourCls)
+    You can override to_representation method to customize it. Just don't forget to call registry.remove(IsoDateString)
     """
 
     @classmethod
     def to_internal_value(cls, value: str) -> 'IsoDateString':
         if not is_date(value):
             raise ValueError(f"'{value}' is not valid date")
         dt = dateutil.parser.isoparse(value)
-        return _extend_datetime(dt.date(), cls)
+        return extend_datetime(dt.date(), cls)
 
     def to_representation(self):
         return self.isoformat()
@@ -77,7 +98,7 @@ def to_internal_value(cls, value: str) -> 'IsoTimeString':
         t = is_time(value)
         if not t:
             raise ValueError(f"'{value}' is not valid time")
-        return _extend_datetime(t, cls)
+        return extend_datetime(t, cls)
 
     def to_representation(self):
         return self.isoformat()
@@ -96,7 +117,7 @@ class IsoDatetimeString(StringSerializable, datetime):
     @classmethod
     def to_internal_value(cls, value: str) -> 'IsoDatetimeString':
         dt = dateutil.parser.isoparse(value)
-        return _extend_datetime(dt, cls)
+        return extend_datetime(dt, cls)
 
     def to_representation(self):
         return self.isoformat()