Gather the CLI command modules into a commands sub-package

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

tools/docs/source/pop_fem_audit_tools.commands.rst

@@ -0,0 +1,53 @@
+pop\_fem\_audit\_tools.commands package
+=======================================
+
+Submodules
+----------
+
+pop\_fem\_audit\_tools.commands.build\_db module
+------------------------------------------------
+
+.. automodule:: pop_fem_audit_tools.commands.build_db
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+pop\_fem\_audit\_tools.commands.export\_llm\_input module
+---------------------------------------------------------
+
+.. automodule:: pop_fem_audit_tools.commands.export_llm_input
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+pop\_fem\_audit\_tools.commands.fetch\_artists module
+-----------------------------------------------------
+
+.. automodule:: pop_fem_audit_tools.commands.fetch_artists
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+pop\_fem\_audit\_tools.commands.fetch\_lyrics module
+----------------------------------------------------
+
+.. automodule:: pop_fem_audit_tools.commands.fetch_lyrics
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+pop\_fem\_audit\_tools.commands.run\_llm module
+-----------------------------------------------
+
+.. automodule:: pop_fem_audit_tools.commands.run_llm
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Module contents
+---------------
+
+.. automodule:: pop_fem_audit_tools.commands
+   :members:
+   :show-inheritance:
+   :undoc-members:

tools/docs/source/pop_fem_audit_tools.rst

@@ -1,17 +1,17 @@
 pop\_fem\_audit\_tools package
 ==============================
 
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   pop_fem_audit_tools.commands
+
 Submodules
 ----------
 
-pop\_fem\_audit\_tools.build\_db module
----------------------------------------
-
-.. automodule:: pop_fem_audit_tools.build_db
-   :members:
-   :show-inheritance:
-   :undoc-members:
-
 pop\_fem\_audit\_tools.config module
 ------------------------------------
 
@@ -28,30 +28,6 @@ pop\_fem\_audit\_tools.database module
    :show-inheritance:
    :undoc-members:
 
-pop\_fem\_audit\_tools.export\_llm\_input module
-------------------------------------------------
-
-.. automodule:: pop_fem_audit_tools.export_llm_input
-   :members:
-   :show-inheritance:
-   :undoc-members:
-
-pop\_fem\_audit\_tools.fetch\_artists module
---------------------------------------------
-
-.. automodule:: pop_fem_audit_tools.fetch_artists
-   :members:
-   :show-inheritance:
-   :undoc-members:
-
-pop\_fem\_audit\_tools.fetch\_lyrics module
--------------------------------------------
-
-.. automodule:: pop_fem_audit_tools.fetch_lyrics
-   :members:
-   :show-inheritance:
-   :undoc-members:
-
 pop\_fem\_audit\_tools.models module
 ------------------------------------
 
@@ -60,14 +36,6 @@ pop\_fem\_audit\_tools.models module
    :show-inheritance:
    :undoc-members:
 
-pop\_fem\_audit\_tools.run\_llm module
---------------------------------------
-
-.. automodule:: pop_fem_audit_tools.run_llm
-   :members:
-   :show-inheritance:
-   :undoc-members:
-
 pop\_fem\_audit\_tools.utils module
 -----------------------------------
 

tools/src/pop_fem_audit_tools/__main__.py

@@ -15,23 +15,23 @@ from collections.abc import Callable
 from importlib.machinery import ModuleSpec
 from types import ModuleType
 
