django-spec-cli 0.4.0__tar.gz → 0.4.1__tar.gz

{django_spec_cli-0.4.0 → django_spec_cli-0.4.1}/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.1] — 2026-11-04
+
+### Added
+- **The command line page shows a spec the kernel refuses.** Its system-check
+  section now includes an example command, `drafts`, serving one spec that
+  declares a plain `Parameter` over a keyword with no default, and prints the
+  `django_spec_cli.W004` sentence it gets. The page's tests assert that
+  `manage.py check` reports exactly that warning for the example and that a
+  run of the spec raises the same sentence, so the page cannot drift from
+  what the check and the command say. No change to the package.
+
 ## [0.4.0] — 2026-11-04
 
 ### Added
@@ -124,7 +135,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `django-service-specs>=0.10.0`, the first kernel release with every name the
   command reads at its root.
 
-[Unreleased]: https://github.com/Artui/django-spec-cli/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/Artui/django-spec-cli/compare/v0.4.1...HEAD
+[0.4.1]: https://github.com/Artui/django-spec-cli/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/Artui/django-spec-cli/compare/v0.3.1...v0.4.0
 [0.3.1]: https://github.com/Artui/django-spec-cli/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/Artui/django-spec-cli/compare/v0.2.1...v0.3.0

{django_spec_cli-0.4.0 → django_spec_cli-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: django-spec-cli
-Version: 0.4.0
+Version: 0.4.1
 Summary: Run a django-service-specs registry from manage.py: one subcommand per spec, options generated from its parameters, exit codes for every refusal.
 Project-URL: Homepage, https://github.com/Artui/django-spec-cli
 Project-URL: Repository, https://github.com/Artui/django-spec-cli

{django_spec_cli-0.4.0 → django_spec_cli-0.4.1}/django_spec_cli/version.py

@@ -2,6 +2,6 @@
 
 from __future__ import annotations
 
-__version__: str = "0.4.0"
+__version__: str = "0.4.1"
 
 __all__ = ["__version__"]

{django_spec_cli-0.4.0 → django_spec_cli-0.4.1}/docs/examples/commands.py

@@ -1,4 +1,5 @@
-"""A registry served as a management command, and a command that looks its user up by username.
+"""A registry served as a management command, a command that looks its user up by username, and
+a command serving a spec the kernel refuses as declared.
 
 ``tests/docs/test_commands_examples.py`` runs every command line
 ``docs/index.md`` shows through this module's ``Command``, from argv as
@@ -137,3 +138,31 @@ class ByUsername(SpecCommand):
 
 
 # --8<-- [end:by_username]
+
+
+# --8<-- [start:refused]
+def retitle(*, title: str) -> str:
+    return title
+
+
+drafts = SpecRegistry()
+drafts.register(
+    "retitle",
+    ServiceSpec(
+        service=retitle,
+        permissions=[IsSignedIn()],
+        # Optional, as a Parameter is unless it says otherwise, over a keyword
+        # with no default: a call leaving it out could not run, so the kernel's
+        # check_seeds refuses the spec, and manage.py check reports it as
+        # django_spec_cli.W004.
+        reads=Parameters.of(Parameter("title", "string")),
+    ),
+)
+
+
+# yourapp/management/commands/drafts.py
+class Drafts(SpecCommand):
+    registry = drafts
+
+
+# --8<-- [end:refused]

{django_spec_cli-0.4.0 → django_spec_cli-0.4.1}/docs/index.md

@@ -264,6 +264,23 @@ with the same sentence, raised as `ImproperlyConfigured` (exit code 1,
 with a traceback) before `--as-user` is looked up, even when the options sent
 would let it run. The command's other specs are unaffected.
 
+A `Parameter` is optional unless it says `required=True`, so a read declared
+plainly over a keyword with no default is one such declaration:
+
+```python
+--8<--
+docs/examples/commands.py:refused
+--8<--
+```
+
+`manage.py check` reports it as `django_spec_cli.W004`, and
+`manage.py drafts retitle --as-user 1 --title Final` is refused with the same
+sentence:
+
+```text
+'retitle' in manage.py drafts cannot run as declared, and a run of it is refused: ServiceSpec.service requires the keyword(s) ['title'], declared as optional reads that nothing else fills, so a call leaving one out is refused as missing. Declare the read required, or give the keyword a default.
+```
+
 All three are warnings, so a spec nobody runs never stops `migrate`, and
 `SILENCED_SYSTEM_CHECKS` silences one by id. Silencing `W004` hides the report
 and does not let the spec run.
@@ -275,7 +292,7 @@ listing only `"django_service_specs"` gets no check for a command. List
 A `SpecCommand` keeps Django's system checks on, so on the command line the
 report is printed to stderr before every run of every command. The runs on
 this page are shown without it; in a project listing the app, each would be
-preceded by the warning for `whoami`. `call_command` skips
+preceded by the warnings for `whoami` and `retitle`. `call_command` skips
 system checks for every command but `check`, so a command run through it
 does not print them.
 

{django_spec_cli-0.4.0 → django_spec_cli-0.4.1}/pyproject.toml

@@ -149,7 +149,7 @@ skip-magic-trailing-comma = false
 root = ["./django_spec_cli"]
 
 [tool.bumpversion]
-current_version = "0.4.0"
+current_version = "0.4.1"
 allow_dirty = false
 commit = false
 tag = false

{django_spec_cli-0.4.0 → django_spec_cli-0.4.1}/tests/docs/test_commands_examples.py

@@ -7,6 +7,10 @@
 shows them - must be the lines printed under it, and its exit status the
 number an ``echo $?`` after it shows. So the page cannot show an option, an
 output or an exit code the command does not have.
+
+The sentence the page prints for the example's ``Drafts``, whose spec the
+kernel refuses, must be the ``django_spec_cli.W004`` the system check reports
+and the refusal a run of the spec raises.
 """
 
 from __future__ import annotations
@@ -18,10 +22,13 @@ from pathlib import Path
 from typing import Any
 
 import pytest
+from django.core.checks import Warning
+from django.core.exceptions import ImproperlyConfigured
 from django.core.management import call_command
 from django.core.management.base import CommandError
 from django_service_specs import UnguardedReason, UnguardedSpec
 
+from django_spec_cli.checks import check_unguarded_specs
 from django_spec_cli.report.unguarded_message import unguarded_message
 from docs.examples import commands
 from tests.dispatch_app.models import Note
@@ -30,6 +37,7 @@ pytestmark = [pytest.mark.django_db, pytest.mark.usefixtures("keep_the_test_conn
 
 PAGE = Path(__file__).resolve().parents[2] / "docs" / "index.md"
 PROMPT = "$ python manage.py notes "
+RETITLE_ARGV = "retitle --as-user 1 --title Final"
 
 
 def _runs() -> list[tuple[str, list[str], int]]:
@@ -112,6 +120,54 @@ def test_the_username_lookup_runs_as_the_user_it_names() -> None:
     assert (caught.value.returncode, str(caught.value)) == (5, "No user named 'nobody'.")
 
 
+def _refused_line() -> str:
+    """The line the page prints for the W004 example: the one opening with its spec and command.
+
+    Found by that opening rather than by its block, so another ``text`` block
+    on the page leaves it alone, and a page no longer printing it fails here.
+    """
+    (line,) = [
+        line
+        for line in PAGE.read_text().splitlines()
+        if line.startswith("'retitle' in manage.py drafts ")
+    ]
+    return line
+
+
+def test_the_refused_spec_is_reported_as_w004_with_the_page_s_sentence(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # The examples are no installed app, so the walk is pointed at the one
+    # command; it would otherwise never load it, and no other test's check
+    # sees this command.
+    monkeypatch.setattr("django_spec_cli.checks.get_commands", lambda: {"drafts": "yourapp"})
+    monkeypatch.setattr(
+        "django_spec_cli.checks.load_command_class", lambda app_name, name: commands.Drafts()
+    )
+    assert check_unguarded_specs(None) == [
+        Warning(
+            _refused_line(),
+            hint=(
+                "Change the declaration as the message says. Until then a run of the spec "
+                "is refused, whether or not django_spec_cli.W004 is silenced."
+            ),
+            obj=commands.Drafts,
+            id="django_spec_cli.W004",
+        )
+    ]
+
+
+@pytest.mark.usefixtures("world")
+def test_a_run_of_the_refused_spec_raises_the_page_s_sentence() -> None:
+    # The run the page names, which sends every option the spec declares, and
+    # is still refused.
+    assert f"`manage.py drafts {RETITLE_ARGV}`" in PAGE.read_text()
+    command = commands.Drafts()
+    with pytest.raises(ImproperlyConfigured) as caught:
+        command.run_from_argv(["manage.py", "drafts", "--skip-checks", *shlex.split(RETITLE_ARGV)])
+    assert str(caught.value) == _refused_line()
+
+
 @pytest.mark.usefixtures("world")
 def test_whoami_is_the_user_named(capsys: pytest.CaptureFixture[str]) -> None:
     assert _run_from_argv("whoami --as-user 1") == 0