1184 Be able to auto register apps (#1182)

* auto register apps

* update docs

* add tests

* move `get_app_identifier` out

* rename var to `app_module`

* fix test

* add docs for root

Author: dantownsend

docs/src/piccolo/projects_and_apps/piccolo_apps.rst

@@ -18,7 +18,7 @@ Run the following command within your project:
 
 .. code-block:: bash
 
-    piccolo app new my_app
+    piccolo app new my_app --register
 
 
 Where ``my_app`` is your new app's name. This will create a folder like this:
@@ -34,7 +34,8 @@ Where ``my_app`` is your new app's name. This will create a folder like this:
 
 
 It's important to register your new app with the ``APP_REGISTRY`` in
-``piccolo_conf.py``.
+``piccolo_conf.py``. If you used the ``--register`` flag, then this is done
+automatically. Otherwise, add it manually:
 
 .. code-block:: python
 
@@ -45,6 +46,18 @@ 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`.
 
+root
+~~~~
+
+By default the app is created in the current directory. If you want the app to
+be in a sub folder, you can use the ``--root`` option:
+
+.. code-block:: bash
+
+    piccolo app new my_app --register --root=./apps
+
+The app will then be created in the ``apps`` folder.
+
 -------------------------------------------------------------------------------
 
 AppConfig

piccolo/apps/app/commands/new.py

@@ -2,12 +2,15 @@
 
 import importlib
 import os
+import pathlib
 import sys
 import typing as t
 
 import black
 import jinja2
 
+from piccolo.conf.apps import PiccoloConfUpdater
+
 TEMPLATE_DIRECTORY = os.path.join(
     os.path.dirname(os.path.abspath(__file__)), "templates"
 )
@@ -30,7 +33,11 @@ def module_exists(module_name: str) -> bool:
         return True
 
 
-def new_app(app_name: str, root: str = "."):
+def get_app_module(app_name: str, root: str) -> str:
+    return ".".join([*pathlib.Path(root).parts, app_name, "piccolo_app"])
+
+
+def new_app(app_name: str, root: str = ".", register: bool = False):
     print(f"Creating {app_name} app ...")
 
     app_root = os.path.join(root, app_name)
@@ -69,8 +76,12 @@ def new_app(app_name: str, root: str = "."):
     with open(os.path.join(migrations_folder_path, "__init__.py"), "w"):
         pass
 
+    if register:
+        app_module = get_app_module(app_name=app_name, root=root)
+        PiccoloConfUpdater().register_app(app_module=app_module)
+
 
-def new(app_name: str, root: str = "."):
+def new(app_name: str, root: str = ".", register: bool = False):
     """
     Creates a new Piccolo app.
 
@@ -79,6 +90,8 @@ def new(app_name: str, root: str = "."):
     :param root:
         Where to create the app e.g. ./my/folder. By default it creates the
         app in the current directory.
+    :param register:
+        If True, the app is registered automatically in piccolo_conf.py.
 
     """
-    new_app(app_name=app_name, root=root)
+    new_app(app_name=app_name, root=root, register=register)

piccolo/conf/apps.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import ast
 import inspect
 import itertools
 import os
@@ -11,6 +12,8 @@
 from importlib import import_module
 from types import ModuleType
 
+import black
+
 from piccolo.apps.migrations.auto.migration_manager import MigrationManager
 from piccolo.engine.base import Engine
 from piccolo.table import Table
@@ -437,6 +440,17 @@ def get_piccolo_conf_module(
         else:
             return module
 
+    def get_piccolo_conf_path(self) -> str:
+        piccolo_conf_module = self.get_piccolo_conf_module()
+
+        if piccolo_conf_module is None:
+            raise ModuleNotFoundError("piccolo_conf.py not found.")
+
+        module_file_path = piccolo_conf_module.__file__
+        assert module_file_path
+
+        return module_file_path
+
     def get_app_registry(self) -> AppRegistry:
         """
         Returns the ``AppRegistry`` instance within piccolo_conf.
@@ -583,3 +597,88 @@ def get_table_classes(
             tables.extend(app_config.table_classes)
 
         return tables
+
+
+###############################################################################
+
+
+class PiccoloConfUpdater:
+
+    def __init__(self, piccolo_conf_path: t.Optional[str] = None):
+        """
+        :param piccolo_conf_path:
+            The path to the piccolo_conf.py (e.g. `./piccolo_conf.py`). If not
+            passed in, we use our ``Finder`` class to get it.
+        """
+        self.piccolo_conf_path = (
+            piccolo_conf_path or Finder().get_piccolo_conf_path()
+        )
+
+    def _modify_app_registry_src(self, src: str, app_module: str) -> str:
+        """
+        :param src:
+            The contents of the ``piccolo_conf.py`` file.
+        :param app_module:
+            The app to add to the registry e.g. ``'music.piccolo_app'``.
+        :returns:
+            Updated Python source code string.
+
+        """
+        ast_root = ast.parse(src)
+
+        parsing_successful = False
+
+        for node in ast.walk(ast_root):
+            if isinstance(node, ast.Call):
+                if (
+                    isinstance(node.func, ast.Name)
+                    and node.func.id == "AppRegistry"
+                ):
+                    if len(node.keywords) > 0:
+                        keyword = node.keywords[0]
+                        if keyword.arg == "apps":
+                            apps = keyword.value
+                            if isinstance(apps, ast.List):
+                                apps.elts.append(
+                                    ast.Constant(app_module, kind="str")
+                                )
+                                parsing_successful = True
+                                break
+
+        if not parsing_successful:
+            raise SyntaxError(
+                "Unable to parse piccolo_conf.py - `AppRegistry(apps=...)` "
+                "not found)."
+            )
+
+        new_contents = ast.unparse(ast_root)
+
+        formatted_contents = black.format_str(
+            new_contents, mode=black.FileMode(line_length=80)
+        )
+
+        return formatted_contents
+
+    def register_app(self, app_module: str):
+        """
+        Adds the given app to the ``AppRegistry`` in ``piccolo_conf.py``.
+
+        This is used by command line tools like:
+
+        .. code-block:: bash
+
+            piccolo app new my_app --register
+
+        :param app_module:
+            The module of the app, e.g. ``'music.piccolo_app'``.
+
+        """
+        with open(self.piccolo_conf_path) as f:
+            piccolo_conf_src = f.read()
+
+        new_contents = self._modify_app_registry_src(
+            src=piccolo_conf_src, app_module=app_module
+        )
+
+        with open(self.piccolo_conf_path, "wt") as f:
+            f.write(new_contents)

tests/apps/app/commands/test_new.py

@@ -3,7 +3,7 @@
 import tempfile
 from unittest import TestCase
 
-from piccolo.apps.app.commands.new import module_exists, new
+from piccolo.apps.app.commands.new import get_app_module, module_exists, new
 
 
 class TestModuleExists(TestCase):
@@ -43,3 +43,21 @@ def test_new_with_clashing_name(self):
                 "A module called sys already exists"
             )
         )
+
+
+class TestGetAppIdentifier(TestCase):
+
+    def test_get_app_module(self):
+        """
+        Make sure the the ``root`` argument is handled correctly.
+        """
+        self.assertEqual(
+            get_app_module(app_name="music", root="."),
+            "music.piccolo_app",
+        )
+
+        for root in ("apps", "./apps", "./apps/"):
+            self.assertEqual(
+                get_app_module(app_name="music", root=root),
+                "apps.music.piccolo_app",
+            )

tests/conf/test_apps.py

@@ -1,10 +1,17 @@
 from __future__ import annotations
 
 import pathlib
+import tempfile
 from unittest import TestCase
 
 from piccolo.apps.user.tables import BaseUser
-from piccolo.conf.apps import AppConfig, AppRegistry, Finder, table_finder
+from piccolo.conf.apps import (
+    AppConfig,
+    AppRegistry,
+    Finder,
+    PiccoloConfUpdater,
+    table_finder,
+)
 from tests.example_apps.mega.tables import MegaTable, SmallTable
 from tests.example_apps.music.tables import (
     Band,
@@ -310,3 +317,44 @@ def test_sort_app_configs(self):
         self.assertListEqual(
             [i.app_name for i in sorted_app_configs], ["app_2", "app_1"]
         )
+
+
+class TestPiccoloConfUpdater(TestCase):
+
+    def test_modify_app_registry_src(self):
+        """
+        Make sure the `piccolo_conf.py` source code can be modified
+        successfully.
+        """
+        updater = PiccoloConfUpdater()
+
+        new_src = updater._modify_app_registry_src(
+            src="APP_REGISTRY = AppRegistry(apps=[])",
+            app_module="music.piccolo_app",
+        )
+        self.assertEqual(
+            new_src.strip(),
+            'APP_REGISTRY = AppRegistry(apps=["music.piccolo_app"])',
+        )
+
+    def test_register_app(self):
+        """
+        Make sure the new contents get written to disk.
+        """
+        temp_dir = tempfile.gettempdir()
+        piccolo_conf_path = pathlib.Path(temp_dir) / "piccolo_conf.py"
+
+        src = "APP_REGISTRY = AppRegistry(apps=[])"
+
+        with open(piccolo_conf_path, "wt") as f:
+            f.write(src)
+
+        updater = PiccoloConfUpdater(piccolo_conf_path=str(piccolo_conf_path))
+        updater.register_app(app_module="music.piccolo_app")
+
+        with open(piccolo_conf_path) as f:
+            contents = f.read().strip()
+
+        self.assertEqual(
+            contents, 'APP_REGISTRY = AppRegistry(apps=["music.piccolo_app"])'
+        )