django-spec-cli 0.3.0__tar.gz → 0.3.1__tar.gz

{django_spec_cli-0.3.0 → django_spec_cli-0.3.1}/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.1] — 2026-11-04
+
+### Fixed
+- **`--help` offers and requires what dispatch asks a caller for.** A
+  subcommand's options, and which of them are marked `(required)`, are now
+  read from the kernel's `spec_caller_input_schema` under the command's
+  `pool_seeds`, rather than from `server_owned_keys` read without them. On any
+  kernel from 0.15.0, two parameters were shown wrongly. A read declared
+  required beside a provider that may fill it, such as a `kwargs` provider
+  whose return names no keys, was marked `(required)`, though a run leaving
+  it out was dispatched. A `reflected` read named like a seed the command's
+  `pool_seeds` registers was offered as an option and marked `(required)`,
+  and passing it was refused as an unknown argument, exit code 3. It is no
+  longer an option. No public name changes.
+
 ## [0.3.0] — 2026-11-04
 
 ### Changed
@@ -67,7 +82,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.3.0...HEAD
+[Unreleased]: https://github.com/Artui/django-spec-cli/compare/v0.3.1...HEAD
+[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
 [0.2.1]: https://github.com/Artui/django-spec-cli/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/Artui/django-spec-cli/compare/v0.1.0...v0.2.0

{django_spec_cli-0.3.0 → django_spec_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: django-spec-cli
-Version: 0.3.0
+Version: 0.3.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.3.0 → django_spec_cli-0.3.1}/django_spec_cli/spec_command.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import argparse
 import inspect
 from collections.abc import Mapping
+from dataclasses import replace
 from typing import Any, TextIO, cast
 
 from django.core.exceptions import ImproperlyConfigured
@@ -30,9 +31,8 @@ from django_service_specs import (
     kernel_spec,
     present,
     refusal_messages,
-    relax_partial,
     resolve_principal,
-    server_owned_keys,
+    spec_caller_input_schema,
     unguarded_specs,
 )
 
@@ -72,8 +72,10 @@ class SpecCommand(BaseCommand):
     - **One subcommand per registry entry**, named after the entry with each
       ``_`` shown as ``-``. Its options are the spec's parameters, as
       [`add_spec_arguments`][django_spec_cli.argv.add_spec_arguments.add_spec_arguments]
-      spells them, less any key the server fills
-      ([`server_owned_keys`][django_service_specs.specs.server_owned_keys.server_owned_keys]).
+      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
+      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.
     - **``--as-user`` is required.** Its value goes through
@@ -162,7 +164,7 @@ class SpecCommand(BaseCommand):
                 )
             self._entries[name] = entry
             spec = kernel_spec(entry.spec)
