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

{django_spec_cli-0.4.1 → django_spec_cli-0.6.0}/.github/workflows/release.yml

@@ -31,7 +31,7 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
-      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
         with:
           enable-cache: true
       - name: Install

{django_spec_cli-0.4.1 → django_spec_cli-0.6.0}/.github/workflows/tests.yml

@@ -20,7 +20,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
         with:
           enable-cache: true
       - name: Install
@@ -37,7 +37,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
         with:
           enable-cache: true
       - name: Install with docs group
@@ -54,7 +54,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
         with:
           enable-cache: true
       # A floor is a claim about the *oldest* version that works, and a lockfile
@@ -171,7 +171,7 @@ jobs:
 
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
         with:
           enable-cache: true
       - name: Install Python ${{ matrix.python-version }}

{django_spec_cli-0.4.1 → django_spec_cli-0.6.0}/.github/workflows/upstream-drift.yml

@@ -43,14 +43,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
         with:
           enable-cache: false
 
       # One cell, not the matrix. The matrix answers "does this combination
       # work"; this answers "has an upstream moved under us", and the newest
       # supported Python is where a new release lands first.
-      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
         with:
           python-version: "3.14"
 

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

@@ -7,6 +7,57 @@ 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
+- **A run stamps its transport: `"cli"`.** Every callable a `SpecCommand` run
+  reaches is now handed a `call_context` built by the kernel's
+  `build_call_context` and stamped last with `"cli"`, exported as
+  `CLI_TRANSPORT`, so a permission check, the Validator, a provider, the
+  service and the presenter read `call_transport(call_context) == "cli"` from
+  one dict. Before, the command handed `dispatch` none, and a callable reading
+  the key saw a missing one, which the kernel reads as an in-process caller.
+  The Validator's declaration the command reads for the options it parses is
+  asked under the stamped dict as well. `request`, `view`, `format` and
+  `action` are in the dict as `None`, which binds nothing different from a
+  missing key. The command line page says what a callable reads here.
+
+### Changed
+- **The floor on `django-service-specs` rises from 0.25.0 to 0.29.0**, the
+  release that adds `build_call_context` and removes the shared `Transport`
+  enum. A project on an older kernel stays on 0.4.x.
+
 ## [0.4.1] — 2026-11-04
 
 ### Added
@@ -135,7 +186,9 @@ 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.1...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
 [0.3.1]: https://github.com/Artui/django-spec-cli/compare/v0.3.0...v0.3.1

{django_spec_cli-0.4.1 → 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.25.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.4.1 → django_spec_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: django-spec-cli
-Version: 0.4.1
+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.25.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.25.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.4.1 → 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.25.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.4.1 → django_spec_cli-0.6.0}/django_spec_cli/__init__.py

@@ -11,11 +11,13 @@ from django_spec_cli.render.render_table import render_table
 from django_spec_cli.render.wants_table import wants_table
 from django_spec_cli.report.unguarded_message import unguarded_message
 from django_spec_cli.spec_command import SpecCommand
+from django_spec_cli.types.cli_transport import CLI_TRANSPORT
 from django_spec_cli.types.exit_code import ExitCode
 from django_spec_cli.version import __version__
 
 __all__ = [
     "__version__",
+    "CLI_TRANSPORT",
     "ExitCode",
     "ParameterDescriptor",
     "SpecCommand",

{django_spec_cli-0.4.1 → 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.4.1 → 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
 
@@ -26,6 +26,7 @@ from django_service_specs import (
     ServiceSpec,
     ServiceValidationError,
     SpecRegistry,
+    build_call_context,
     check_seeds,
     coerce_flat,
     dispatch,
@@ -46,6 +47,7 @@ from django_spec_cli.render.render_result import render_result
 from django_spec_cli.render.wants_table import wants_table
 from django_spec_cli.report.unguarded_message import unguarded_message
 from django_spec_cli.report.utils import refused_message
+from django_spec_cli.types.cli_transport import CLI_TRANSPORT
 from django_spec_cli.types.exit_code import ExitCode
 
 _OWN_OPTIONS = frozenset({"--as-user", "--json", "--table"})
@@ -76,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.
@@ -97,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.
 
@@ -117,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.
@@ -173,8 +186,24 @@ class SpecCommand(BaseCommand):
                 )
             self._entries[name] = entry
             spec = kernel_spec(entry.spec)
-            parameters = _sendable(spec, self.pool_seeds)
             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("%", "%%"),
@@ -251,12 +280,19 @@ 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)
             ) from error
         spec = kernel_spec(entry.spec)
