applied pre-commit corrections. Improved doc comments

anikolaienko · anikolaienko · commit 8ac61b175264 · 2022-10-25T12:12:40.000+03:00
diff --git a/automapper/exceptions.py b/automapper/exceptions.py
@@ -8,4 +8,6 @@ class MappingError(Exception):
 
 class CircularReferenceError(Exception):
     def __init__(self, *args: object) -> None:
-        super().__init__("Mapper does not support objects with circular references yet", *args)
+        super().__init__(
+            "Mapper does not support objects with circular references yet", *args
+        )
diff --git a/automapper/extensions/default.py b/automapper/extensions/default.py
@@ -11,7 +11,9 @@ def __init_method_classifier__(target_cls: Type[T]) -> bool:
     return (
         hasattr(target_cls, "__init__")
         and hasattr(getattr(target_cls, "__init__"), "__annotations__")
-        and isinstance(getattr(getattr(target_cls, "__init__"), "__annotations__"), dict)
+        and isinstance(
+            getattr(getattr(target_cls, "__init__"), "__annotations__"), dict
+        )
         and getattr(getattr(target_cls, "__init__"), "__annotations__")
     )
 
diff --git a/automapper/mapper.py b/automapper/mapper.py
@@ -32,17 +32,17 @@
 __PRIMITIVE_TYPES = {int, float, complex, str, bytes, bytearray, bool}
 
 
-def is_sequence(obj: Any) -> bool:
+def _is_sequence(obj: Any) -> bool:
     """Check if object implements `__iter__` method"""
     return hasattr(obj, "__iter__")
 
 
-def is_subscriptable(obj: Any) -> bool:
+def _is_subscriptable(obj: Any) -> bool:
     """Check if object implements `__get_item__` method"""
     return hasattr(obj, "__get_item__")
 
 
-def is_primitive(obj: Any) -> bool:
+def _is_primitive(obj: Any) -> bool:
     """Check if object type is primitive"""
     return type(obj) in __PRIMITIVE_TYPES
 
@@ -67,12 +67,26 @@ def map(
         fields_mapping: FieldsMap = None,
         deepcopy: bool = True,
     ) -> T:
-        """Produces output object mapped from source object and custom arguments
+        """Produces output object mapped from source object and custom arguments.
 
         Parameters:
             skip_none_values - do not map fields that has None value
             fields_mapping - mapping for fields with different names
             deepcopy - should we deepcopy all attributes? [default: True]
+
+        Args:
+            obj (S): _description_
+            skip_none_values (bool, optional): Skip None values when creating `target class` obj. Defaults to False.
+            fields_mapping (FieldsMap, optional): Custom mapping.
+                Specify dictionary in format {"field_name": value_object}. Defaults to None.
+            deepcopy (bool, optional): Applies deepcopy to all child objects when copy into output instance.
+                Defaults to True.
+
+        Raises:
+            CircularReferenceError: Circular references in `source class` object are not allowed yet.
+
+        Returns:
+            T: instance of `target class` with mapped values from `source class` or custom `fields_mapping` dictionary.
         """
         return self.__mapper._map_common(
             obj,
@@ -97,22 +111,22 @@ def __init__(self) -> None:
     def add_spec(self, classifier: Type[T], spec_func: SpecFunction[T]) -> None:
         """Add a spec function for all classes in inherited from base class.
 
-        Parameters:
-            * classifier - base class to identify all descendant classes
-            * spec_func - returns a list of fields (List[str]) for target class
-            that are accepted in constructor
+        Args:
+            classifier (ClassifierFunction[T]): base class to identify all descendant classes.
+            spec_func (SpecFunction[T]): get list of fields (List[str]) for `target class` to be passed in constructor.
         """
         ...
 
     @overload
-    def add_spec(self, classifier: ClassifierFunction[T], spec_func: SpecFunction[T]) -> None:
+    def add_spec(
+        self, classifier: ClassifierFunction[T], spec_func: SpecFunction[T]
+    ) -> None:
         """Add a spec function for all classes identified by classifier function.
 
