django-spec-cli 0.5.0__tar.gz → 0.6.0__tar.gz

{django_spec_cli-0.5.0 → django_spec_cli-0.6.0}/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] — 2026-11-09
+
+### Fixed
+- **A field a Validator declares only under `cli` is an option.** The command
+  asked the kernel's `spec_caller_input_schema` for the options to offer with no
+  `call_context`, so the schema was the declaration made to no transport at all,
+  and a field the Validator declares only when
+  `call_transport(call_context) == "cli"` got no option. If it was required,
+  every run was refused for it. The schema is now read under the same stamped
+  dict `--help` already hands the Validator, so such a field is offered, marked
+  `(required)` where it is, and a run leaving it out is refused with the shape
+  check's own message. A field declared to another transport is still no option.
+  The command line page no longer carries the caveat that asked for such a field
+  to be declared to every transport.
+
+- **A field a Validator declares only under `cli` that dispatch seeds itself is
+  refused for its spec alone.** The read `--help` makes under the stamped dict
+  raised `ImproperlyConfigured` for such a field, for example `user`, while the
+  parser was built, so every spec of the command, `--help` and `--explain` died
+  with a traceback, and `django_spec_cli.W004` said nothing because
+  `check_seeds` takes no `call_context`. The parser now takes that refusal for
+  the one spec: its subcommand takes no option and its `--help` prints the
+  kernel's reason, a run of it raises the same sentence as `ImproperlyConfigured`
+  before `--as-user` is looked up, whatever was sent, and `W004` names it. The
+  command's other specs are unaffected.
+
+### Changed
+- **The floor on `django-service-specs` rises from 0.29.0 to 0.30.0**, the
+  release that lets `spec_caller_input_schema` take a `call_context`. A project
+  on an older kernel stays on 0.5.x.
+
 ## [0.5.0] — 2026-11-08
 
 ### Added
