Merge pull request #128 from level12/124-component-structure

introduce a component scheme

Author: guruofgentoo

keg/__init__.py

@@ -1,9 +1,20 @@
 from __future__ import absolute_import
 
-from flask import current_app
+from flask import current_app  # noqa: F401
 
-from keg.app import Keg
+from keg.app import Keg  # noqa: F401
+from keg.component import (  # noqa: F401
+    KegComponent,
+    KegModelComponent,
+    KegModelViewComponent,
+    KegViewComponent,
+)
 
-# silence linter
-current_app
-Keg
+__all__ = [
+    'Keg',
+    'KegComponent',
+    'KegModelComponent',
+    'KegModelViewComponent',
+    'KegViewComponent',
+    'current_app',
+]

keg/app.py

@@ -1,5 +1,6 @@
 from __future__ import absolute_import
 
+import importlib
 import warnings
 
 import flask
@@ -135,6 +136,12 @@ def init_keyring(self):
     def init_extensions(self):
         self.init_db()
 
+        # Keg components are essentially flask extensions, so they need to be set up during the
+        # init process. Being extensions, it makes sense to trigger this here. But, they will best
+        # be set up at the end of the init process, because other app-specific extensions may be
+        # set up in `on_init_complete` for error handling/notifications and the like.
+        signals.init_complete.connect(self.init_registered_components, sender=self)
+
     def db_manager_cls(self):
         from keg.db import DatabaseManager
         return DatabaseManager
@@ -144,6 +151,16 @@ def init_db(self):
             cls = self.db_manager_cls()
             self.db_manager = cls(self)
 
+    def init_registered_components(self, app):
+        # KEG_REGISTERED_COMPONENTS is presumed to be a set/list/iterable of dotted paths usable
+        # for import. At the top level of the imported path, there should be a `__component__`
+        # that takes the dotted path that was used for import (as an absolute parent for relative
+        # imports) and has an init_app. Ideally, based on KegComponent.
+        for comp_path in self.config.get('KEG_REGISTERED_COMPONENTS', set()):
+            comp_module = importlib.import_module(comp_path)
+            comp_object = getattr(comp_module, '__component__')
+            comp_object.init_app(self, parent_path=comp_path)
+
     def init_blueprints(self):
         # TODO: probably want to be selective about adding our blueprint
         self.register_blueprint(kegbp)

keg/component.py

