added table_finder

Author: dantownsend

docs/src/piccolo/projects_and_apps/piccolo_apps.rst

@@ -1,16 +1,20 @@
 .. _PiccoloApps:
 
+############
 Piccolo Apps
-============
+############
 
 By leveraging Piccolo apps you can:
 
- * Modularise your code.
- * Share your apps with other Piccolo users.
- * Unlock some useful functionality like auto migrations.
+* Modularise your code.
+* Share your apps with other Piccolo users.
+* Unlock some useful functionality like auto migrations.
 
+-------------------------------------------------------------------------------
+
+***************
 Creating an app
----------------
+***************
 
 Run the following command within your project:
 
@@ -19,7 +23,7 @@ Run the following command within your project:
     piccolo app new my_app
 
 
-This will create a folder like this:
+Where `my_app` is your new app's name. This will create a folder like this:
 
 .. code-block:: bash
 
@@ -43,8 +47,11 @@ It's important to register your new app with the ``APP_REGISTRY`` in
 Anytime you invoke the `piccolo` command, you will now be able to perform
 operations on your app, such as :ref:`Migrations`.
 
+-------------------------------------------------------------------------------
+
+*********
 AppConfig
----------
+*********
 
 Inside your app's `piccolo_app.py` file is an ``AppConfig`` instance. This is
 how you customise your app's settings.
@@ -75,7 +82,7 @@ how you customise your app's settings.
     )
 
 app_name
-~~~~~~~~
+========
 
 This is used to identify your app, when using the `piccolo` CLI, for example:
 
@@ -84,24 +91,55 @@ This is used to identify your app, when using the `piccolo` CLI, for example:
     piccolo migrations forwards blog
 
 migrations_folder_path
-~~~~~~~~~~~~~~~~~~~~~~
+======================
 
 Specifies where your app's migrations are stored. By default, a folder called
 `piccolo_migrations` is used.
 
 table_classes
-~~~~~~~~~~~~~
+=============
+
+Use this to register your app's ``Table`` subclasses. This is important for
+auto migrations (see :ref:`Migrations`).
+
+You can register them manually, see the example above, or can use
+``table_finder``.
+
+table_finder
+------------
+
+Instead of manually registering ``Table`` subclasses, you can use
+``table_finder`` to automatically import any ``Table`` subclasses from a given
+list of modules.
+
+.. code-block:: python
+
+    from piccolo.conf.apps import table_finder
+
+    APP_CONFIG = AppConfig(
+        app_name='blog',
+        migrations_folder_path=os.path.join(CURRENT_DIRECTORY, 'piccolo_migrations'),
+        table_classes=table_finder(modules=['blog.tables']),
+        migration_dependencies=[],
+        commands=[]
+    )
+
+The module path should be from the root of the project (the same directory as
+your ``piccolo_conf.py`` file, rather than a relative path).
+
+.. currentmodule:: piccolo.conf.apps
+
+.. autofunction:: table_finder
 
-Use this to register your app's tables. This is important for auto migrations (see :ref:`Migrations`).
 
 migration_dependencies
-~~~~~~~~~~~~~~~~~~~~~~
+======================
 
 Used to specify other Piccolo apps whose migrations need to be run before the
 current app's migrations.
 
 commands
-~~~~~~~~
+========
 
 You can register functions and coroutines, which are automatically added to
 the `piccolo` CLI.
@@ -155,8 +193,11 @@ app.
 Piccolo itself is bundled with several apps - have a look at the source code
 for inspiration.
 
+-------------------------------------------------------------------------------
+
+************
 Sharing Apps
-------------
+************
 
 By breaking up your project into apps, the project becomes more maintainable.
 You can also share these apps between projects, and they can even be installed

docs/src/piccolo/schema/column_types.rst

@@ -390,7 +390,7 @@ Example
 Type
 ====
 
-``UUID`` uses the ``UUID`` Python type for values.
+``UUID`` uses the ``UUID`` type for values.
 
 .. code-block:: python
 

piccolo/conf/apps.py

@@ -3,8 +3,58 @@
 from importlib import import_module
 import typing as t
 
