extended inforation about code generated with sqlacodegen

README.md

@@ -2,11 +2,13 @@
 
 ## Configuration
 
-The file `.flaskenv` contains the default configuration. Flask reads the file at startup and adds the contained key-value-pairs as environment variables to the runtime environment. When the Flask app object is being created in `__init__.py`, all environment variables that start with the prefix "FLASK_" are added to the app configuration. This is true for any prefixed environment variable, not just the ones from `.flaskenv`.
+The file `.flaskenv` contains the default configuration. Flask reads the file at startup and adds its key-value-pairs to the runtime environment as environment variables. When the Flask app object is being created in `__init__.py`, all environment variables that start with the prefix "FLASK_" get added to the app configuration. 
 
-Configuration values can be overridden by passing another config file to Flask via the `-e` command line switch. It will be processed the same way as `.flaskenv`, which means that all keys must be prefixed with "FLASK_", and takes precedence over the default configuration.
+This is true for any prefixed environment variable, not just the ones from `.flaskenv`. It is therefore possible to set additional config parameters by hand before running the app. Just make sure to prefix the variable name with "FLASK_". 
 
-Finally, you can override config settings while instantiating the Flask app through the factory. To do this, simply pass a dictionary with the (unprefixed) override settings as named parameter `config` to the `create_app()` method. Settings passed this way take precedence over the default configuration and an optional config file. 
+Configuration values from the runtime environment can be overridden by using Flask's `-e` command line switch to pass a second config file to the app. This file gets processed the same way as `.flaskenv`, which means that all its keys must be prefixed with "FLASK_". These vars take precedence over the default configuration.
+
+Finally, you can override config settings with Python during  the Flask app's instantiation through the factory. To do this, simply pass a dictionary with (unprefixed) key-value-pairs to `create_app()` method as named parameter `config`. Settings passed this way take precedence over those from the default configuration and additional config files. 
 
 
 
@@ -35,6 +37,7 @@ python-dotenv
 Pillow
 pytest
 flask-debugtoolbar (optional)
+sqlacodegen (optional; only ever used from the command line during development)
 
 ### CSS and Javascript
 
@@ -50,6 +53,17 @@ some icons from heroicons.com
 
 ## Other useful stuff
 
+### Generate SQLAlchemy code from an existing database  
+
+Right now the_works reflects an existing database in order to infer the underlying data models for SQLAlchemy. Of course, this only works if all the tables already exist in the database. If the_works is run with an empty database (this happens when running tests, for example), the app will create fresh tables in the database. The necessary information about the tables can be generated from an existing database with the help of [sqlacodegen](https://pypi.org/project/sqlacodegen/). Just run this command inside the project's root directory:
+
+`sqlacodegen --generator tables sqlite:///path/to/good/db.sqlite > ./the_works/tables.py`
+
+The tool sqlacodegen can also generate Python code declaring the data models directly. This would make the use of reflection obsolete. The command would be: 
+
+`sqlacodegen --generator declarative sqlite:///path/to/good/db.sqlite > outputfile.py`
+
+
 ### Export database schema
 
 Method 1: `sqlite3 the_works.sqlite .schema > outputfile.sql` 
@@ -61,13 +75,6 @@ Method 2: Open DB in SQLitebrowser and use File -> Export -> Database to SQL fil
 * overwrite old schema (DROP TABLE, then CREATE TABLE)
 
 
-### Generate declarative SQLAlchemy code 
-
-Right now the_works reflects an existing database in order to infer the underlying data models for SQLAlchemy. If I wanted to declare the data models directly instead of using reflection, I would need declarative code. This code can be generated from an existing database with the help of [sqlacodegen](https://pypi.org/project/sqlacodegen/):
-
-`sqlacodegen sqlite:///path/to/db.sqlite > outputfile.py`
-
-
 ### Generate `requirements.txt`
 
 I use [pipreqs](https://pypi.org/project/pipreqs/) to generate the file `requirements.txt`. The package scans all source files for import statements and uses those to extract all required Pip packages.   

the_works/tables.py

@@ -1,4 +1,4 @@
-# file created via `sqlacodegen --generator tables sqlite:///path/to/the_works.sqlite > tables.py` 
+# this is the verbatim output of `sqlacodegen --generator tables sqlite:///path/to/the_works.sqlite`, run inside project root 
 
 from sqlalchemy import Column, ForeignKey, Integer, LargeBinary, MetaData, Table, Text