@@ -155,7 +186,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.5.0...HEAD
+[Unreleased]: https://github.com/Artui/django-spec-cli/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/Artui/django-spec-cli/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/Artui/django-spec-cli/compare/v0.4.1...v0.5.0
 [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

{django_spec_cli-0.5.0 → django_spec_cli-0.6.0}/CLAUDE.md

@@ -139,7 +139,7 @@ configured and enforced. isort order is stdlib, third party, first party.
 | --- | --- | --- |
 | Python | 3.10 | 3.10 through 3.14 |
 | Django | 4.2 | 4.2, 5.0, 5.1, 5.2, 6.0, 6.1 |
-| django-service-specs | 0.29.0 | the newest release, and the floor in the `floor` job |
+| django-service-specs | 0.30.0 | the newest release, and the floor in the `floor` job |
 
 The Python and Django floors are the kernel's, and cannot sit below them.
 

{django_spec_cli-0.5.0 → django_spec_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: django-spec-cli
-Version: 0.5.0
+Version: 0.6.0
 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
@@ -30,7 +30,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
-Requires-Dist: django-service-specs>=0.29.0
+Requires-Dist: django-service-specs>=0.30.0
 Requires-Dist: django>=4.2
 Description-Content-Type: text/markdown
 
@@ -61,7 +61,7 @@ the import path, the system check ids and the setting key are this package's.
 pip install django-spec-cli
 ```
 
-Python 3.10 or later, Django 4.2 or later, and `django-service-specs` 0.29.0 or
+Python 3.10 or later, Django 4.2 or later, and `django-service-specs` 0.30.0 or
 later, which it installs.
 
 ## Quickstart

{django_spec_cli-0.5.0 → django_spec_cli-0.6.0}/README.md

@@ -25,7 +25,7 @@ the import path, the system check ids and the setting key are this package's.
 pip install django-spec-cli
 ```
 
-Python 3.10 or later, Django 4.2 or later, and `django-service-specs` 0.29.0 or
+Python 3.10 or later, Django 4.2 or later, and `django-service-specs` 0.30.0 or
 later, which it installs.
 
 ## Quickstart

{django_spec_cli-0.5.0 → django_spec_cli-0.6.0}/django_spec_cli/checks.py

@@ -108,10 +108,13 @@ def check_unguarded_specs(
 
 
 def _refused(command: SpecCommand) -> Iterator[tuple[str, ImproperlyConfigured]]:
-    """Each spec of ``command`` that ``check_seeds`` refuses, with its refusal, in registry order.
+    """Each spec of ``command`` a run refuses as declared, with its refusal, in registry order.
 
-    The same question ``SpecCommand.handle`` asks before a run, under the
-    same ``pool_seeds``, so a spec reported here is one a run refuses.
+    Two questions, as ``SpecCommand.handle`` asks them and in its order:
+    ``check_seeds`` under the same ``pool_seeds``, and the read the parser
+    made under the cli-stamped dict, which ``check_seeds`` never sees. The
+    parser has been built by now (the walk builds it), and it kept the
+    second's refusals. A spec both refuse is reported once, for the first.
     Outside the walk's ``try``: a refusal names one spec, and the command
     loaded, so its other specs are still reported and it is no W003.
     """
@@ -120,6 +123,10 @@ def _refused(command: SpecCommand) -> Iterator[tuple[str, ImproperlyConfigured]]
             check_seeds(entry.spec, pool_seeds=command.pool_seeds)
         except ImproperlyConfigured as error:
             yield entry.name, error
+            continue
+        declared = command._refused_by_declaration.get(entry.name)
+        if declared is not None:
+            yield entry.name, declared
 
 
 def _spec_commands(

{django_spec_cli-0.5.0 → django_spec_cli-0.6.0}/django_spec_cli/spec_command.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import argparse
 import inspect
-from collections.abc import Mapping
+from collections.abc import Mapping, Sequence
 from dataclasses import replace
 from typing import Any, TextIO, cast
 
@@ -78,7 +78,7 @@ class SpecCommand(BaseCommand):
       [`add_spec_arguments`][django_spec_cli.argv.add_spec_arguments.add_spec_arguments]
       spells them, as the input schema a transport advertises asks for them
       ([`spec_caller_input_schema`][django_service_specs.schema.spec_caller_input_schema.spec_caller_input_schema]
-      under ``pool_seeds``): less any key the server fills, and required only
+      under ``pool_seeds`` and the stamped ``call_context``): less any key the server fills, and required only
       where dispatch refuses leaving it out.
       No option is matched by a prefix: an abbreviation is refused rather
       than read as whichever option it begins.
@@ -99,7 +99,14 @@ class SpecCommand(BaseCommand):
       and its refusal is raised as ``ImproperlyConfigured``, as a command
       naming no registry is: a traceback and ``ExitCode.ERROR``, whatever
       the options sent. The command's other specs still run, and the system
-      check reports the same spec as ``django_spec_cli.W004``.
+      check reports the same spec as ``django_spec_cli.W004``. The same holds for a spec
+      whose Validator declares, only to ``cli``, a parameter dispatch seeds
+      itself: ``check_seeds`` is asked outside a call and never sees it, the
+      read the parser makes under the stamped dict does, and the parser takes
+      that refusal for its spec alone. Its subcommand takes no option and its
+      ``--help`` gives the reason; a run raises it as above, and W004 reports
+      it too
+      (test_a_run_of_it_is_refused_with_the_kernel_s_reason_whatever_is_sent).
     - ``--explain`` runs no spec: it lists the ones that authorize nothing,
       as the system check does.
 
@@ -119,10 +126,14 @@ class SpecCommand(BaseCommand):
     _command_label: str
     _parser: CommandParser
     _entries: dict[str, RegisteredSpec]
+    _refused_by_declaration: dict[str, ImproperlyConfigured]
 
     def create_parser(self, prog_name: str, subcommand: str, **kwargs: Any) -> CommandParser:
         """Django's parser, with this command's options added and no option read by its prefix."""
         self._command_label = subcommand
+        # Before ``add_arguments``, and not in it: a subclass overriding that
+        # without calling ``super()`` still leaves the system check a dict to read.
+        self._refused_by_declaration = {}
         parser = super().create_parser(prog_name, subcommand, **kwargs)
         # Django's own options are on this parser, and a prefix of one is no
         # more an option here than on a subcommand.
@@ -175,8 +186,24 @@ class SpecCommand(BaseCommand):
                 )
             self._entries[name] = entry
             spec = kernel_spec(entry.spec)
-            parameters = _sendable(spec, self.pool_seeds, _call_context())
             summary = _summary(spec, entry.name)
+            try:
+                parameters = _sendable(spec, self.pool_seeds, _call_context())
+            except ImproperlyConfigured as error:
+                # Only the read made under the stamped dict can raise here: a
+                # declaration the kernel refuses outside a call is
+                # ``check_seeds``' and is asked in ``handle``. Raising from the
+                # parser would stop every spec the command serves, ``--help``
+                # and ``--explain`` with them, so the refusal waits for a run of
+                # this spec, which raises it, and its subcommand takes no option.
+                self._refused_by_declaration[entry.name] = error
+                _add_refused_subparser(
+                    subparsers,
+                    name,
+                    summary,
+                    refused_message(entry.name, self._command_label, error),
+                )
+                continue
             subparser = subparsers.add_parser(
                 name,
                 help=summary.replace("%", "%%"),
@@ -253,6 +280,9 @@ class SpecCommand(BaseCommand):
         # ``ExitCode.ERROR`` is published as the failure with a traceback.
         try:
             check_seeds(entry.spec, pool_seeds=self.pool_seeds)
+            declared = self._refused_by_declaration.get(entry.name)
+            if declared is not None:
+                raise declared
         except ImproperlyConfigured as error:
             raise ImproperlyConfigured(
                 refused_message(entry.name, self._command_label, error)
@@ -328,7 +358,12 @@ def _sendable(
     """What a caller may send, as the kernel's caller schema reads it: required only where dispatch demands it.
 
     The parameters ``spec_caller_input_schema`` offers under the command's
-    ``pool_seeds``, so no key the server fills is an option: one a provider
+    ``pool_seeds`` and the stamped ``call_context``, so a field a Validator
+    declares only to ``cli`` is an option and one declared to another
+    transport is not
+    (test_a_required_field_declared_only_under_cli_is_an_option_marked_required,
+    test_a_field_declared_under_another_transport_is_no_option), and no key the
+    server fills is an option: one a provider
     is annotated to fill (test_a_key_the_server_fills_is_no_option), and a
     reflected read a registered seed fills
     (test_a_reflected_read_a_seed_fills_is_an_option_only_without_the_seed).
@@ -342,7 +377,7 @@ def _sendable(
     (test_a_read_a_provider_requires_itself_is_required). Only
     relaxed, never made required, so a declared default still answers.
     """
-    schema = spec_caller_input_schema(spec, pool_seeds=pool_seeds)
+    schema = spec_caller_input_schema(spec, pool_seeds=pool_seeds, call_context=call_context)
     required = frozenset(schema.get("required", ()))
     return Parameters.of(
         *(
@@ -353,6 +388,37 @@ def _sendable(
     )
 
 
+def _add_refused_subparser(subparsers: Any, name: str, summary: str, message: str) -> None:
+    """The subcommand of a spec whose declaration refuses under the stamped dict: its reason, and no option.
+
+    Whatever is sent after the name is taken and read by nothing, so a run is
+    refused with the reason whatever it carried, as a spec ``check_seeds``
+    refuses is. Only ``--help`` is read, and it prints the reason.
+    """
+    subparser = subparsers.add_parser(
+        name,
+        help=summary.replace("%", "%%"),
+        description=summary,
+        # argparse formats an epilog only where it names ``%(prog)``, so a
+        # ``%`` is doubled there and nowhere else
+        # (test_a_percent_sign_in_the_reason_is_printed_as_it_is).
+        epilog=message.replace("%", "%%") if "%(prog)" in message else message,
+        usage="%(prog)s [arguments ...]",
+        allow_abbrev=False,
+    )
+    reads_help = subparser.parse_known_args
+
+    def take_everything(
+        args: Sequence[str], namespace: argparse.Namespace | None = None
+    ) -> tuple[argparse.Namespace, list[str]]:
+        # ``_SubParsersAction`` hands a list and a ``None`` namespace.
+        if {"-h", "--help"} & set(args):
+            return reads_help(args, namespace)
+        return argparse.Namespace(), []
+
+    subparser.parse_known_args = take_everything
+
+
 def _summary(spec: ServiceSpec | SelectorSpec, name: str) -> str:
     """The first paragraph of what the spec's callable says about itself, and whether it reads or writes.
 

{django_spec_cli-0.5.0 → django_spec_cli-0.6.0}/django_spec_cli/version.py

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

{django_spec_cli-0.5.0 → django_spec_cli-0.6.0}/docs/index.md

@@ -27,7 +27,7 @@ pip install django-spec-cli
 ```
 
 It installs [`django-service-specs`](https://artui.github.io/django-service-specs/), the kernel whose specs it serves,
-from 0.29.0, on Python 3.10 and Django 4.2 or later. The command line was the
+from 0.30.0, on Python 3.10 and Django 4.2 or later. The command line was the
 kernel's `commands/` subpackage, and moved here so the kernel carries no
 transport.
 
@@ -264,6 +264,17 @@ 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.
 
+The same holds for a declaration only the command's own read reaches. A
+Validator may declare a field only when `call_transport(call_context) == "cli"`,
+and if that field is named for a key dispatch seeds itself, such as `user`,
+`check_seeds` (asked outside a call) never sees it, and the read `--help`
+makes under the stamped dict raises. That refusal belongs to the one spec: its
+subcommand takes no option, its `--help` prints the kernel's reason, a run of it
+ends with the same sentence as `ImproperlyConfigured` whatever was sent, and
+`django_spec_cli.W004` names it. The command's other specs, `--help` and
+`--explain` work as before. A spec both reads refuse is reported once, with the
+`check_seeds` reason.
+
 A `Parameter` is optional unless it says `required=True`, so a read declared
 plainly over a keyword with no default is one such declaration:
 
@@ -323,13 +334,11 @@ docs/examples/commands.py:transport
   such an entry, as it does for a missing one, and `format` and `action` are
   never bound by name, so a spec written for HTTP runs here as it did.
 - **`--help` is read under a dict too.** The command builds a stamped dict of
-  its own for each spec to describe a Validator's fields for the parser. The
-  kernel's schema and seed checks that decide which options are offered are
-  asked outside a call, as they are by every transport, and read no stamp. So
-  the option names come from a transport-blind declaration: a field a
-  Validator declares only when `call_transport(call_context) == "cli"` is
-  never offered, and if it is required, every run is refused for it.
-  Declare such a field for every transport, or not at all.
+  its own for each spec, and the options come from the kernel's caller schema
+  read under it, as the Validator's declaration is. A field a Validator
+  declares only when `call_transport(call_context) == "cli"` is an option,
+  marked `(required)` where it is required, and one it declares to another
+  transport is none.
 - **Seams.** The value is not configurable: a subclass cannot change what a
   run stamps. What a subclass can supply is `resolve_as_user`, who the run is
   made as, and `pool_seeds`, which adds a keyword to the pool every callable

{django_spec_cli-0.5.0 → django_spec_cli-0.6.0}/pyproject.toml

@@ -49,8 +49,10 @@ dependencies = [
     # ``tests/test_exit_code_for.py`` decides by name. Below 0.11.0 the kernel
     # also still shipped its own copy of the command and registered its own
     # ``W001`` and ``W003``. 0.29.0 adds ``build_call_context``, which the
-    # command builds the context it stamps ``cli`` on through.
-    "django-service-specs>=0.29.0",
+    # command builds the context it stamps ``cli`` on through. 0.30.0 lets
+    # ``spec_caller_input_schema`` take that context, so the options offered are
+    # read under it.
+    "django-service-specs>=0.30.0",
 ]
 
 [project.urls]
@@ -150,7 +152,7 @@ skip-magic-trailing-comma = false
 root = ["./django_spec_cli"]
 
 [tool.bumpversion]
-current_version = "0.5.0"
+current_version = "0.6.0"
 allow_dirty = false
 commit = false
 tag = false

{django_spec_cli-0.5.0 → django_spec_cli-0.6.0}/tests/test_checks.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 
 import importlib
 import io
+from typing import Any
 
 import pytest
 from django.apps import apps
@@ -27,6 +28,9 @@ from django_service_specs import (
     UnguardedReason,
     UnguardedSpec,
     Unrestricted,
+    ValidationContext,
+    Validator,
+    call_transport,
 )
 
 from django_spec_cli.checks import check_unguarded_specs
@@ -263,6 +267,80 @@ class TestADeclarationTheKernelRefuses:
         assert seeded == []
 
 
+class _SeedNamedUnderCli(Validator):
+    """Declares ``user``, a name dispatch seeds itself, only when the transport is ``cli``."""
+
+    def parameters(self, *, call_context: Any = None) -> Parameters:
+        declared = [Parameter("n", "integer", required=False)]
+        if call_transport(call_context) == "cli":
+            declared.append(Parameter("user", "string", required=False))
+        return Parameters.of(*declared)
+
+    def validate(self, arguments: Any, context: ValidationContext) -> dict[str, Any]:
+        return dict(arguments)
+
+
+class TestADeclarationOnlyTheCliStampedReadRefuses:
+    """The read the parser makes under the stamped dict, which ``check_seeds`` never sees."""
+
+    def _walk(
+        self, monkeypatch: pytest.MonkeyPatch, registry: SpecRegistry
+    ) -> tuple[type, list[CheckMessage]]:
+        command = type("Command", (SpecCommand,), {"registry": registry})
+        monkeypatch.setattr("django_spec_cli.checks.get_commands", lambda: {"seeded": APP})
+        monkeypatch.setattr(
+            "django_spec_cli.checks.load_command_class", lambda app_name, name: command()
+        )
+        return command, check_unguarded_specs(None)
+
+    def test_the_spec_is_reported_as_w004_naming_it_and_the_command_is_no_w003(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        registry = SpecRegistry()
+        registry.register(
+            "bad",
+            ServiceSpec(service=_echo, permissions=[StaffOnly()], validator=_SeedNamedUnderCli()),
+        )
+        registry.register("good", ServiceSpec(service=_echo, permissions=[StaffOnly()]))
+        command, messages = self._walk(monkeypatch, registry)
+        assert [(m.id, m.obj) for m in messages] == [("django_spec_cli.W004", command)]
+        assert messages[0].msg.startswith(
+            "'bad' in manage.py seeded cannot run as declared, and a run of it is refused: "
+            "ServiceSpec.validator declares the parameter(s) ['user'], which dispatch seeds itself."
+        )
+
+    def test_a_command_overriding_add_arguments_without_super_is_still_checked(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        class Bare(SpecCommand):
+            registry = SpecRegistry()
+
+            def add_arguments(self, parser: Any) -> None: ...
+
+        registry = SpecRegistry()
+        registry.register("open", ServiceSpec(service=_echo, permissions=[Unrestricted()]))
+        Bare.registry = registry
+        monkeypatch.setattr("django_spec_cli.checks.get_commands", lambda: {"bare": APP})
+        monkeypatch.setattr("django_spec_cli.checks.load_command_class", lambda *_: Bare())
+        assert [m.id for m in check_unguarded_specs(None)] == ["django_spec_cli.W001"]
+
+    def test_a_spec_both_reads_refuse_is_reported_once(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        both = ServiceSpec(
+            service=_echo,
+            permissions=[StaffOnly()],
+            validator=_SeedNamedUnderCli(),
+            reads=Parameters.of(Parameter("project", "integer", required=False)),
+            kwargs=_needs_project,
+        )
+        registry = SpecRegistry()
+        registry.register("both", both)
+        _, messages = self._walk(monkeypatch, registry)
+        assert [m.id for m in messages] == ["django_spec_cli.W004"]
+        assert "requires the keyword(s) ['project']" in messages[0].msg
+
+
 class TestAppConfigs:
     """``manage.py check <app_label>`` checks the commands of the apps it names."""