-from pop_fem_audit_tools import (
-    build_db,
-    export_llm_input,
-    fetch_artists,
-    fetch_lyrics,
-    run_llm,
+from .commands import (
+    build_db_command,
+    export_llm_input_command,
+    fetch_artists_command,
+    fetch_lyrics_command,
+    run_llm_command,
 )
 
 MODULE_PROG: str = "python -m pop_fem_audit_tools"
 """The program name when run with ``python -m``."""
 
 SUBCOMMANDS: dict[str, Callable[[list[str] | None], int]] = {
-    "build-db": build_db.main,
-    "export-llm-input": export_llm_input.main,
-    "fetch-artists": fetch_artists.main,
-    "fetch-lyrics": fetch_lyrics.main,
-    "run-llm": run_llm.main,
+    "build-db": build_db_command,
+    "export-llm-input": export_llm_input_command,
+    "fetch-artists": fetch_artists_command,
+    "fetch-lyrics": fetch_lyrics_command,
+    "run-llm": run_llm_command,
 }
 """The dispatch table from the subcommand name to the tool main."""
 

tools/src/pop_fem_audit_tools/commands/__init__.py

@@ -0,0 +1,10 @@
+# Tools for A Feminist Audit of Pop Music.
+# Copyright 2026 imacat.  All rights reserved.
+# Authors:
+#   imacat@mail.imacat.idv.tw (imacat), 2026/8/4
+"""The registry of the CLI subcommands."""
+from .build_db import main as build_db_command
+from .export_llm_input import main as export_llm_input_command
+from .fetch_artists import main as fetch_artists_command
+from .fetch_lyrics import main as fetch_lyrics_command
+from .run_llm import main as run_llm_command

tools/src/pop_fem_audit_tools/commands/build_db.py

@@ -59,8 +59,8 @@ from typing import Any, Self
 import sqlalchemy as sa
 from sqlalchemy.orm import Session
 
-from .database import Base, ds
-from .models import (
+from ..database import Base, ds
+from ..models import (
     Artist,
     ChartEntry,
     Role,

tools/src/pop_fem_audit_tools/commands/export_llm_input.py

@@ -19,8 +19,8 @@ from pathlib import Path
 import sqlalchemy as sa
 from sqlalchemy.orm import Session
 
-from .database import ds
-from .models import Song
+from ..database import ds
+from ..models import Song
 
 
 def parse_args(argv: list[str] | None) -> argparse.Namespace:

tools/src/pop_fem_audit_tools/commands/fetch_artists.py

@@ -34,10 +34,10 @@ from typing import Any, Literal, TextIO
 import sqlalchemy as sa
 from sqlalchemy.orm import Session
 
-from . import VERSION
-from .database import ds
-from .models import Artist, Song, SongArtist
-from .utils import format_duration
+from .. import VERSION
+from ..database import ds
+from ..models import Artist, Song, SongArtist
+from ..utils import format_duration
 
 API_URL: str = "https://www.wikidata.org/w/api.php"
 """The URL of the Wikidata API endpoint."""

tools/src/pop_fem_audit_tools/commands/fetch_lyrics.py

@@ -36,14 +36,14 @@ from typing import Any
 import sqlalchemy as sa
 from sqlalchemy.orm import Session
 
-from .database import ds
-from .models import (
+from ..database import ds
+from ..models import (
     Artist,
     Role,
     Song,
     SongArtist,
 )
-from .utils import format_duration
+from ..utils import format_duration
 
 PROVENANCE_FIELDS: Sequence[str] = (
     "song_id", "source", "method", "acquired_at", "note")

tools/src/pop_fem_audit_tools/commands/run_llm.py

@@ -26,7 +26,7 @@ from typing import Any, Self
 
 import anthropic
 
-from .config import get_settings
+from ..config import get_settings
 
 MODEL: str = "claude-sonnet-4-6"
 TEMPERATURE: float = 0.0

tools/tests/test_build_db.py

@@ -15,7 +15,8 @@ from unittest import mock
 import sqlalchemy as sa
 from sqlalchemy.orm import Session
 
-from pop_fem_audit_tools import build_db, config
+from pop_fem_audit_tools import config
+from pop_fem_audit_tools.commands import build_db
 from pop_fem_audit_tools.database import DataSource
 from pop_fem_audit_tools.models import (
     Artist,

tools/tests/test_export_llm_input.py

@@ -14,7 +14,8 @@ from unittest import mock
 
 from sqlalchemy.orm import Session
 
-from pop_fem_audit_tools import config, export_llm_input
+from pop_fem_audit_tools import config
+from pop_fem_audit_tools.commands import export_llm_input
 from pop_fem_audit_tools.database import Base, DataSource
 from pop_fem_audit_tools.models import (
     Artist,

tools/tests/test_fetch_artists.py

@@ -16,7 +16,8 @@ from unittest import mock
 
 from sqlalchemy.orm import Session
 
-from pop_fem_audit_tools import config, fetch_artists
+from pop_fem_audit_tools import config
+from pop_fem_audit_tools.commands import fetch_artists
 from pop_fem_audit_tools.database import Base, DataSource
 from pop_fem_audit_tools.models import Artist, Role, Song, SongArtist
 

tools/tests/test_fetch_lyrics.py

@@ -16,7 +16,8 @@ from unittest import mock
 
 from sqlalchemy.orm import Session
 
-from pop_fem_audit_tools import config, fetch_lyrics
+from pop_fem_audit_tools import config
+from pop_fem_audit_tools.commands import fetch_lyrics
 from pop_fem_audit_tools.database import Base, DataSource
 from pop_fem_audit_tools.models import (
     Artist,

tools/tests/test_main.py

@@ -11,7 +11,8 @@ import unittest
 from contextlib import redirect_stderr, redirect_stdout
 from unittest import mock
 
-from pop_fem_audit_tools import __main__, run_llm
+from pop_fem_audit_tools import __main__
+from pop_fem_audit_tools.commands import run_llm
 
 
 class TestDispatcher(unittest.TestCase):

tools/tests/test_run_llm.py

@@ -14,7 +14,8 @@ from pathlib import Path
 from typing import Any
 from unittest import mock
 
-from pop_fem_audit_tools import config, run_llm
+from pop_fem_audit_tools import config
+from pop_fem_audit_tools.commands import run_llm
 
 
 class RunLLMTestCase(unittest.TestCase):