-        Parameters:
-            * classifier - boolean predicate that identifies a group of classes
-            by certain characteristics: if class has a specific method or a field, etc.
-            * spec_func - returns a list of fields (List[str]) for target class
-            that are accepted in constructor
+        Args:
+            classifier (ClassifierFunction[T]): boolean predicate that identifies a group of classes
+                by certain characteristics: if class has a specific method or a field, etc.
+            spec_func (SpecFunction[T]): get list of fields (List[str]) for `target class` to be passed in constructor.
         """
         ...
 
@@ -146,16 +160,21 @@ def add(
     ) -> None:
         """Adds mapping between object of `source class` to an object of `target class`.
 
-        Parameters
-        ----------
-        source_cls : Type
-            Source class to map from
-        target_cls : Type
-            Target class to map to
-        override : bool, optional
-            Override existing `source class` mapping to use new `target class`
-        deepcopy : bool, optional
-            Should we deepcopy all attributes? [default: True]
+        Args:
+            source_cls (Type[S]): Source class to map from
+            target_cls (Type[T]): Target class to map to
+            override (bool, optional): Override existing `source class` mapping to use new `target class`.
+                Defaults to False.
+            fields_mapping (FieldsMap, optional): Custom mapping.
+                Specify dictionary in format {"field_name": value_object}. Defaults to None.
+            deepcopy (bool, optional): Applies deepcopy to all child objects when copy into output instance.
+                Defaults to True.
+
+        Raises:
+            DuplicatedRegistrationError: Same mapping for `source class` was added.
+            Only one mapping per source class can exist at a time for now.
+            You can specify target class manually using `mapper.to(target_cls)` method
+            or use `override` argument to replace existing mapping.
         """
         if source_cls in self._mappings and not override:
             raise DuplicatedRegistrationError(
@@ -169,22 +188,42 @@ def map(
         *,
         skip_none_values: bool = False,
         fields_mapping: FieldsMap = None,
-        deepcopy: bool = None,
+        deepcopy: bool = True,
     ) -> T:  # type: ignore [type-var]
-        """Produces output object mapped from source object and custom arguments"""
+        """Produces output object mapped from source object and custom arguments
+
+        Args:
+            obj (object): Source object to map to `target class`.
+            skip_none_values (bool, optional): Skip None values when creating `target class` obj. Defaults to False.
+            fields_mapping (FieldsMap, optional): Custom mapping.
+                Specify dictionary in format {"field_name": value_object}. Defaults to None.
+            deepcopy (bool, optional): Applies deepcopy to all child objects when copy into output instance.
+                Defaults to True.
+
+        Raises:
+            MappingError: No `target class` specified to be mapped into.
+                Register mappings using `mapped.add(...)` or specify `target class` using `mapper.to(target_cls).map()`.
+            CircularReferenceError: Circular references in `source class` object are not allowed yet.
+
+        Returns:
+            T: instance of `target class` with mapped values from `source class` or custom `fields_mapping` dictionary.
+        """
         obj_type = type(obj)
         if obj_type not in self._mappings:
             raise MappingError(f"Missing mapping type for input type {obj_type}")
         obj_type_preffix = f"{obj_type.__name__}."
 
-        target_cls, target_cls_field_mappings, target_deepcopy = self._mappings[obj_type]
+        target_cls, target_cls_field_mappings, target_deepcopy = self._mappings[
+            obj_type
+        ]
 
         common_fields_mapping = fields_mapping
         if target_cls_field_mappings:
             # transform mapping if it's from source class field
             common_fields_mapping = {
                 target_obj_field: getattr(obj, source_field[len(obj_type_preffix) :])
-                if isinstance(source_field, str) and source_field.startswith(obj_type_preffix)
+                if isinstance(source_field, str)
+                and source_field.startswith(obj_type_preffix)
                 else source_field
                 for target_obj_field, source_field in target_cls_field_mappings.items()
             }
@@ -217,13 +256,15 @@ def _get_fields(self, target_cls: Type[T]) -> Iterable[str]:
             if classifier(target_cls):
                 return self._classifier_specs[classifier](target_cls)
 
-        raise MappingError(f"No spec function is added for base class of {type(target_cls)}")
+        raise MappingError(
+            f"No spec function is added for base class of {type(target_cls)}"
+        )
 
     def _map_subobject(
         self, obj: S, _visited_stack: Set[int], skip_none_values: bool = False
     ) -> Any:
         """Maps subobjects recursively"""
-        if is_primitive(obj):
+        if _is_primitive(obj):
             return obj
 
         obj_id = id(obj)
@@ -238,10 +279,12 @@ def _map_subobject(
         else:
             _visited_stack.add(obj_id)
 
-            if is_sequence(obj):
+            if _is_sequence(obj):
                 if isinstance(obj, dict):
                     result = {
-                        k: self._map_subobject(v, _visited_stack, skip_none_values=skip_none_values)
+                        k: self._map_subobject(
+                            v, _visited_stack, skip_none_values=skip_none_values
+                        )
                         for k, v in obj.items()
                     }
                 else:
@@ -269,12 +312,23 @@ def _map_common(
         fields_mapping: FieldsMap = None,
         deepcopy: bool = True,
     ) -> T:
-        """Produces output object mapped from source object and custom arguments
-
-        Parameters:
-            skip_none_values - do not map fields that has None value
-            fields_mapping - fields mappings for fields with different names
-            deepcopy - Should we deepcopy all attributes? [default: True]
+        """Produces output object mapped from source object and custom arguments.
+
+        Args:
+            obj (S): Source object to map to `target class`.
+            target_cls (Type[T]): Target class to map to.
+            _visited_stack (Set[int]): Visited child objects. To avoid infinite recursive calls.
+            skip_none_values (bool, optional): Skip None values when creating `target class` obj. Defaults to False.
+            fields_mapping (FieldsMap, optional): Custom mapping.
+                Specify dictionary in format {"field_name": value_object}. Defaults to None.
+            deepcopy (bool, optional): Applies deepcopy to all child objects when copy into output instance.
+                Defaults to True.
+
+        Raises:
+            CircularReferenceError: Circular references in `source class` object are not allowed yet.
+
+        Returns:
+            T: Instance of `target class` with mapped fields.
         """
         obj_id = id(obj)
 