-if t.TYPE_CHECKING:
-    from piccolo.table import Table
+from piccolo.table import Table
+
+
+def table_finder(
+    modules: t.Sequence[str],
+    include_tags: t.Sequence[str] = ["__all__"],
+    exclude_tags: t.Sequence[str] = [],
+) -> t.List[t.Type[Table]]:
+    """
+    Rather than explicitly importing and registering table classes with the
+    AppConfig, ``table_finder`` can be used instead. It imports any ``Table``
+    subclasses in the given modules. Tags can be used to limit which ``Table``
+    subclasses are imported.
+
+    :param modules:
+        The module paths to check for ``Table`` subclasses. For example,
+        ['blog.tables']. The path should be from the root of your project,
+        not a relative path.
+    :param include_tags:
+        If the ``Table`` subclass has one of these tags, it will be
+        imported. The special tag '__all__' will import all ``Table``
+        subclasses found.
+    :param exclude_tags:
+        If the ``Table`` subclass has any of these tags, it won't be
+        imported. `exclude_tags` overrides `include_tags`.
+
+    """
+    table_subclasses: t.List[t.Type[Table]] = []
+
+    for module_path in modules:
+        try:
+            module = import_module(module_path)
+        except ImportError as exception:
+            print(f"Unable to import {module_path}")
+            raise exception
+
+        object_names = [i for i in dir(module) if not i.startswith("_")]
+
+        for object_name in object_names:
+            _object = getattr(module, object_name)
+            if issubclass(_object, Table) and _object is not Table:
+                table: Table = _object
+                if exclude_tags and set(table._meta.tags).intersection(
+                    set(exclude_tags)
+                ):
+                    continue
+                elif "__all__" in include_tags:
+                    table_subclasses.append(_object)
+                elif set(table._meta.tags).intersection(set(include_tags)):
+                    table_subclasses.append(_object)
+
+    return table_subclasses
 
 
 @dataclass

piccolo/table.py

@@ -40,6 +40,7 @@ class TableMeta:
     default_columns: t.List[Column] = field(default_factory=list)
     non_default_columns: t.List[Column] = field(default_factory=list)
     foreign_key_columns: t.List[ForeignKey] = field(default_factory=list)
+    tags: t.List[str] = field(default_factory=list)
     _db: t.Optional[Engine] = None
 
     # Records reverse foreign key relationships - i.e. when the current table
@@ -97,7 +98,7 @@ def __init_subclass__(
         cls,
         tablename: t.Optional[str] = None,
         db: t.Optional[Engine] = None,
-        app: t.Optional[str] = None,
+        tags: t.List[str] = [],
     ):
         """
         Automatically populate the _meta, which includes the tablename, and
@@ -133,7 +134,7 @@ def __init_subclass__(
 
                 if isinstance(column, PrimaryKey):
                     # We want it at the start.
-                    columns = [column] + columns
+                    columns = [column] + columns  # type: ignore
                     default_columns.append(column)
                 else:
                     columns.append(column)
@@ -152,6 +153,7 @@ def __init_subclass__(
             default_columns=default_columns,
             non_default_columns=non_default_columns,
             foreign_key_columns=foreign_key_columns,
+            tags=tags,
             _db=db,
         )
 

tests/conf/test_apps.py

@@ -1,8 +1,57 @@
 from unittest import TestCase
 
-from piccolo.conf.apps import AppRegistry
+from piccolo.conf.apps import AppRegistry, AppConfig, table_finder
 
 
 class TestAppRegistry(TestCase):
     def test_init(self):
-        AppRegistry()
+        app_registry = AppRegistry(apps=["piccolo.apps.user.piccolo_app"])
+        app_config = app_registry.get_app_config(app_name="user")
+        self.assertTrue(isinstance(app_config, AppConfig))
+
+
+class TestTableFinder(TestCase):
+    def test_table_finder(self):
+        """
+        Should return all Table subclasses.
+        """
+        tables = table_finder(modules=["tests.example_project.tables"])
+
+        table_class_names = [i.__name__ for i in tables]
+        table_class_names.sort()
+
+        self.assertEqual(
+            table_class_names,
+            ["Band", "Concert", "Manager", "Poster", "Ticket", "Venue"],
+        )
+
+    def test_include_tags(self):
+        """
+        Should return all Table subclasses with a matching tag.
+        """
+        tables = table_finder(
+            modules=["tests.example_project.tables"], include_tags=["special"]
+        )
+
+        table_class_names = [i.__name__ for i in tables]
+        table_class_names.sort()
+
+        self.assertEqual(
+            table_class_names, ["Poster"],
+        )
+
+    def test_exclude_tags(self):
+        """
+        Should return all Table subclasses without the specified tags.
+        """
+        tables = table_finder(
+            modules=["tests.example_project.tables"], exclude_tags=["special"]
+        )
+
+        table_class_names = [i.__name__ for i in tables]
+        table_class_names.sort()
+
+        self.assertEqual(
+            table_class_names,
+            ["Band", "Concert", "Manager", "Ticket", "Venue"],
+        )

tests/example_project/tables.py

@@ -35,5 +35,9 @@ class Ticket(Table):
     price = Numeric(digits=(5, 2))
 
 
-class Poster(Table):
+class Poster(Table, tags=["special"]):
+    """
+    Has tags for tests which need it.
+    """
+
     content = Text()