From 968e1b4e4a6fbd5a15037cdb11a3f9dee5108570 Mon Sep 17 00:00:00 2001 From: Dennis Fink Date: Sat, 14 Nov 2026 18:44:23 +0100 Subject: docs(core): standardize reST docstrings Expand function and method documentation with consistent reST parameter, return, and exception fields while clarifying behavior where additional context is useful. Normalize test and migration docstrings to the same documentation conventions. --- webmentions_ssg/cli.py | 31 ++++++++++++++++++++++++++----- 1 file changed, 26 insertions(+), 5 deletions(-) (limited to 'webmentions_ssg/cli.py') 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. " -- cgit v1.3.1