Add factory_boy plugin support

mimesis/__init__.py

@@ -146,7 +146,7 @@
     "__license__",
 ]
 
-__version__ = "14.0.0"
+__version__ = "15.0.0"
 __title__ = "mimesis"
 __description__ = "Mimesis: Fake Data Generator."
 __url__ = "https://github.com/lk-geimfari/mimesis"

mimesis/plugins/factory.py

@@ -0,0 +1,118 @@
+from contextlib import contextmanager
+from typing import Any, ClassVar, Iterator
+
+from mimesis.locales import Locale
+from mimesis.schema import Field, RegisterableFieldHandlers
+
+try:
+    from factory import declarations
+    from factory.builder import BuildStep, Resolver
+except ImportError:
+    raise ImportError("This plugin requires factory_boy to be installed.")
+
+__all__ = ["MimesisField"]
+
+
+class MimesisField(declarations.BaseDeclaration):  # type: ignore[misc]
+    """
+    Mimesis integration with FactoryBoy starts here.
+
+    This class provides a common interface for FactoryBoy,
+    but inside it has Mimesis generators.
+    """
+
+    _default_locale: ClassVar[Locale] = Locale.EN
+    _cached_instances: ClassVar[dict[str, Field]] = {}
+
+    def __init__(
+        self,
+        field: str,
+        locale: Locale | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Creates a field instance.
+
+        The created field is lazy. It also receives build time parameters.
+        These parameters are not applied yet.
+
+        :param field: name to be passed to :class:`~mimesis.schema.Field`.
+        :param locale: locale to use. This parameter has the highest priority.
+        :param kwargs: optional parameters that would be passed to ``Field``.
+        """
+        super().__init__()
+        self.locale = locale
+        self.kwargs = kwargs
+        self.field = field
+
+    def evaluate(
+        self,
+        instance: Resolver,
+        step: BuildStep,
+        extra: dict[str, Any] | None = None,
+    ) -> Any:
+        """Evaluates the lazy field.
+
+        :param instance: (factory.builder.Resolver): The object holding currently computed attributes.
+        :param step: (factory.builder.BuildStep): The object holding the current build step.
+        :param extra: Extra call-time added kwargs that would be passed to ``Field``.
+        """
+        kwargs: dict[str, Any] = {}
+        kwargs.update(self.kwargs)
+        kwargs.update(extra or {})
+
+        field_handlers = step.builder.factory_meta.declarations.get(
+            "field_handlers", []
+        )
+
+        mimesis_field = self._get_cached_instance(
+            locale=self.locale,
+            field_handlers=field_handlers,
+        )
+        return mimesis_field(self.field, **kwargs)
+
+    @classmethod
+    @contextmanager
+    def override_locale(cls, locale: Locale) -> Iterator[None]:
+        """
+        Overrides unspecified locales.
+
+        Remember that implicit locales would not be overridden.
+        """
+        old_locale = cls._default_locale
+        cls._default_locale = locale
+        yield
+        cls._default_locale = old_locale
+
+    @classmethod
+    def _get_cached_instance(
+        cls,
+        locale: Locale | None = None,
+        field_handlers: RegisterableFieldHandlers | None = None,
+    ) -> Field:
+        """Returns cached instance.
+
+        :param locale: locale to use.
+        :param field_handlers: custom field handlers.
+        :return: cached instance of Field.
+        """
+        if locale is None:
+            locale = cls._default_locale
+
+        field_names = "-".join(
+            sorted(
+                dict(field_handlers if field_handlers else []).keys(),
+            )
+        )
+
+        key = f"{locale}{field_names}"
+
+        if key not in cls._cached_instances:
+            field = Field(locale)
+
+            if field_handlers:
+                field.register_handlers(field_handlers)
+
+            cls._cached_instances[key] = field
+
+        return cls._cached_instances[key]

mimesis/schema.py

@@ -5,7 +5,7 @@
 import json
 import pickle
 import re
-import typing as t
+from typing import Any, Callable, Sequence
 
 from mimesis.exceptions import (
     AliasesTypeError,
@@ -21,12 +21,20 @@
 from mimesis.random import Random
 from mimesis.types import JSON, CallableSchema, Key, MissingSeed, Seed
 
-__all__ = ["BaseField", "Field", "Fieldset", "Schema"]
-
-FieldCache = dict[str, t.Callable[[t.Any], t.Any]]
-FieldHandler = t.Callable[[Random, t.Any], t.Any]
+__all__ = [
+    "BaseField",
+    "Field",
+    "Fieldset",
+    "Schema",
+    "FieldHandler",
+    "RegisterableFieldHandler",
+    "RegisterableFieldHandlers",
+]
+
+FieldCache = dict[str, Callable[[Any], Any]]
+FieldHandler = Callable[[Random, Any], Any]
 RegisterableFieldHandler = tuple[str, FieldHandler]
-RegisterableFieldHandlers = t.Sequence[RegisterableFieldHandler]
+RegisterableFieldHandlers = Sequence[RegisterableFieldHandler]
 
 
 class BaseField:
@@ -62,7 +70,7 @@ def get_random_instance(self) -> Random:
         """
         return self._generic.random
 
-    def _explicit_lookup(self, name: str) -> t.Any:
+    def _explicit_lookup(self, name: str) -> Any:
         """An explicit method lookup.
 
         This method is called when the field
@@ -79,7 +87,7 @@ def _explicit_lookup(self, name: str) -> t.Any:
         except AttributeError:
             raise FieldError(name)
 
-    def _fuzzy_lookup(self, name: str) -> t.Any:
+    def _fuzzy_lookup(self, name: str) -> Any:
         """A fuzzy method lookup.
 
         This method is called when the field definition
@@ -97,7 +105,7 @@ def _fuzzy_lookup(self, name: str) -> t.Any:
 
         raise FieldError(name)
 
-    def _lookup_method(self, name: str) -> t.Any:
+    def _lookup_method(self, name: str) -> Any:
         """Lookup method by the field name.
 
         :param name: The field name.
@@ -137,8 +145,8 @@ def perform(
         self,
         name: str | None = None,
         key: Key = None,
-        **kwargs: t.Any,
-    ) -> t.Any:
+        **kwargs: Any,
+    ) -> Any:
         """Performs the value of the field by its name.
 
         It takes any string that represents the name of any method of
@@ -224,7 +232,7 @@ def register_handler(self, field_name: str, field_handler: FieldHandler) -> None
 
     def handle(
         self, field_name: str | None = None
-    ) -> t.Callable[[FieldHandler], FieldHandler]:
+    ) -> Callable[[FieldHandler], FieldHandler]:
         """Decorator for registering a custom field handler.
 
         You can use this decorator only for functions,
@@ -261,7 +269,7 @@ def unregister_handler(self, field_name: str) -> None:
 
         self._handlers.pop(field_name, None)
 
-    def unregister_handlers(self, field_names: t.Sequence[str] = ()) -> None:
+    def unregister_handlers(self, field_names: Sequence[str] = ()) -> None:
         """Unregister a field handlers with given names.
 
         :param field_names: Names of the fields.
