the_works/README.md

the_works – a publication management tool for writers

This software project

• supports managing texts and publications with multiple languages, pseudonyms, genres, publishers, series, editions, and more
• supports storage of cover images
• focuses on ease-of-use, safety, and speed
• written and field-tested by an actual writer

the_works also is

• based on common technologies like Python, SQL, and HTML/JavaScript
• underlying frameworks are Flask and SQLAlchemy
• includes test coverage (using pytest)

Configuration

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.

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_".

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.

Flask commands

Execute commands with python -m flask <command>. You don't need to specify --app the_works as long as the environment variable "FLASK_APP" is set to "the_works"; the default configuration file does this.

Available commands:

• run: Serve app (don't use for production).

• shell: start a shell within the app context (I can i.e. import specific table models and test ORM data structures)

Dependencies

Python Packages

Required pip packages

• flask
• flask-sqlalchemy
• python-dotenv
• Pillow
• pytest

Optional pip packages

• flask-debugtoolbar (optional)
• sqlacodegen (optional; only used from the command line during development)

CSS and Javascript resources

• any regular (not classless) stylesheet from PicoCSS for general styling
• SwitchColorMode.js from Yohn's fork of PicoCSS to enable color mode switching
• DataTables (JS and CSS components) to enable ordering and filtering result tables
  • DataTables requires jQuery, which can either be bundled with DataTables itself or installed as a separate resource

Icons

some icons from heroicons.com

Other useful stuff

Export database schema

Method 1: sqlite3 the_works.sqlite .schema > outputfile.sql

Method 2: Open DB in SQLitebrowser and use File -> Export -> Database to SQL file …

• keep original CREATE statements
• export schema only
• overwrite old schema (DROP TABLE, then CREATE TABLE)

Generate requirements.txt

I use 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. See pipreqs -h for usage info.

Outdated: Generate SQLAlchemy code from an existing database

Right now In earlier stages, 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. 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