diff options
Diffstat (limited to 'webmentions_ssg/cli.py')
| -rw-r--r-- | webmentions_ssg/cli.py | 31 |
1 files changed, 26 insertions, 5 deletions
diff --git a/webmentions_ssg/cli.py b/webmentions_ssg/cli.py index 7a68651..5c2d534 100644 --- a/webmentions_ssg/cli.py +++ b/webmentions_ssg/cli.py @@ -21,7 +21,12 @@ USERS_CLI = AppGroup("users", help="Manage users.") def _require_user(username: str): - """Return a user by username or report a CLI-friendly error.""" + """Return a user by username or report a CLI-friendly error. + + :param username: Username to look up in the database. + :returns: Matching user record. + :raises click.ClickException: If no matching username exists. + """ user = db.session.scalar(sa.select(User).where(User.username == username)) if user is None: raise click.ClickException(f"User {username!r} does not exist.") @@ -59,7 +64,10 @@ def create_user(username: str, password: str) -> None: @USERS_CLI.command("list", help="List registered users.") def list_users() -> None: - """List user IDs and usernames in alphabetical order.""" + """List user IDs and usernames in alphabetical order. + + Write either a sorted ID/username table or a message if no accounts exist. + """ users = db.session.scalars(sa.select(User).order_by(User.username)).all() if not users: click.echo("No users found.") @@ -155,14 +163,22 @@ DB_CLI = AppGroup("db", help="Handle database") def _table_names() -> set[str]: - """Return existing table names without modifying the database schema.""" + """Return existing table names without modifying the database schema. + + :returns: Names of tables in the configured database. + """ with db.engine.connect() as connection: return set(inspect(connection).get_table_names()) @DB_CLI.command("create-db", help="Create a new database using all migrations") def create_db() -> None: - """Initialize an empty database and record its Alembic revision.""" + """Initialize an empty database and record its Alembic revision. + + Refuse to initialize a nonempty schema, then run the complete Alembic upgrade chain. + + :raises click.ClickException: If the database already contains tables. + """ if _table_names(): raise click.ClickException( "The database already contains tables. " @@ -176,7 +192,12 @@ def create_db() -> None: @DB_CLI.command("upgrade", help="Upgrade an existing database to the latest revision") def upgrade_db() -> None: - """Apply pending migrations to a previously initialized database.""" + """Apply pending migrations to a previously initialized database. + + Require a previously migrated schema before applying pending Alembic revisions. + + :raises click.ClickException: If the database has no Alembic revision table. + """ if "alembic_version" not in _table_names(): raise click.ClickException( "No Flask-Migrate revision table found. " |
