Home

Lute API proposal

There are any number of activities a user might like to do without interacting directly with the UI:

Get version and configuration data for a bug report
Create a backup for export to another device
Import a backup from another device
Load a new story from a file or URL or from the output of another command
Load term entries from a file or the output of another command
Export stories and terms and generate a list of most and/or least familiar terms
Export a story and generate Anki cards, audio with https://pypi.org/project/gTTS/, etc.
Run a cron job that checks usage statistics and sends a notification if there has been no recent activity.

In order of importance:

All permutations of:

Include docstrings for each function, method, class, and module; ideally with examples.
Use python-style naming for functions, methods, and class names (e.g. "my_useful_function", NOT "myUsefulFunction").
Report success/failure of each operation, use custom exceptions if warranted.
Add type versioning where possible, compatible with lowest supported python version.
Security: guard against SQL injection.

TODO -- separate scripts, e.g. lute, lute-xxx, lute-yyy, or one script with subcommands like git? The separate scripts approach makes additional capabilities discoverable with command-completion. The subcommand approach makes them discoverable with lute help but provides a cluttered interface.
Include a --help option for each command, ideally with examples.
Use consistent CLI options -- For example, don't add a --debug option to one command and a --verbose option to another if they both do the same thing.
Use exit codes to report CLI command status: 0 for success, 1 for command error, 129 or higher for termination by signal.
Handle BrokenPipeErrors properly in CLI commands -- see https://docs.python.org/3/library/signal.html#note-on-sigpipe.

Is SQLite concurrency control adequate for all use cases where the API is being executed through a different process than the running Lute flask application?
How stable is the data model? Is now the right time to expose an API?

To install scripts, add entries to project.scripts section of pyproject.toml
1. Current script entry is lute = "lute.main:start" but lute/main.py only defines a _start method, what's going on?
To install to current python environment (likely virtualenv) use flit install command (see https://flit.pypa.io/en/latest/cmdline.html) or just pip install .