3.2. Base Template

The Base Template is the foundation every project starts from — it’s a default template, included automatically whether you name it or not. It provides the Clean Architecture layout (see Layered Architecture for the internals), a working example (a User model with full CRUD), and the runtime that powers every other template.

3.2.1. A working project out of the box

A fresh project isn’t just an empty skeleton — it runs immediately:

  • A default in-memory database. Every project starts with a zero-dependency, in-process database adapter, so the example User CRUD works without installing or configuring anything. Install SQLAlchemy or MongoDB later to switch to a real one — the code that uses the database doesn’t need to change.

  • A default package manager (Poetry). Switch to Pipenv or uv any time — your existing dependencies convert automatically, nothing is lost. See Exclusive Templates.

  • Central configuration in config/app.toml — project name/version, environment, debug mode, log level, language, theme, and which database/package manager backs the generic defaults above.

3.2.2. Resilience and developer experience

  • Automatic recovery from missing dependencies. If a runner hits an import error for a package that isn’t installed yet, the framework installs it automatically (through whichever package manager the project is using) and retries — you don’t need to stop and run an install command by hand.

  • Consistent, themeable CLI output — a message printer with distinct styles for success, warning, error, critical, title, and info messages, so every template’s output looks and feels consistent.

  • The runner system — the interactive (or fully-scriptable) entry point every project uses to run its own code; see Runner Layer for how it works and how to add your own.

3.2.3. Learning the architecture by example

The generated User model, repository, use cases, and CLI presentation aren’t just filler — they’re a complete, working reference implementation of every layer described on the Layered Architecture pages, worth reading through before building your own.

3.2.4. Runners

Two runners ship with the base project, both in runners/main/:

  • python run app start starts the application’s own entry point and prints its name, version, environment and debug mode, read from config/app.toml and pyproject.toml.

  • python tools app show_informations prints the same application information, without starting anything. It’s the tool to use when checking the configuration.

  • python run user <method> works on the example User model:

    • python run user list lists every user.

    • python run user create username=anaclara creates a user.

    • python run user update id=1 username=anaclara renames a user.

    • python run user delete id=1 deletes a user.

Arguments can be passed as key=value. Runs are interactive by default: a missing value is asked for. Pass interactive=false for scripts and automation: then a missing or invalid argument stops the run with an error that names it (exit status 1), and confirmations take their default. Run without a command to choose from the interactive menu, if the prompt_toolkit template is installed.