Random model builder (piccolo-orm#169)

aminalaee · dantownsend · web-flow · commit 74d160998a41 · 2021-08-25T21:10:50.000+01:00
* add random model builders

* add `build` and `build_sync` methods

* Use `run_sync`

* Make `build` classmethods, use Piccolo for column checking and update docs

* updated docs

Made sure `await` is used where appropriate, and added link to the new tester app

Co-authored-by: Daniel Townsend &lt;dan@dantownsend.co.uk&gt;
diff --git a/docs/src/index.rst b/docs/src/index.rst
@@ -14,6 +14,7 @@ Welcome to Piccolo's documentation!
    piccolo/migrations/index
    piccolo/authentication/index
    piccolo/asgi/index
+   piccolo/testing/index
    piccolo/features/index
    piccolo/playground/index
    piccolo/deployment/index
diff --git a/docs/src/piccolo/projects_and_apps/included_apps.rst b/docs/src/piccolo/projects_and_apps/included_apps.rst
@@ -101,6 +101,8 @@ need to run raw SQL queries on your database.
 For it to work, the underlying command needs to be on the path (i.e. ``psql``
 or ``sqlite3`` depending on which you're using).
 
+.. _TesterApp:
+
 tester
 ~~~~~~
 
diff --git a/docs/src/piccolo/testing/index.rst b/docs/src/piccolo/testing/index.rst
@@ -0,0 +1,73 @@
+Testing
+=======
+
+Piccolo provides a few tools to make testing easier and decrease manual work.
+
+Model Builder
+-------------
+
+When writing unit tests, it's usually required to have some data seeded into the database.
+You can build and save the records manually or use ``ModelBuilder`` to generate random records for you.
+
+This way you can randomize the fields you don't care about and specify important fields explicitly and
+reduce the amount of manual work required.
+``ModelBuilder`` currently supports all Piccolo column types and features.
+
+Let's say we have the following schema:
+
+.. code-block:: python
+
+    from piccolo.columns import ForeignKey, Varchar
+
+    class Manager(Table):
+        name = Varchar(length=50)
+
+    class Band(Table):
+        name = Varchar(length=50)
+        manager = ForeignKey(Manager, null=True)
+
+You can build a random ``Band`` which will also build and save a random ``Manager``:
+
+.. code-block:: python
+
+    from piccolo.testing.model_builder import ModelBuilder
+
+    band = await ModelBuilder.build(Band)  # Band instance with random values persisted
+
+.. note:: ``ModelBuilder.build(Band)`` persists record into the database by default.
+
+You can also run it synchronously if you prefer:
+
+.. code-block:: python
+
+    manager = ModelBuilder.build_sync(Manager)
+
+
+To specify any attribute, pass the ``defaults`` dictionary to the ``build`` method:
+
+.. code-block:: python
+
+    manager = ModelBuilder.build(Manager)
+
+    # Using table columns
+    band = await ModelBuilder.build(Band, defaults={Band.name: "Guido", Band.manager: manager})
+
+    # Or using strings as keys
+    band = await ModelBuilder.build(Band, defaults={"name": "Guido", "manager": manager})
+
+To build objects without persisting them into the database:
+
+.. code-block:: python
+
+    band = await ModelBuilder.build(Band, persist=False)
+
+To build object with minimal attributes, leaving nullable fields empty:
+
+.. code-block:: python
+
+    band = await ModelBuilder.build(Band, minimal=True)  # Leaves manager empty
+
+Test runner
+-----------
+
+See the :ref:`tester app<TesterApp>`.
diff --git a/piccolo/testing/__init__.py b/piccolo/testing/__init__.py
@@ -0,0 +1,3 @@
+from piccolo.testing.model_builder import ModelBuilder
+
+__all__ = ["ModelBuilder"]
diff --git a/piccolo/testing/model_builder.py b/piccolo/testing/model_builder.py
@@ -0,0 +1,156 @@
+import json
+import typing as t
+from datetime import date, datetime, time, timedelta
+from decimal import Decimal
+from uuid import UUID
+
+from piccolo.columns.base import Column
+from piccolo.table import Table
+from piccolo.testing.random_builder import RandomBuilder
+from piccolo.utils.sync import run_sync
+
+
+class ModelBuilder:
+    __DEFAULT_MAPPER: t.Dict[t.Type, t.Callable] = {
+        bool: RandomBuilder.next_bool,
+        bytes: RandomBuilder.next_bytes,
+        date: RandomBuilder.next_date,
+        datetime: RandomBuilder.next_datetime,
+        float: RandomBuilder.next_float,
+        int: RandomBuilder.next_int,
+        str: RandomBuilder.next_str,
+        time: RandomBuilder.next_time,
+        timedelta: RandomBuilder.next_timedelta,
+        UUID: RandomBuilder.next_uuid,
+    }
+
+    @classmethod
+    async def build(
+        cls,
+        table_class: t.Type[Table],
+        defaults: t.Dict[t.Union[Column, str], t.Any] = None,
+        persist: bool = True,
+        minimal: bool = False,
+    ) -> Table:
+        """
+        Build Table instance with random data and save async.
+        This can build relationships, supported data types and parameters.
+
+        :param table_class:
+            Table class to randomize.
+
+        Examples:
+
+            manager = ModelBuilder.build(Manager)
+            manager = ModelBuilder.build(Manager, name='Guido')
+            manager = ModelBuilder(persist=False).build(Manager)
+            manager = ModelBuilder(minimal=True).build(Manager)
+            band = ModelBuilder.build(Band, manager=manager)
+        """
+        return await cls._build(
+            table_class=table_class,
+            defaults=defaults,
+            persist=persist,
+            minimal=minimal,
+        )
+
+    @classmethod
+    def build_sync(
+        cls,
+        table_class: t.Type[Table],
+        defaults: t.Dict[t.Union[Column, str], t.Any] = None,
+        persist: bool = True,
+        minimal: bool = False,
+    ) -> Table:
+        """
+        Build Table instance with random data and save sync.
+        This can build relationships, supported data types and parameters.
+
+        :param table_class:
+            Table class to randomize.
+
+        Examples:
+
+            manager = ModelBuilder.build_sync(Manager)
+            manager = ModelBuilder.build_sync(Manager, name='Guido')
+            manager = ModelBuilder(persist=False).build_sync(Manager)
+            manager = ModelBuilder(minimal=True).build_sync(Manager)
+            band = ModelBuilder.build_sync(Band, manager=manager)
+        """
+        return run_sync(
+            cls.build(
+                table_class=table_class,
+                defaults=defaults,
+                persist=persist,
+                minimal=minimal,
+            )
+        )
+
+    @classmethod
+    async def _build(
+        cls,
+        table_class: t.Type[Table],
+        defaults: t.Dict[t.Union[Column, str], t.Any] = None,
+        minimal: bool = False,
+        persist: bool = True,
+    ) -> Table:
+        model = table_class()
+        defaults = {} if not defaults else defaults
+
+        for column, value in defaults.items():
+            if isinstance(column, str):
+                column = model._meta.get_column_by_name(column)
+
+            setattr(model, column._meta.name, value)
+
+        for column in model._meta.columns:
+
+            if column._meta.null and minimal:
+                continue
+
+            if column._meta.name in defaults:
+                continue  # Column value exists
+
+            if "references" in column._meta.params and persist:
+                reference_model = await cls._build(
+                    column._meta.params["references"],
+                    persist=True,
+                )
+                random_value = getattr(
+                    reference_model,
+                    reference_model._meta.primary_key._meta.name,
+                )
+            else:
+                random_value = cls._randomize_attribute(column)
+
+            setattr(model, column._meta.name, random_value)
+
+        if persist:
+            await model.save().run()
+
+        return model
+
+    @classmethod
+    def _randomize_attribute(cls, column: Column) -> t.Any:
+        """
+        Generate a random value for a column and apply formattings.
+
+        :param column:
+            Column class to randomize.
+        """
+        if column.value_type == Decimal:
+            precision, scale = column._meta.params["digits"]
+            random_value = RandomBuilder.next_float(
+                maximum=10 ** (precision - scale), scale=scale
+            )
+        elif column._meta.choices:
+            random_value = RandomBuilder.next_enum(column._meta.choices)
+        else:
+            random_value = cls.__DEFAULT_MAPPER[column.value_type]()
+
+        if "length" in column._meta.params and isinstance(random_value, str):
+            return random_value[: column._meta.params["length"]]
+        elif column.column_type in ["JSON", "JSONB"]:
+            return json.dumps(random_value)
+
+        return random_value
diff --git a/piccolo/testing/random_builder.py b/piccolo/testing/random_builder.py
@@ -0,0 +1,73 @@
+import enum
+import random
+import string
+import typing as t
+import uuid
+from datetime import date, datetime, time, timedelta
+
+
+class RandomBuilder:
+    @classmethod
+    def next_bool(cls) -> bool:
+        return random.choice([True, False])
+
+    @classmethod
+    def next_bytes(cls, length=8) -> bytes:
+        return random.getrandbits(length * 8).to_bytes(length, "little")
+
+    @classmethod
+    def next_date(cls) -> date:
+        return date(
+            year=random.randint(2000, 2050),
+            month=random.randint(1, 12),
+            day=random.randint(1, 28),
+        )
+
+    @classmethod
+    def next_datetime(cls) -> datetime:
+        return datetime(
+            year=random.randint(2000, 2050),
+            month=random.randint(1, 12),
+            day=random.randint(1, 28),
+            hour=random.randint(0, 23),
+            minute=random.randint(0, 59),
+            second=random.randint(0, 59),
+        )
+
+    @classmethod
+    def next_enum(cls, e: t.Type[enum.Enum]) -> t.Any:
+        return random.choice([item.value for item in e])
+
+    @classmethod
+    def next_float(cls, minimum=0, maximum=2147483647, scale=5) -> float:
+        return round(random.uniform(minimum, maximum), scale)
+
+    @classmethod
+    def next_int(cls, minimum=0, maximum=2147483647) -> int:
+        return random.randint(minimum, maximum)
+
+    @classmethod
+    def next_str(cls, length=16) -> str:
+        return "".join(
+            random.choice(string.ascii_letters) for _ in range(length)
+        )
+
+    @classmethod
+    def next_time(cls) -> time:
+        return time(
+            hour=random.randint(0, 23),
+            minute=random.randint(0, 59),
+            second=random.randint(0, 59),
+        )
+
+    @classmethod
+    def next_timedelta(cls) -> timedelta:
+        return timedelta(
+            days=random.randint(1, 7),
+            hours=random.randint(1, 23),
+            minutes=random.randint(0, 59),
+        )
+
+    @classmethod
+    def next_uuid(cls) -> uuid.UUID:
+        return uuid.uuid4()
diff --git a/tests/testing/__init__.py b/tests/testing/__init__.py
diff --git a/tests/testing/test_model_builder.py b/tests/testing/test_model_builder.py
diff --git a/tests/testing/test_random_builder.py b/tests/testing/test_random_builder.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+from piccolo.testing.model_builder import ModelBuilder`
	`2`	`+`
	`3`	`+__all__ = ["ModelBuilder"]`