@@ -0,0 +1,121 @@
+import importlib
+
+import flask
+
+
+class KegComponent:
+    """ Keg components follow the paradigm of flask extensions, and provide some defaults for the
+    purpose of setting up model/view structure. Using components, a project may be broken down into
+    logical blocks, each having their own entities, blueprints, templates, tests, etc.
+
+    Setup involves:
+    - KEG_REGISTERED_COMPONENTS config setting: assumed to be an iterable of importable dotted paths
+    - `__component__`: at the top level of each dotted path, this attribute should point to an
+    instance of `KegComponent`. E.g. `__component__ = KegComponent('widgets')`
+
+    By default, components will load entities from `db_visit_modules` into metadata and register
+    any blueprints specified by `load_blueprints`.
+
+    Blueprints can be created with the helper methods `create_named_blueprint` or `create_blueprint`
+    in order to have a configured template folder relative to the blueprint path.
+
+    Use KegModelComponent, KegViewComponent, or KegModelViewComponent for some helpful defaults for
+    model/blueprint discovery.
+
+    db_visit_modules: an iterable of dotted paths (e.g. `.mycomponent.entities`,
+                      `app.component.extraentities`) where Keg can find the entities for this
+                      component to load them into the metadata.
+
+    .. note:: Normally this is not explicitly required but can be useful in cases where imports
+       won't reach that file.
+
+    .. note:: This can accept relative dotted paths (starts with `.`) and it will prepend the
+       component python package determined by Keg when instantiating the component. You can also
+       pass absolute dotted paths and no alterations will be performed.
+
+    load_blueprints: an iterable of tuples, each having a dotted path (e.g. `.mycomponent.views`,
+                     `app.component.extraviews`) and the blueprint attribute name to load and
+                     register on the app. E.g. `(('.views', 'component_bp'), )`
+
+    .. note:: This can accept relative dotted paths (starts with `.`) and it will prepend the
+       component python package determined by Keg when instantiating the component. You can also
+       pass absolute dotted paths and no alterations will be performed.
+
+    template_folder: string to be passed for template config to blueprints created via the component
+    """
+    db_visit_modules = tuple()
+    load_blueprints = tuple()
+    template_folder = 'templates'
+
+    def __init__(self, name, app=None, db_visit_modules=None, load_blueprints=None,
+                 template_folder=None, parent_path=None):
+        self.name = name
+        # Allow customization of the defaults in the constructor
+        self.db_visit_modules = db_visit_modules or self.db_visit_modules
+        self.load_blueprints = load_blueprints or self.load_blueprints
+        self.template_folder = template_folder or self.template_folder
+        if app:
+            # Not really intended to be used this way, but it fits the flask extension paradigm
+            # and could conceivably be set up in lieu of KEG_REGISTERED_COMPONENTS
+            self.init_app(app, parent_path=parent_path)
+
+    def init_app(self, app, parent_path=None):
+        # parent_path gets used as an absolute parent for the relative import paths of
+        # model/blueprints.
+        # E.g. if relative_dotted_path is `my_app.components.widget` and one of the relative import
+        # paths is `.model.entities`, the full import is `my_app.components.widget.model.entities`
+        self.init_config(app)
+        self.init_db(parent_path)
+        self.init_blueprints(app, parent_path)
+
+    def init_config(self, app):
+        # Components may define their own config defaults
+        pass
+
+    def init_db(self, parent_path):
+        # Intent is to import the listed modules, so their entities are registered in metadata
+        for dotted_path in self.db_visit_modules:
+            import_name = dotted_path
+            if import_name.startswith('.'):
+                import_name = f'{parent_path}{dotted_path}'
+            importlib.import_module(import_name)
+
+    def init_blueprints(self, app, parent_path):
+        # Register any blueprints that are listed by path in load_blueprints
+        for bp_path, bp_attr in self.load_blueprints:
+            import_name = bp_path
+            if import_name.startswith('.'):
+                import_name = f'{parent_path}{bp_path}'
+            mod_imported = importlib.import_module(import_name)
+            app.register_blueprint(getattr(mod_imported, bp_attr))
+
+    def create_blueprint(self, *args, **kwargs):
+        # Make a flask blueprint having a template folder configured
+        kwargs['template_folder'] = kwargs.get('template_folder', self.template_folder)
+        bp = flask.Blueprint(*args, **kwargs)
+
+        return bp
+
+    def create_named_blueprint(self, *args, **kwargs):
+        # Make a flask blueprint named with the component name, having a template folder configured
+        return self.create_blueprint(self.name, *args, **kwargs)
+
+
+class ModelMixin:
+    db_visit_modules = ('.model.entities', )
+
+
+class ViewMixin:
+    load_blueprints = (('.views', 'component_bp'), )
+
+
+class KegModelComponent(ModelMixin, KegComponent):
+    pass
+
+
+class KegViewComponent(ViewMixin, KegComponent):
+    pass
+
+
+class KegModelViewComponent(ModelMixin, ViewMixin, KegComponent):
+    pass

keg/tests/test_db.py

@@ -7,6 +7,9 @@
 from keg.signals import db_init_pre, db_init_post, db_clear_post, db_clear_pre
 from keg.testing import invoke_command
 
+# Note: we do not want to import Blog directly here. Doing so will affect metadata collection and
+# prevent the tests below from proving that component initialization is loading the model.
+# from keg_apps.db.blog.model.entities import Blog
 import keg_apps.db.model.entities as ents
 from keg_apps.db.app import DBApp
 from keg_apps.db2 import DB2App
@@ -27,11 +30,14 @@ def setup_class(cls):
         DBApp.testing_prep()
 
     def test_primary_db_entity(self):