-        parameters = spec.parameters()
+        # One dict for the whole run, built ahead of the first callable it
+        # asks: the declaration read here, then every stage ``dispatch`` runs,
+        # so a callable reading ``transport`` sees ``cli`` from either.
+        call_context = _call_context()
+        parameters = spec.parameters(call_context=call_context)
         raw = parsed_arguments(argparse.Namespace(**options), parameters)
         # Read before the run, not after it: a setting that names no format
         # raises, and raising once a write has committed reports a failure for
@@ -282,6 +318,7 @@ class SpecCommand(BaseCommand):
                 principal=principal,
                 arguments=coerce_flat(parameters, raw),
                 pool_seeds=self.pool_seeds,
+                call_context=call_context,
             )
         except (DispatchError, ServiceError) as error:
             raise CommandError(_message(error), returncode=int(exit_code_for(error))) from error
@@ -304,11 +341,29 @@ class SpecCommand(BaseCommand):
             self.stdout.write(unguarded_message(unguarded, label))
 
 
-def _sendable(spec: ServiceSpec | SelectorSpec, pool_seeds: PoolSeeds) -> Parameters:
+def _call_context() -> dict[str, Any]:
+    """A new context for the command's own reads and one run, stamped ``cli``.
+
+    ``request`` and ``view`` are there as ``None``, since a command line has
+    neither: the kernel hands a callable declaring either ``None`` for a
+    ``None`` entry exactly as for a missing one, so no binding changes.
+    ``format`` and ``action`` are no pool names and are never bound.
+    """
+    return build_call_context(CLI_TRANSPORT)
+
+
+def _sendable(
+    spec: ServiceSpec | SelectorSpec, pool_seeds: PoolSeeds, call_context: dict[str, Any]
+) -> Parameters:
     """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).
@@ -322,17 +377,48 @@ def _sendable(spec: ServiceSpec | SelectorSpec, pool_seeds: PoolSeeds) -> Parame
     (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(
         *(
             param if param.name in required else replace(param, required=False)
-            for param in spec.parameters()
+            for param in spec.parameters(call_context=call_context)
             if param.name in schema["properties"]
         )
     )
 
 
+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.6.0/django_spec_cli/types/__init__.py

@@ -0,0 +1,9 @@
+"""Value types: the exit status a command's run ends with, and the transport name it stamps."""
+
+from django_spec_cli.types.cli_transport import CLI_TRANSPORT
+from django_spec_cli.types.exit_code import ExitCode
+
+__all__ = [
+    "CLI_TRANSPORT",
+    "ExitCode",
+]

django_spec_cli-0.6.0/django_spec_cli/types/cli_transport.py

@@ -0,0 +1,13 @@
+"""``CLI_TRANSPORT`` - the transport name a ``SpecCommand`` stamps on every call's context."""
+
+from __future__ import annotations
+
+from typing import Final
+
+CLI_TRANSPORT: Final = "cli"
+"""What a ``SpecCommand`` stamps under the kernel's ``TRANSPORT_KEY``: the plain string ``"cli"``.
+
+A callable reads it with the kernel's ``call_transport``, or compares
+``call_context["transport"] == "cli"`` with nothing imported. This package owns
+the string and the kernel lists no transports; it is a public contract, so it
+never changes."""

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

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

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

