aboutsummaryrefslogtreecommitdiff
path: root/webmentions_ssg/cli.py
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--webmentions_ssg/cli.py31
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. "