-        assert ents.Blog.query.count() == 0
-        blog = ents.Blog(title=u'foo')
+        # importing Blog here to ensure we're importing after app init, which will only succeed if
+        # the component has loaded properly
+        from keg_apps.db.blog.model.entities import Blog
+        assert Blog.query.count() == 0
+        blog = Blog(title=u'foo')
         db.session.add(blog)
         db.session.commit()
-        assert ents.Blog.query.count() == 1
+        assert Blog.query.count() == 1
 
     def test_postgres_bind_db_entity(self):
         assert ents.PGDud.query.count() == 0
@@ -63,6 +69,10 @@ def setup_class(cls):
         DBApp.testing_prep()
 
     def test_db_init_with_clear(self):
+        # importing Blog here to ensure we're importing after app init, which will only succeed if
+        # the component has loaded properly
+        from keg_apps.db.blog.model.entities import Blog
+
         # have to use self here to enable the inner functions to adjust an outer-context variable
         self.init_pre_connected = False
         self.init_post_connected = False
@@ -85,8 +95,8 @@ def catch_clear_pre(app):
         def catch_clear_post(app):
             self.clear_post_connected = True
 
-        ents.Blog.testing_create()
-        assert ents.Blog.query.count() >= 1
+        Blog.testing_create()
+        assert Blog.query.count() >= 1
         ents.PGDud2.testing_create()
         assert ents.PGDud2.query.count() >= 1
 
@@ -95,9 +105,9 @@ def catch_clear_post(app):
         # todo: We could check all the intermediate steps, but this is more a functional test
         # for now.  If the record is gone and we can create an new blog post, then we assume the
         # clear and init went ok.
-        assert ents.Blog.query.count() == 0
-        ents.Blog.testing_create()
-        assert ents.Blog.query.count() == 1
+        assert Blog.query.count() == 0
+        Blog.testing_create()
+        assert Blog.query.count() == 1
 
         assert self.init_pre_connected
         assert self.init_post_connected

keg/tests/test_web.py

@@ -30,3 +30,11 @@ def test_blueprint_url_prefix(self):
     def test_blueprint_template_folder(self):
         resp = self.testapp.get('/tanagra/blueprint-test')
         assert 'blueprint template found ok' in resp
+
+
+class TestComponentBlueprint(WebBase):
+    appcls = WebApp
+
+    def test_component_blueprint_loads(self):
+        resp = self.testapp.get('/blog')
+        assert 'I am a blog' in resp

keg_apps/db/blog/__init__.py

@@ -0,0 +1,4 @@
+from keg import KegModelComponent
+
+
+__component__ = KegModelComponent('blog')

keg_apps/db/blog/model/__init__.py

@@ -0,0 +1,17 @@
+from blazeutils.strings import randchars
+
+from keg.db import db
+
+
+class Blog(db.Model):
+    __tablename__ = 'blogs'
+
+    id = db.Column(db.Integer, primary_key=True)
+    title = db.Column(db.Unicode(50), unique=True, nullable=False)
+
+    @classmethod
+    def testing_create(cls):
+        blog = Blog(title=randchars())
+        db.session.add(blog)
+        db.session.commit()
+        return blog

keg_apps/db/blog/model/entities.py

@@ -2,6 +2,10 @@
 class DefaultProfile(object):
     KEG_KEYRING_ENABLE = False
 
+    KEG_REGISTERED_COMPONENTS = {
+        'keg_apps.db.blog',
+    }
+
 
 class TestProfile(object):
     KEG_DB_DIALECT_OPTIONS = {

keg_apps/db/config.py

@@ -3,20 +3,6 @@
 from keg.db import db
 
 
-class Blog(db.Model):
-    __tablename__ = 'blogs'
-
-    id = db.Column(db.Integer, primary_key=True)
-    title = db.Column(db.Unicode(50), unique=True, nullable=False)
-
-    @classmethod
-    def testing_create(cls):
-        blog = Blog(title=randchars())
-        db.session.add(blog)
-        db.session.commit()
-        return blog
-
-
 ####
 # The next several entities exist to facilitate testing of the way Keg handles multiple database
 # binds and dialects.