usethis-python · nathanjmcdougall · Jun 20, 2025 · Jun 18, 2025 · Jun 19, 2025 · Jun 20, 2025
diff --git a/README.md b/README.md
@@ -85,6 +85,7 @@ $ pipx run usethis tool ruff
 - [`usethis author`](#usethis-author) — Set new author information for the project.
 - [`usethis docstyle`](#usethis-docstyle-style) — Set new author information for the project.
 - [`usethis rule`](#usethis-rule-rulecode) — Set a docstring style convention for the project, and [enforce it with Ruff](https://docs.astral.sh/ruff/rules/#pydocstyle-d).
+- [`usethis status`](#usethis-status-status) — Set the development status of the project (via trove classifiers).
 
 ### Manage README
 
@@ -188,6 +189,15 @@ Supported options:
   - `numpy` for [NumPy docstring style](https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard)
   - `google` for [Google docstring style](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)
   - `pep257` for [PEP 257 docstring style](https://www.python.org/dev/peps/pep-0257/)
+- `--status` to set the development status of the project. Defaults to `planning`.
+  Possible values:
+  - `planning` or `1` for "Development Status :: 1 - Planning"
+  - `pre-alpha` or `2` for "Development Status :: 2 - Pre-Alpha"
+  - `alpha` or `3` for "Development Status :: 3 - Alpha"
+  - `beta` or `4` for "Development Status :: 4 - Beta"
+  - `production` or `5` for "Development Status :: 5 - Production/Stable"
+  - `mature` or `6` for "Development Status :: 6 - Mature"
+  - `inactive` or `7` for "Development Status :: 7 - Inactive"
 - `--offline` to disable network access and rely on caches
 - `--quiet` to suppress output
 - `--frozen` to leave the virtual environment and lockfile unchanged (i.e. do not install dependencies, nor update lockfiles)
@@ -349,23 +359,27 @@ Supported options:
 - `--offline` to disable network access and rely on caches
 - `--quiet` to suppress output
 
-### `usethis rule <rulecode>`
+### `usethis readme`
 
-Add (or manage configuration) of Ruff and Deptry rules in `pyproject.toml`.
+Add a README.md file to the project.
 
-See [the Ruff documentation](https://docs.astral.sh/ruff/rules/) for a list of available
-rules, and [the Deptry documentation](https://deptry.com/rules-violations/) for a list
-of available rules.
+Supported options:
 
-Example:
+- `--quiet` to suppress output
+- `--badges` to also add badges to the README.md file
 
-`usethis rule RUF001`
+### `usethis author`
 
-Supported options:
+Set new author information for the project.
 
-- `--remove` to remove the rule selection or ignore status.
-- `--ignore` to add the rule to the ignore list (or remove it if --remove is specified).
-- `--offline` to disable network access and rely on caches
+Required options:
+
+- `--name` for the new author's name
+
+Other supported options:
+
+- `--email` to set the author email address
+- `--overwrite` to overwrite all existing author information
 - `--quiet` to suppress output
 
 ### `usethis docstyle <style>`
@@ -388,28 +402,43 @@ Supported options:
 
 - `--quiet` to suppress output
 
-### `usethis readme`
+### `usethis rule <rulecode>`
 
-Add a README.md file to the project.
+Add (or manage configuration) of Ruff and Deptry rules in `pyproject.toml`.
+
+See [the Ruff documentation](https://docs.astral.sh/ruff/rules/) for a list of available
+rules, and [the Deptry documentation](https://deptry.com/rules-violations/) for a list
+of available rules.
+
+Example:
+
+`usethis rule RUF001`
 
 Supported options:
 
+- `--remove` to remove the rule selection or ignore status.
+- `--ignore` to add the rule to the ignore list (or remove it if --remove is specified).
+- `--offline` to disable network access and rely on caches
 - `--quiet` to suppress output
-- `--badges` to also add badges to the README.md file
 
-### `usethis author`
+### `usethis status <status>`
 
-Set new author information for the project.
+Set the development status of the project via trove classifiers.
 
-Required options:
+Possible values (required):
 
-- `--name` for the new author's name
+- `usethis status planning` or `usethis status 1` for "Development Status :: 1 - Planning"
+- `usethis status pre-alpha` or `usethis status 2` for "Development Status :: 2 - Pre-Alpha"
+- `usethis status alpha` or `usethis status 3` for "Development Status :: 3 - Alpha"
+- `usethis status beta` or `usethis status 4` for "Development Status :: 4 - Beta"
+- `usethis status production` or `usethis status 5` for "Development Status :: 5 - Production/Stable"
+- `usethis status mature` or `usethis status 6` for "Development Status :: 6 - Mature"
+- `usethis status inactive` or `usethis status 7` for "Development Status :: 7 - Inactive"
 
-Other supported options:
+Supported options:
 
-- `--email` to set the author email address
-- `--overwrite` to overwrite all existing author information
 - `--quiet` to suppress output
+- `--badges` to add an associated badge to the README file
 
 ### `usethis list`
 

diff --git a/pyproject.toml b/pyproject.toml
@@ -198,7 +198,7 @@ name = "usethis._interface"
 type = "layers"
 layers = [
   # Note; if you're adding an interface, make sure it's in the README too.
-  "author | badge | browse | ci | docstyle | format_ | init | lint | list | readme | rule | show | spellcheck | test | tool | version",
+  "author | badge | browse | ci | docstyle | format_ | init | lint | list | readme | rule | show | spellcheck | status | test | tool | version",
 ]
 containers = [ "usethis._interface" ]
 exhaustive = true
@@ -209,7 +209,7 @@ type = "layers"
 layers = [
   # docstyle uses (Ruff) tool, badge uses readme
   "badge | docstyle | list | rule",
-  "author | browse | ci | readme | show | tool",
+  "author | browse | ci | readme | show | status | tool",
 ]
 containers = [ "usethis._core" ]
 exhaustive = true

diff --git a/src/usethis/_app.py b/src/usethis/_app.py
@@ -15,6 +15,7 @@
 import usethis._interface.rule
 import usethis._interface.show
 import usethis._interface.spellcheck
+import usethis._interface.status
 import usethis._interface.test
 import usethis._interface.tool
 import usethis._interface.version
@@ -76,6 +77,12 @@
 )(
     usethis._interface.rule.rule,
 )
+app.command(
+    help="Set the development status of the project (via trove classifiers).",
+    rich_help_panel=rich_help_panel,
+)(
+    usethis._interface.status.status,
+)
 
 rich_help_panel = "Manage README"
 app.add_typer(

diff --git a/src/usethis/_core/status.py b/src/usethis/_core/status.py
@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from enum import Enum
+
+from usethis._console import tick_print
+from usethis._integrations.file.pyproject_toml.io_ import PyprojectTOMLManager
+from usethis._integrations.uv.init import ensure_pyproject_toml
+
+
+class DevelopmentStatusEnum(Enum):
+    planning = "planning"
+    planning_code = "1"
+    prealpha = "prealpha"
+    prealpha_code = "2"
+    alpha = "alpha"
+    alpha_code = "3"
+    beta = "beta"
+    beta_code = "4"
+    production = "production"
+    production_code = "5"
+    mature = "mature"
+    mature_code = "6"
+    inactive = "inactive"
+    inactive_code = "7"
+
+
+def use_development_status(
+    status: DevelopmentStatusEnum,
+) -> None:
+    ensure_pyproject_toml()
+
+    new_classifier = _STATUS_TO_CLASSIFIER_MAP[status]
+
+    dispstatus = new_classifier.removeprefix("Development Status :: ")
+
+    tick_print(f"Setting the development status to '{dispstatus}'.")
+
+    mgr = PyprojectTOMLManager()
+    try:
+        existing_classifiers = mgr[["project", "classifiers"]]
+    except KeyError:
+        existing_classifiers = []
+    existing_status_classifiers = {
+        classifier
+        for classifier in existing_classifiers
+        if classifier in STATUS_CLASSIFIERS
+    }
+    mgr.remove_from_list(
+        keys=["project", "classifiers"],
+        values=existing_status_classifiers,
+    )
+
+    mgr.extend_list(
+        keys=["project", "classifiers"],
+        values=[new_classifier],
+    )
+
+
+_STATUS_TO_CLASSIFIER_MAP = {
+    DevelopmentStatusEnum.planning: "Development Status :: 1 - Planning",
+    DevelopmentStatusEnum.planning_code: "Development Status :: 1 - Planning",
+    DevelopmentStatusEnum.prealpha: "Development Status :: 2 - Pre-Alpha",
+    DevelopmentStatusEnum.prealpha_code: "Development Status :: 2 - Pre-Alpha",
+    DevelopmentStatusEnum.alpha: "Development Status :: 3 - Alpha",
+    DevelopmentStatusEnum.alpha_code: "Development Status :: 3 - Alpha",
+    DevelopmentStatusEnum.beta: "Development Status :: 4 - Beta",
+    DevelopmentStatusEnum.beta_code: "Development Status :: 4 - Beta",
+    DevelopmentStatusEnum.production: "Development Status :: 5 - Production/Stable",
+    DevelopmentStatusEnum.production_code: "Development Status :: 5 - Production/Stable",
+    DevelopmentStatusEnum.mature: "Development Status :: 6 - Mature",
+    DevelopmentStatusEnum.mature_code: "Development Status :: 6 - Mature",
+    DevelopmentStatusEnum.inactive: "Development Status :: 7 - Inactive",
+    DevelopmentStatusEnum.inactive_code: "Development Status :: 7 - Inactive",
+}
+
+STATUS_CLASSIFIERS = set(_STATUS_TO_CLASSIFIER_MAP.values())
diff --git a/src/usethis/_integrations/file/toml/io_.py b/src/usethis/_integrations/file/toml/io_.py
@@ -31,7 +31,7 @@
 )
 
 if TYPE_CHECKING:
-    from collections.abc import Sequence
+    from collections.abc import Collection, Sequence
     from pathlib import Path
     from typing import ClassVar
 
@@ -278,7 +278,7 @@ def extend_list(self, *, keys: Sequence[Key], values: list[Any]) -> None:
 
         self.commit(toml_document)
 
-    def remove_from_list(self, *, keys: Sequence[Key], values: list[Any]) -> None:
+    def remove_from_list(self, *, keys: Sequence[Key], values: Collection[Any]) -> None:
         if not keys:
             msg = "At least one ID key must be provided."
             raise ValueError(msg)

diff --git a/src/usethis/_interface/init.py b/src/usethis/_interface/init.py
@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import typer
 from typing_extensions import assert_never
 
@@ -16,6 +18,7 @@
 )
 from usethis._core.docstyle import DocStyleEnum, use_docstyle
 from usethis._core.readme import add_readme
+from usethis._core.status import DevelopmentStatusEnum, use_development_status
 from usethis._core.tool import use_pre_commit
 from usethis._integrations.uv.init import opinionated_uv_init
 from usethis._toolset.format_ import use_formatters
@@ -25,7 +28,7 @@
 from usethis.errors import UsethisError
 
 
-def init(  # noqa: PLR0913
+def init(  # noqa: PLR0913, PLR0915
     format_: bool = typer.Option(
         True, "--format/--no-format", help="Add recommended formatters."
     ),
@@ -57,6 +60,11 @@ def init(  # noqa: PLR0913
         "--docstyle",
         help="Set a docstring style convention for the project.",
     ),
+    status: DevelopmentStatusEnum = typer.Option(
+        "planning",
+        "--status",
+        help="Set the development status of the project.",
+    ),
     offline: bool = offline_opt,
     quiet: bool = quiet_opt,
     frozen: bool = frozen_opt,
@@ -81,6 +89,9 @@ def init(  # noqa: PLR0913
             opinionated_uv_init()
             add_readme()
 
+            assert isinstance(status, DevelopmentStatusEnum)
+            use_development_status(status)
+
             if pre_commit:
                 tick_print("Adding the pre-commit framework.")
                 with usethis_config.set(alert_only=True):

diff --git a/src/usethis/_interface/status.py b/src/usethis/_interface/status.py
@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import typer
+
+from usethis._config import quiet_opt, usethis_config
+from usethis._config_file import files_manager
+from usethis._console import err_print
+from usethis._core.status import (
+    DevelopmentStatusEnum,
+    use_development_status,
+)
+from usethis.errors import UsethisError
+
+
+def status(
+    status: DevelopmentStatusEnum = typer.Argument(
+        default=..., help="Docstring style to enforce."
+    ),
+    quiet: bool = quiet_opt,
+) -> None:
+    assert isinstance(status, DevelopmentStatusEnum)
+
+    with usethis_config.set(quiet=quiet), files_manager():
+        try:
+            use_development_status(status)
+        except UsethisError as err:
+            err_print(err)
+            raise typer.Exit(code=1) from None