-            parameters = _sendable(spec)
+            parameters = _sendable(spec, self.pool_seeds)
             summary = _summary(spec, entry.name)
             subparser = subparsers.add_parser(
                 name,
@@ -281,18 +283,30 @@ class SpecCommand(BaseCommand):
             self.stdout.write(unguarded_message(unguarded, label))
 
 
-def _sendable(spec: ServiceSpec | SelectorSpec) -> Parameters:
-    """What a caller may send, as the shape check reads it: required only where dispatch demands it.
-
-    Relaxed for ``partial`` by the shape check's own reading, so ``--help``
-    marks ``(required)`` exactly where an omission is refused
-    (test_a_partial_spec_requires_only_what_names_its_row), and without the
-    keys the server fills, whose value a caller's would never replace
-    (test_a_key_the_server_fills_is_no_option).
+def _sendable(spec: ServiceSpec | SelectorSpec, pool_seeds: PoolSeeds) -> 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
+    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).
+    Each is relaxed where the schema does not require it, so ``--help``
+    marks ``(required)`` exactly where an omission is refused: on a
+    ``partial`` spec (test_a_partial_spec_requires_only_what_names_its_row)
+    and beside a provider that may fill it
+    (test_a_read_a_provider_may_fill_is_offered_and_not_required). Only
+    relaxed, never made required, so a declared default still answers.
     """
-    owned = server_owned_keys(spec)
-    relaxed = relax_partial(spec, spec.parameters())
-    return Parameters.of(*(param for param in relaxed if param.name not in owned))
+    schema = spec_caller_input_schema(spec, pool_seeds=pool_seeds)
+    required = frozenset(schema.get("required", ()))
+    return Parameters.of(
+        *(
+            param if param.name in required else replace(param, required=False)
+            for param in spec.parameters()
+            if param.name in schema["properties"]
+        )
+    )
 
 
 def _summary(spec: ServiceSpec | SelectorSpec, name: str) -> str:

{django_spec_cli-0.3.0 → django_spec_cli-0.3.1}/django_spec_cli/version.py

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

{django_spec_cli-0.3.0 → django_spec_cli-0.3.1}/docs/index.md

@@ -86,14 +86,20 @@ equals sign: `--tag=-x`.
 of its service's or selector's docstring and whether it reads or writes, or
 its registered name when the function says nothing. `manage.py notes
 rename-note --help` lists its options, with `(required)` where leaving one
-out is refused. On a `partial` spec, that is only what names the row: the
-Validator's fields may be left out, as dispatch allows.
+out is refused. Both are read from the input schema a transport advertises,
+[`spec_caller_input_schema`][django_service_specs.schema.spec_caller_input_schema.spec_caller_input_schema],
+under the command's `pool_seeds`, so the command asks for what dispatch asks
+for. On a `partial` spec, `(required)` is only what names the row: the
+Validator's fields may be left out, as dispatch allows. A parameter a provider
+may fill, such as a read beside a `kwargs` provider whose return names no keys,
+is an option and is not required.
 
 Some parameters have no option:
 
-- **A key the server fills**, one a `kwargs` provider is annotated to answer
-  ([`server_owned_keys`][django_service_specs.specs.server_owned_keys.server_owned_keys]),
-  since a value sent for it would be dropped.
+- **A key the server fills**: one a `kwargs` provider is annotated to answer,
+  since a value sent for it would be dropped, and a `reflected` read named like
+  a seed `pool_seeds` registers, since the seed fills it and dispatch refuses an
+  argument of its name.
 - **A parameter with no flat spelling**: an object, an array of objects or of
   arrays, and a file. The subcommand's help names them. A spec that requires
   one, such as any `many` spec, cannot be run from the command line.

{django_spec_cli-0.3.0 → django_spec_cli-0.3.1}/pyproject.toml

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

{django_spec_cli-0.3.0 → django_spec_cli-0.3.1}/tests/test_spec_command.py

@@ -297,6 +297,23 @@ class TestSeeds:
         command = command_over(self._registry(), pool_seeds=seeds)
         assert run("greet", "--as-user", str(owner.pk), command=command) == '"hello acme"\n'
 
+    def test_a_reflected_read_a_seed_fills_is_an_option_only_without_the_seed(
+        self, capsys: pytest.CaptureFixture[str], owner: Any
+    ) -> None:
+        # Offered under the command's seeds, it would be refused when passed,
+        # as an argument dispatch does not take.
+        def greet(*, tenant: str) -> str:
+            return f"hello {tenant}"
+
+        reads = Parameters.of(Parameter("tenant", "string", required=True, reflected=True))
+        spec = ServiceSpec(service=greet, permissions=[Unrestricted()], reads=reads)
+        registry = registry_of(greet=spec)
+        seeded = command_over(registry, pool_seeds=DEFAULT_POOL_SEEDS.extend(tenant=lambda: "acme"))
+        assert "--tenant" not in help_of(capsys, "greet", command=seeded)
+        assert run("greet", "--as-user", str(owner.pk), command=seeded) == '"hello acme"\n'
+        unseeded = " ".join(help_of(capsys, "greet", command=command_over(registry)).split())
+        assert "--tenant STRING (required)" in unseeded
+
     def test_with_no_seeds_named_a_callable_reading_one_fails_as_dispatch_does(
         self, owner: Any
     ) -> None:
@@ -428,6 +445,21 @@ class TestHelp:
         assert "--project" not in text
         assert "--n INTEGER" in text
 
+    def test_a_read_a_provider_may_fill_is_offered_and_not_required(
+        self, capsys: pytest.CaptureFixture[str], owner: Any
+    ) -> None:
+        # A return that says nothing about its keys may fill any read, so
+        # dispatch demands none of them of the caller and the help asks for none.
+        def may_fill(**_: Any) -> dict[str, Any]:
+            return {"project": 1}
+
+        spec = echo_spec(Parameter("project", "integer", required=True), kwargs=may_fill)
+        command = command_over(registry_of(echo=spec))
+        text = " ".join(help_of(capsys, "echo", command=command).split())
+        assert "--project INTEGER" in text
+        assert "(required)" not in text
+        assert lines(run("echo", "--as-user", str(owner.pk), command=command)) == [{"project": 1}]
+
 
 # --- output --------------------------------------------------------------------------------------