@@ -285,7 +339,7 @@ def _map_common(
         target_cls_fields = self._get_fields(target_cls)
 
         mapped_values: Dict[str, Any] = {}
-        is_obj_subscriptable = is_subscriptable(obj)
+        is_obj_subscriptable = _is_subscriptable(obj)
         for field_name in target_cls_fields:
             if (
                 (fields_mapping and field_name in fields_mapping)
@@ -316,5 +370,12 @@ def _map_common(
         return cast(target_cls, target_cls(**mapped_values))  # type: ignore [valid-type]
 
     def to(self, target_cls: Type[T]) -> MappingWrapper[T]:
-        """Specify target class to map source object to"""
+        """Specify `target class` to which map `source class` object.
+
+        Args:
+            target_cls (Type[T]): Target class.
+
+        Returns:
+            MappingWrapper[T]: Mapping wrapper. Use `map` method to perform mapping now.
+        """
         return MappingWrapper[T](self, target_cls)
diff --git a/tests/test_automapper.py b/tests/test_automapper.py
@@ -20,7 +20,9 @@ def __init__(self, num: int, text: str, flag: bool) -> None:
 
     @classmethod
     def fields(cls) -> Iterable[str]:
-        return (field for field in cls.__init__.__annotations__.keys() if field != "return")
+        return (
+            field for field in cls.__init__.__annotations__.keys() if field != "return"
+        )
 
 
 class AnotherClass:
@@ -66,12 +68,16 @@ def setUp(self):
     def test_add_spec__adds_to_internal_collection(self):
         self.mapper.add_spec(ParentClass, custom_spec_func)
         assert ParentClass in self.mapper._class_specs
-        assert ["num", "text", "flag"] == self.mapper._class_specs[ParentClass](ChildClass)
+        assert ["num", "text", "flag"] == self.mapper._class_specs[ParentClass](
+            ChildClass
+        )
 
     def test_add_spec__error_on_adding_same_class_spec(self):
         self.mapper.add_spec(ParentClass, custom_spec_func)
         with pytest.raises(DuplicatedRegistrationError):
-            self.mapper.add_spec(ParentClass, lambda concrete_type: ["field1", "field2"])
+            self.mapper.add_spec(
+                ParentClass, lambda concrete_type: ["field1", "field2"]
+            )
 
     def test_add_spec__adds_to_internal_collection_for_classifier(self):
         self.mapper.add_spec(classifier_func, spec_func)
diff --git a/tests/test_automapper_dict_field.py b/tests/test_automapper_dict_field.py
@@ -1,7 +1,7 @@
 from typing import Any, Dict
 from unittest import TestCase
 
-from automapper import mapper, create_mapper
+from automapper import create_mapper, mapper
 
 
 class Candy:
@@ -36,17 +36,27 @@ def setUp(self) -> None:
     def test_map__with_dict_field(self):
         public_info = mapper.to(ShopPublicInfo).map(self.shop)
 
-        self.assertEqual(public_info.products["magazines"], self.shop.products["magazines"])
+        self.assertEqual(
+            public_info.products["magazines"], self.shop.products["magazines"]
+        )
         self.assertNotEqual(
             id(public_info.products["magazines"]), id(self.shop.products["magazines"])
         )
 
-        self.assertNotEqual(public_info.products["candies"], self.shop.products["candies"])
-        self.assertNotEqual(public_info.products["candies"][0], self.shop.products["candies"][0])
-        self.assertNotEqual(public_info.products["candies"][1], self.shop.products["candies"][1])
+        self.assertNotEqual(
+            public_info.products["candies"], self.shop.products["candies"]
+        )
+        self.assertNotEqual(
+            public_info.products["candies"][0], self.shop.products["candies"][0]
+        )
+        self.assertNotEqual(
+            public_info.products["candies"][1], self.shop.products["candies"][1]
+        )
 
         self.assertEqual(public_info.products["candies"][0].name, "Reese's cups")
-        self.assertEqual(public_info.products["candies"][0].brand, "The Hershey Company")
+        self.assertEqual(
+            public_info.products["candies"][0].brand, "The Hershey Company"
+        )
 
         self.assertEqual(public_info.products["candies"][1].name, "Snickers")
         self.assertEqual(public_info.products["candies"][1].brand, "Mars, Incorporated")
@@ -56,20 +66,25 @@ def test_deepcopy_disabled(self):
         public_info = mapper.to(ShopPublicInfo).map(self.shop)
 
         self.assertIsNot(public_info.products, self.shop.products)
-        self.assertEqual(public_info.products["magazines"], self.shop.products["magazines"])
-        self.assertNotEqual(public_info.products["magazines"], id(self.shop.products["magazines"]))
+        self.assertEqual(
+            public_info.products["magazines"], self.shop.products["magazines"]
+        )
+        self.assertNotEqual(
+            public_info.products["magazines"], id(self.shop.products["magazines"])
+        )
 
         self.assertIs(public_info_deep.products, self.shop.products)
         self.assertEqual(
-            id(public_info_deep.products["magazines"]), id(self.shop.products["magazines"])
+            id(public_info_deep.products["magazines"]),
+            id(self.shop.products["magazines"]),
         )
 
     def test_deepcopy_disabled_in_add(self):
         self.mapper.add(Shop, ShopPublicInfo, deepcopy=False)
-        public_info = self.mapper.map(self.shop)
+        public_info: ShopPublicInfo = self.mapper.map(self.shop)
 
         self.assertIs(public_info.products, self.shop.products)
 
         # Manually enable deepcopy on .map()
-        public_info = self.mapper.map(self.shop, deepcopy=True)
-        self.assertIsNot(public_info.products, self.shop.products)
+        public_info2: ShopPublicInfo = self.mapper.map(self.shop, deepcopy=True)
+        self.assertIsNot(public_info2.products, self.shop.products)
diff --git a/tests/test_automapper_sample.py b/tests/test_automapper_sample.py
@@ -1,4 +1,5 @@
 from dataclasses import dataclass
+
 from automapper import mapper
 
 
@@ -64,7 +65,9 @@ def test_map__field_with_different_name():
 
 def test_map__field_with_different_name_register():
     try:
-        mapper.add(UserInfo, PublicUserInfoDiff, fields_mapping={"full_name": "UserInfo.name"})
+        mapper.add(
+            UserInfo, PublicUserInfoDiff, fields_mapping={"full_name": "UserInfo.name"}
+        )
 
         user_info = UserInfo("John Malkovich", 35, "engineer")
         public_user_info: PublicUserInfoDiff = mapper.map(user_info)
diff --git a/tests/test_for_complex_obj.py b/tests/test_for_complex_obj.py
diff --git a/tests/test_for_sqlalchemy_extention.py b/tests/test_for_sqlalchemy_extention.py
