more readme and env var substitutions

HISTORY.rst

@@ -6,7 +6,9 @@ History
 0.1.1 (2017-01-06)
 ------------------
 * fix template variables so ``settings.yml`` include db connection settings and ``requirements.txt`` is correct
-* fix ``requirements.txt`` template to be compatible with pyup.
+* fix ``requirements.txt`` template to be compatible with pyup
+* add basic help to readme
+* allow environment variable substitution into settings
 
 0.1.0 (2017-01-05)
 ------------------

aiohttp_devtools/start/template/README.md

@@ -3,4 +3,10 @@
 
 Your new web app is ready to go!
 
-**TODO**: how to run it.
+To run your app you'll need to:
+1. Activate a python 3.5 or 3.6 environment
+2. Install the required packages with `pip install -r requirements.txt`
+3. Make sure the app's settings are configured correctly (see `settings.yml`). You can also
+ use environment variables to define sensitive settings, eg. DB connection variables
+4. You can then run your app during development with `adev runserver .`
+

aiohttp_devtools/start/template/app/main.py

@@ -1,8 +1,9 @@
+import os
 from pathlib import Path
 
 from aiohttp import web
 # {% if database.is_pg_sqlalchemy %}
-from aiopg.sa.engine import _create_engine
+from aiopg.sa import create_engine
 from sqlalchemy.engine.url import URL
 # {% endif %}
 
@@ -29,10 +30,11 @@
 
 THIS_DIR = Path(__file__).parent
 BASE_DIR = THIS_DIR.parent
-SETTINGS_FILE = BASE_DIR / 'settings.yml'
+SETTINGS_FILE = BASE_DIR / 'settings.yml'  # type: Path
 
 DEV_DICT = t.Dict()
 DEV_DICT.allow_extra('*')
+ENV_PREFIX = 'APP_'
 
 SETTINGS_STRUCTURE = t.Dict({
     # the "dev" dictionary contains information used by aiohttp-devtools to serve your app locally
@@ -56,13 +58,48 @@
 })
 
 
+def substitute_environ(s_dict: dict, prefix: str) -> dict:
+    """
+    Substitute environment variables into a settings dict.
+
+    Names are searched hierarchically with underscores representing levels, environment variables must be
+    capitalised.
+
+    For sample lets say we have ` {'foo': 'bar', 'subdict': {'value': 123}}` with prefix 'APP_',
+    the environment variable "APP_FOO = spam" would replace "bar" and "APP_SUBDICT_VALUE = 3"
+    would be converted to int and replace 123 in the dict.
+
+    :param: s_dict: dict to replace values in
+    :param: prefix: required prefix for environment variables to
+    :return: modified dict
+    """
+    for key, value in s_dict.items():
+        if isinstance(value, dict):
+            s_dict[key] = substitute_environ(value, prefix + key + '_')
+        elif isinstance(value, dict):
+            # doesn't make sense, we can't do anything here
+            pass
+        else:
+            env_var = os.getenv((prefix + key).upper(), None)
+            if env_var is not None:
+                # basic attempt to convert the new value to match the original type
+                if isinstance(value, int):
+                    s_dict[key] = int(env_var)
+                else:
+                    # are there any other types we might need to cope with here?
+                    s_dict[key] = env_var
+    return s_dict
+
+
 def load_settings() -> dict:
     """
     Read settings.yml and, validation its content.
     :return: settings dict
     """
     settings_file = SETTINGS_FILE.resolve()
-    return read_and_validate(str(settings_file), SETTINGS_STRUCTURE)
+    settings = read_and_validate(str(settings_file), SETTINGS_STRUCTURE)
+    settings = substitute_environ(settings, ENV_PREFIX)
+    return settings
 
 # {% if template_engine.is_jinja %}
 
@@ -144,7 +181,7 @@ def pg_dsn(db_settings: dict) -> str:
 
 
 async def startup(app: web.Application):
-    app['pg_engine'] = await _create_engine(pg_dsn(app['database']), loop=app.loop)
+    app['pg_engine'] = await create_engine(pg_dsn(app['database']), loop=app.loop)
 
 
 async def cleanup(app: web.Application):

aiohttp_devtools/start/template/app/templates/messages.jinja

@@ -12,7 +12,7 @@
     {% endif %}
     <p>
       <label for="username">Your name:</label>
-      <input type="text" name="username" id="username" placeholder="fred blogs" value="{{ username }}">
+      <input type="text" name="username" id="username" placeholder="Fred Bloggs" value="{{ username }}">
       <label for="message">Message:</label>
       <input type="text" name="message" id="message" placeholder="hello there">
       <button type="submit">Post Message</button>

setup.cfg

@@ -1,7 +1,7 @@
 [tool:pytest]
 testpaths = tests
 addopts = --isort
-timeout = 5
+timeout = 8
 isort_ignore =
     aiohttp_devtools/start/template/*.py