@@ -1,5 +1,6 @@
-"""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.
+"""A registry served as a management command, a command that looks its user up by username, a
+command whose service reads the transport it is called over, 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
@@ -31,6 +32,7 @@ from django_service_specs import (
     ServiceSpec,
     SpecRegistry,
     Unrestricted,
+    call_transport,
 )
 
 from django_spec_cli import SpecCommand
@@ -166,3 +168,21 @@ class Drafts(SpecCommand):
 
 
 # --8<-- [end:refused]
+
+
+# --8<-- [start:transport]
+def where(*, call_context: Any) -> str:
+    """The transport this call came over, as its context says."""
+    return call_transport(call_context) or "in-process"
+
+
+where_registry = SpecRegistry()
+where_registry.register("where", ServiceSpec(service=where, permissions=[IsSignedIn()]))
+
+
+# yourapp/management/commands/where.py
+class Where(SpecCommand):
+    registry = where_registry
+
+
+# --8<-- [end:transport]

{django_spec_cli-0.4.1 → 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.25.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:
 
@@ -296,6 +307,44 @@ 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.
 
+## What a callable reads here
+
+Every callable a run reaches is handed one `call_context`, built by the
+kernel's
+[`build_call_context`][django_service_specs.types.build_call_context.build_call_context]
+and stamped last with this package's transport name, the plain string `"cli"`,
+exported as `django_spec_cli.CLI_TRANSPORT`. Read it with the kernel's
+[`call_transport`][django_service_specs.types.call_transport.call_transport],
+or compare `call_context["transport"] == "cli"` with nothing imported:
+
+```python
+--8<--
+docs/examples/commands.py:transport
+--8<--
+```
+
+- **One dict per run.** The command builds it ahead of everything it asks of
+  a spec and hands the same object to the declaration it reads for the
+  options it parses, then to `dispatch`, so a permission check, the
+  Validator's `parameters()` and `validate()`, a provider, the service and the
+  presenter all read `"cli"` from one dict.
+- **The standard entries are there as `None`.** `request`, `view`, `format`
+  and `action` are keys of the dict with no value, since a command line has
+  none. The kernel hands a callable declaring `request` or `view` `None` for
+  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, 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
+  may declare, so an entry a project needs in every call is a seed rather
+  than a key of the dict.
+
 ## What it does not do
 
 - **No payload file.** Arguments are options; an object or a list of rows has

{django_spec_cli-0.4.1 → django_spec_cli-0.6.0}/docs/reference.md

@@ -60,3 +60,4 @@ Registered by `DjangoSpecCliConfig`, so a project gets them by listing
 ## Types
 
 ::: django_spec_cli.types.exit_code.ExitCode
+::: django_spec_cli.types.cli_transport.CLI_TRANSPORT

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

@@ -48,8 +48,11 @@ dependencies = [
     # ``PermissionCheckDenied`` in ``REFUSALS``, which
     # ``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``.
-    "django-service-specs>=0.25.0",
+    # ``W001`` and ``W003``. 0.29.0 adds ``build_call_context``, which the
+    # 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]
@@ -149,7 +152,7 @@ skip-magic-trailing-comma = false
 root = ["./django_spec_cli"]
 
 [tool.bumpversion]
-current_version = "0.4.1"
+current_version = "0.6.0"
 allow_dirty = false
 commit = false
 tag = false

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

@@ -172,3 +172,10 @@ def test_a_run_of_the_refused_spec_raises_the_page_s_sentence() -> None:
 def test_whoami_is_the_user_named(capsys: pytest.CaptureFixture[str]) -> None:
     assert _run_from_argv("whoami --as-user 1") == 0
     assert capsys.readouterr().out == '"ada"\n'
+
+
+@pytest.mark.usefixtures("world")
+def test_the_transport_example_reads_cli() -> None:
+    out = io.StringIO()
+    call_command(commands.Where(), "where", "--as-user", "1", stdout=out)
+    assert out.getvalue() == '"cli"\n'