@@ -305,7 +313,7 @@ class Field(BaseField):
         Dogtag_1836
     """
 
-    def __call__(self, *args: t.Any, **kwargs: t.Any) -> t.Any:
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
         return self.perform(*args, **kwargs)
 
 
@@ -338,7 +346,7 @@ class Fieldset(BaseField):
     fieldset_default_iterations: int = 10
     fieldset_iterations_kwarg: str = "i"
 
-    def __init__(self, *args: t.Any, **kwargs: t.Any) -> None:
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
         """Initialize fieldset.
 
         Accepts additional keyword argument **i** which is used
@@ -353,7 +361,7 @@ def __init__(self, *args: t.Any, **kwargs: t.Any) -> None:
         )
         super().__init__(*args, **kwargs)
 
-    def __call__(self, *args: t.Any, **kwargs: t.Any) -> list[t.Any]:
+    def __call__(self, *args: Any, **kwargs: Any) -> list[Any]:
         """Perform fieldset.
 
         :param args: Arguments for field.
@@ -399,7 +407,7 @@ def __init__(self, schema: CallableSchema, iterations: int = 10) -> None:
         else:
             raise SchemaError()
 
-    def to_csv(self, file_path: str, **kwargs: t.Any) -> None:
+    def to_csv(self, file_path: str, **kwargs: Any) -> None:
         """Export a schema as a CSV file.
 
         :param file_path: The file path.
@@ -412,7 +420,7 @@ def to_csv(self, file_path: str, **kwargs: t.Any) -> None:
             dict_writer.writeheader()
             dict_writer.writerows(data)
 
-    def to_json(self, file_path: str, **kwargs: t.Any) -> None:
+    def to_json(self, file_path: str, **kwargs: Any) -> None:
         """Export a schema as a JSON file.
 
         :param file_path: File a path.
@@ -421,7 +429,7 @@ def to_json(self, file_path: str, **kwargs: t.Any) -> None:
         with open(file_path, "w", encoding="utf-8") as fp:
             json.dump(self.create(), fp, **kwargs)
 
-    def to_pickle(self, file_path: str, **kwargs: t.Any) -> None:
+    def to_pickle(self, file_path: str, **kwargs: Any) -> None:
         """Export a schema as the pickled representation of the object to the file.
 
         :param file_path: The file path.