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

{django_spec_cli-0.6.0 → django_spec_cli-0.7.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@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
         with:
           enable-cache: true
       - name: Install

{django_spec_cli-0.6.0 → django_spec_cli-0.7.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@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
         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@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
         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@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
         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@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
         with:
           enable-cache: true
       - name: Install Python ${{ matrix.python-version }}

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

@@ -43,7 +43,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
         with:
           enable-cache: false
 

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

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] — 2026-11-14
+
+### Added
+- **A spec whose result is a file writes its bytes.** A spec presenting through the
+  kernel's `FilePresenter` was presented as JSON Lines, and the encoder refused its
+  `FileResult` with a `TypeError`. Its subcommand now writes the file's bytes to
+  `--output-file PATH`, an option only a file spec's subcommand takes, or else to
+  stdout's binary buffer when stdout is not a terminal. At a terminal without
+  `--output-file`, with `--table` or `--json`, with a stdout that takes no bytes, or with
+  a `PATH` that is a directory or whose directory does not exist, the run is a usage
+  error raised before the user is looked up or the spec is run, so nothing is written.
+  `SPEC_CLI_OUTPUT` is not read for it. The file's name, type and length go to stderr;
+  the name is never used as a path. The file is read whole before `PATH` is opened, so
+  a refused run leaves a file there as it was, and an `allow_none` spec finding
+  nothing writes nothing. A file spec the kernel's `file_output` refuses (a `LIST`
+  selector, `many`, `returns_many`, presented affordances) is refused as declared, for
+  its spec alone, and `django_spec_cli.W004` reports it. `write_file` is the new public
+  helper.
+
+### Changed
+- **The kernel floor is 0.33.0**, up from 0.30.0, for `FileResult`, `FilePresenter` and
+  `file_output`. Two things a selector with a `filter_set` shows change with it, both
+  the kernel's (0.31.0): `--help` lists a choice filter's labels beside its values, as
+  in `one of: ada (Ada Lovelace)`, since the kernel now hands them on; and on Django
+  5.0 or later a named group of choices held in a mapping offers and accepts its
+  members, where it offered the group's name and refused a member. A lazy affordance
+  reason reaches `ActionUnavailable` as text, as before, and the `QueryDict` a
+  `FormValidator` now binds is behind dispatch.
+- **`W003` is described as it behaves**: it reports any project command that fails to
+  load, since a command that will not import cannot be told apart from a `SpecCommand`.
+- **The API reference's docstrings are restored.** The docstrings the reference renders
+  carry their full text again.
+- **The guide states four things it left out.** The checks carry no tag, so a run
+  selecting by `--tag` skips them; finding the commands imports every command module
+  of the project's apps on each check run; a table hides a hidden field and JSON Lines
+  does not; and a table holds its whole result in memory.
+
 ## [0.6.0] — 2026-11-09
 
 ### Fixed
@@ -186,7 +223,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.6.0...HEAD
+[Unreleased]: https://github.com/Artui/django-spec-cli/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/Artui/django-spec-cli/compare/v0.6.0...v0.7.0
 [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

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

@@ -117,6 +117,27 @@ ships `py.typed`, so consumers get the annotations.
 Never a mypy-style `# type: ignore` in the package - a pre-commit hook rejects
 it.
 
+## Comment budget
+
+`#` comments and docstrings both count, in the package and in the tests:
+
+- A class: at most three lines (its docstring plus comments in its body outside its methods).
+- A function or method: at most one line (docstring plus comments inside it, or directly
+  above it).
+- A module: nothing before the first import (no module docstring, no header comment); a
+  package `__init__.py` with nothing to export is empty.
+- Exempt: directives (`# noqa`, `# ty:`, `# vX.Y.Z` pins), migrations, and a docstring
+  the code or a test reads through `__doc__`, which is data.
+
+A docstring a `:::` page renders (the object, and its public members unless `members:`
+narrows them) is exempt too: it is the API reference. Comments around it still count.
+Condense rather than move: a reason that does not fit is cut, not relocated to prose
+elsewhere. The exception is a walkthrough comment inside a `--8<--` snippet section of a
+`docs/` example: its prose moves onto the page beside the include. A body left empty by a removed docstring takes `...`. Ruff's E501 is on at 100
+columns and `ruff format` never wraps a comment, so a line that does not fit is
+condensed, not wrapped; an unbreakable string such as a URL takes `# noqa: E501`. The workbench's
+`bin/comment-budget.py` lists the violations.
+
 ## Linting and formatting
 
 `ruff` is the source of truth for both. Use `...` rather than `pass` for empty
@@ -139,7 +160,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.30.0 | the newest release, and the floor in the `floor` job |
+| django-service-specs | 0.33.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.6.0 → django_spec_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: django-spec-cli
-Version: 0.6.0
+Version: 0.7.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.30.0
+Requires-Dist: django-service-specs>=0.33.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.30.0 or
+Python 3.10 or later, Django 4.2 or later, and `django-service-specs` 0.33.0 or
 later, which it installs.
 
 ## Quickstart

{django_spec_cli-0.6.0 → django_spec_cli-0.7.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.30.0 or
+Python 3.10 or later, Django 4.2 or later, and `django-service-specs` 0.33.0 or
 later, which it installs.
 
 ## Quickstart

{django_spec_cli-0.6.0 → django_spec_cli-0.7.0}/django_spec_cli/__init__.py

@@ -1,5 +1,3 @@
-"""A registry of specs as a management command."""
-
 from django_spec_cli.argv.add_spec_arguments import add_spec_arguments
 from django_spec_cli.argv.describe_parameters import describe_parameters
 from django_spec_cli.argv.parameter_descriptor import ParameterDescriptor
@@ -9,6 +7,7 @@ from django_spec_cli.render.render_json_lines import render_json_lines
 from django_spec_cli.render.render_result import render_result
 from django_spec_cli.render.render_table import render_table
 from django_spec_cli.render.wants_table import wants_table
+from django_spec_cli.render.write_file import write_file
 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
@@ -26,6 +25,7 @@ __all__ = [
     "render_result",
     "render_table",
     "wants_table",
+    "write_file",
     "add_spec_arguments",
     "describe_parameters",
     "parsed_arguments",

django_spec_cli-0.7.0/django_spec_cli/apps.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from django.apps import AppConfig
+from django.core.checks import register
+
+from django_spec_cli.checks import check_unguarded_specs
+
+
+class DjangoSpecCliConfig(AppConfig):
+    """Registers the system check over every ``SpecCommand``'s specs, and does nothing else."""
+
+    name = "django_spec_cli"
+
+    def ready(self) -> None:
+        register(check_unguarded_specs)

{django_spec_cli-0.6.0 → django_spec_cli-0.7.0}/django_spec_cli/argv/__init__.py

@@ -1,5 +1,3 @@
-"""How a spec's parameters become command-line options, and come back as its arguments."""
-
 from django_spec_cli.argv.add_spec_arguments import add_spec_arguments
 from django_spec_cli.argv.describe_parameters import describe_parameters
 from django_spec_cli.argv.parameter_descriptor import ParameterDescriptor

{django_spec_cli-0.6.0 → django_spec_cli-0.7.0}/django_spec_cli/argv/add_spec_arguments.py

@@ -1,5 +1,3 @@
-"""``add_spec_arguments`` - one argparse option per parameter a command line can send."""
-
 from __future__ import annotations
 
 import argparse
@@ -100,8 +98,6 @@ def _add_option(parser: argparse.ArgumentParser, descriptor: ParameterDescriptor
         "help": _help(descriptor),
     }
     if descriptor.type == "boolean":
-        # No ``metavar``, ``type`` or ``choices``: a flag takes no value, and
-        # Python 3.12 deprecates passing them to this action.
         parser.add_argument(option, action=argparse.BooleanOptionalAction, **common)
         return
     parser.add_argument(
@@ -118,7 +114,6 @@ def _metavar(descriptor: ParameterDescriptor) -> str:
     if descriptor.format is not None:
         return descriptor.format.upper()
     kind = descriptor.items if descriptor.type == "array" else descriptor.type
-    # An ``any``, and an array declaring no element, take any value.
     return "VALUE" if kind in (None, "any") else kind.upper()
 
 
@@ -139,31 +134,19 @@ def _help(descriptor: ParameterDescriptor) -> str | None:
         notes.append("required")
     if descriptor.default is not UNSET:
         notes.append(f"default: {_text(descriptor.default)}")
-    # ``str``: a help text may be a lazy translation, rendered here.
     parts = [str(descriptor.help)] if descriptor.help else []
     if notes:
         parts.append("(" + "; ".join(notes) + ")")
-    # Argparse %-formats every help string, so a literal ``%`` - in the
-    # declared help, a choice, a label or a default - is doubled to print as
-    # written: test_a_percent_sign_in_any_help_text_is_printed_as_written.
+    # Argparse %-formats help, so a literal ``%`` is doubled to print as written.
     return " ".join(parts).replace("%", "%%") if parts else None
 
 
 def _choice(choice: Any, pairs: tuple[tuple[Any, str], ...]) -> str:
     """A choice as typed, with its label where one is declared."""
-    # Matched by type as well as value, as the declaration keeps them apart:
-    # ``1`` and ``True`` are equal to Python and two choices to a caller. Each
-    # condition is held by its own case of test_a_choice_is_shown_with_its_own_label:
-    # [equal-across-types] (the type) and [unlabelled] (the value).
     label = next((lb for v, lb in pairs if type(v) is type(choice) and v == choice), None)
     return _text(choice) if label is None else f"{_text(choice)} ({label})"
 
 
 def _text(value: Any) -> str:
-    """A value as it is typed: a string bare, anything else as its JSON.
-
-    An empty string is quoted, since bare it would read as no value at all.
-    """
-    # Each condition is held by its own test: test_an_empty_string_default_is_shown_quoted
-    # (the emptiness) and test_a_choice_that_is_not_a_string_is_listed_as_json (the type).
+    """A value as it is typed: a string bare unless empty, anything else as its JSON."""
     return value if isinstance(value, str) and value else json.dumps(value)

{django_spec_cli-0.6.0 → django_spec_cli-0.7.0}/django_spec_cli/argv/describe_parameters.py

@@ -1,5 +1,3 @@
-"""``describe_parameters`` - a spec's Parameters, as a command line sees them."""
-
 from __future__ import annotations
 
 import json
@@ -24,7 +22,7 @@ def describe_parameters(parameters: Parameters) -> tuple[ParameterDescriptor, ..
     Never refuses a declaration: a parameter with no flat spelling is
     described with ``argv=False`` rather than left out, so a command can still
     say in ``--help`` that a spec takes something argv cannot send.
-    """
+    """  # noqa: E501
     return tuple(_describe(param) for param in parameters)
 
 
@@ -34,11 +32,7 @@ def _describe(param: Parameter) -> ParameterDescriptor:
         type=param.type,
         format=param.format,
         items=param.items if isinstance(param.items, str) else None,
-        # The shape check's own rule for an absent argument, so the help says
-        # "(required)" exactly where an omission is refused. Each condition is
-        # held by its own test: test_required_means_an_omitted_option_is_refused
-        # (the declaration) and test_a_required_parameter_with_a_default_is_not_required
-        # (the default, reported or not).
+        # The shape check's rule for an omitted argument: "(required)" marks a refused omission.
         required=param.required and param.default is UNSET,
         default=_shown_default(param.default),
         choices=param.choices,
@@ -53,26 +47,14 @@ def _describe(param: Parameter) -> ParameterDescriptor:
 
 
 def _has_flat_spelling(param: Parameter) -> bool:
-    # Read from the type rather than from ``nested``, which alone is narrower
-    # than "no honest option": an object with no ``fields`` and an array of
-    # ``object``, ``array`` or ``file`` elements have no nested Parameters and
-    # still no string that spells them. Held by
-    # test_a_parameter_with_no_flat_spelling_has_no_option, one case per type,
-    # and test_every_parameter_a_command_line_can_send_has_an_option.
+    # Read from the type: ``nested`` is narrower than "no honest option".
     if param.type == "array":
         return param.items in _FLAT_ELEMENTS
     return param.type in _FLAT_TYPES
 
 
 def _shown_default(default: Any) -> Any:
-    """The default, where JSON spells it; otherwise ``UNSET``, so nothing is shown.
-
-    One check rather than a list of exclusions: ``json.dumps`` refuses
-    ``UNSET``, a callable and any other object it has no spelling for, and
-    ``allow_nan=False`` refuses NaN and the infinities, which Python's encoder
-    would otherwise write as tokens no JSON reader takes. Each is a case of
-    test_a_default_with_no_json_spelling_is_not_reported.
-    """
+    """The default, where JSON spells it; otherwise ``UNSET``, so nothing is shown."""
     try:
         json.dumps(default, allow_nan=False)
     except (TypeError, ValueError):

{django_spec_cli-0.6.0 → django_spec_cli-0.7.0}/django_spec_cli/argv/parameter_descriptor.py

@@ -1,5 +1,3 @@
-"""``ParameterDescriptor`` - one parameter, as a command line sees it."""
-
 from __future__ import annotations
 
 from dataclasses import dataclass

{django_spec_cli-0.6.0 → django_spec_cli-0.7.0}/django_spec_cli/argv/parsed_arguments.py

@@ -1,5 +1,3 @@
-"""``parsed_arguments`` - the options argparse read, as the raw arguments ``coerce_flat`` takes."""
-
 from __future__ import annotations
 
 import argparse
@@ -32,7 +30,7 @@ def parsed_arguments(namespace: argparse.Namespace, parameters: Parameters) -> d
     A value set there by a caller other than argparse, as ``call_command``
     does with keyword arguments, is handed on as it was set, except that a
     ``bool`` for a ``boolean`` is spelled as argparse's would have been.
-    """
+    """  # noqa: E501
     values = vars(namespace)
     raw: dict[str, Any] = {}
     for param in parameters:
@@ -40,10 +38,6 @@ def parsed_arguments(namespace: argparse.Namespace, parameters: Parameters) -> d
         if key not in values:
             continue
         value = values[key]
-        # Each condition is held by its own case of
-        # test_a_value_given_by_destination_rather_than_argv_is_handed_on: a
-        # string for a boolean stays the string, and a ``bool`` for an ``any``
-        # stays the ``bool``.
         if param.type == "boolean" and isinstance(value, bool):
             value = "true" if value else "false"
         raw[param.name] = value

{django_spec_cli-0.6.0 → django_spec_cli-0.7.0}/django_spec_cli/argv/utils.py

@@ -1,5 +1,3 @@
-"""Helpers ``argv/`` and ``SpecCommand`` share: how a parameter's name becomes argv and back."""
-
 from __future__ import annotations
 
 DESTINATION_PREFIX = "spec_arg__"

django_spec_cli-0.7.0/django_spec_cli/checks.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from collections.abc import Iterator, Sequence
+from typing import Any
+
+from django.apps import AppConfig
+from django.core.checks import CheckMessage, Warning
+from django.core.exceptions import ImproperlyConfigured
+from django.core.management import get_commands, load_command_class
+from django_service_specs import UnguardedSpec, check_seeds, unguarded_specs
+
+from django_spec_cli.report.unguarded_message import unguarded_message
+from django_spec_cli.report.utils import refused_message
+from django_spec_cli.spec_command import SpecCommand
+
+_HINT = (
+    "Declare a PermissionCheck that refuses someone in the spec's permissions, or add "
+    "'django_spec_cli.W001' to SILENCED_SYSTEM_CHECKS if the spec is meant to be open."
+)
+_REFUSED_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."
+)
+
+
+def check_unguarded_specs(
+    app_configs: Sequence[AppConfig] | None, **kwargs: Any
+) -> list[CheckMessage]:
+    """Warn once per spec that authorizes nothing or can't run, in every project ``SpecCommand``."""
+    messages: list[CheckMessage] = []
+    for name, app_name, loaded in _spec_commands(app_configs):
+        if isinstance(loaded, Exception):
+            messages.append(
+                Warning(
+                    f"The command {name!r} from {app_name} could not be set up, so its specs "
+                    f"were not checked: {type(loaded).__name__}: {loaded}",
+                    hint=(
+                        f"Run manage.py {name} to see the traceback. Until it loads, the specs "
+                        "it serves are not checked."
+                    ),
+                    id="django_spec_cli.W003",
+                )
+            )
+            continue
+        command, specs = loaded
+        messages.extend(
+            Warning(
+                unguarded_message(spec, name),
+                hint=_HINT,
+                obj=type(command),
+                id="django_spec_cli.W001",
+            )
+            for spec in specs
+        )
+        messages.extend(
+            Warning(
+                refused_message(spec_name, name, error),
+                hint=_REFUSED_HINT,
+                obj=type(command),
+                id="django_spec_cli.W004",
+            )
+            for spec_name, error in _refused(command)
+        )
+    return messages
+
+
+def _refused(command: SpecCommand) -> Iterator[tuple[str, ImproperlyConfigured]]:
+    """Each spec of ``command`` a run refuses as declared, with its refusal, in registry order."""
+    for entry in command.registry:
+        try:
+            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(
+    app_configs: Sequence[AppConfig] | None,
+) -> Iterator[tuple[str, str, tuple[SpecCommand, tuple[UnguardedSpec, ...]] | Exception]]:
+    """Each ``SpecCommand`` the project serves: its unguarded specs, or why it will not load."""
+    wanted = None if app_configs is None else {config.name for config in app_configs}
+    for name, app_name in get_commands().items():
+        if app_name == "django.core" or (wanted is not None and app_name not in wanted):
+            continue
+        try:
+            command = load_command_class(app_name, name)
+            if not isinstance(command, SpecCommand):
+                continue
+            command.create_parser("manage.py", name)
+            loaded: tuple[SpecCommand, tuple[UnguardedSpec, ...]] | Exception = (
+                command,
+                unguarded_specs(command.registry),
+            )
+        except Exception as error:
+            loaded = error
+        yield name, app_name, loaded

{django_spec_cli-0.6.0 → django_spec_cli-0.7.0}/django_spec_cli/exit_code_for.py

@@ -1,5 +1,3 @@
-"""``exit_code_for`` - the exit status a refusal ends a ``SpecCommand`` run with."""
-
 from __future__ import annotations
 
 from django_service_specs import (

{django_spec_cli-0.6.0 → django_spec_cli-0.7.0}/django_spec_cli/render/__init__.py

@@ -1,13 +1,13 @@
-"""How a command writes a presented result: a table for a terminal, JSON lines for a pipe."""
-
 from django_spec_cli.render.render_json_lines import render_json_lines
 from django_spec_cli.render.render_result import render_result
 from django_spec_cli.render.render_table import render_table
 from django_spec_cli.render.wants_table import wants_table
+from django_spec_cli.render.write_file import write_file
 
 __all__ = [
     "render_json_lines",
     "render_result",
     "render_table",
     "wants_table",
+    "write_file",
 ]

{django_spec_cli-0.6.0 → django_spec_cli-0.7.0}/django_spec_cli/render/render_json_lines.py

@@ -1,5 +1,3 @@
-"""``render_json_lines`` - presented rows as JSON Lines, one object per line, streamed."""
-
 from __future__ import annotations
 
 from collections.abc import Iterable, Mapping

{django_spec_cli-0.6.0 → django_spec_cli-0.7.0}/django_spec_cli/render/render_result.py

@@ -1,5 +1,3 @@
-"""``render_result`` - what ``present`` returned, written as a table or as JSON Lines."""
-
 from __future__ import annotations
 
 from collections.abc import Iterable, Mapping
@@ -45,19 +43,10 @@ def render_result(presented: Any, output: Output | None, stream: TextIO, *, tabl
     """
     if presented is None:
         return
-    # A mapping and a string are both iterable, and each is one value rather
-    # than a sequence of rows, so both are answered before the iterable check.
-    # Three conditions in one branch arc, each held by its own test:
-    # the ``str`` cases of test_a_scalar_is_a_result_column_or_one_line_of_its_json
-    # (``str``), test_bytes_are_a_scalar_and_never_iterated_as_rows
-    # (``bytes``), and the ``int`` cases of the first (no iterable, which
-    # iterating would raise on).
     if isinstance(presented, Mapping):
         rows: Iterable[Any] = (presented,)
     elif isinstance(presented, str | bytes) or not isinstance(presented, Iterable):
         rows = (presented,)
-        # A scalar has no declared field to sit under, whatever the spec
-        # declares, so its table is the one ``result`` column.
         output = None
     else:
         rows = presented

{django_spec_cli-0.6.0 → django_spec_cli-0.7.0}/django_spec_cli/render/render_table.py

@@ -1,5 +1,3 @@
-"""``render_table`` - presented rows as an aligned plain-text table."""
-
 from __future__ import annotations
 
 import json
@@ -100,8 +98,6 @@ def render_table(rows: Sequence[Mapping[str, Any]], output: Output | None, strea
     if not columns:
         return
     lines = [
-        # A header is escaped as a cell is: with no declared output it is a
-        # row's own key, which could carry a line break as well as a value.
         [_text(column.header) for column in columns],
         *([_cell(row.get(column.name), column.choices) for column in columns] for row in rows),
     ]
@@ -111,9 +107,6 @@ def render_table(rows: Sequence[Mapping[str, Any]], output: Output | None, strea
             _pad(text, width, right=column.right)
             for text, width, column in zip(line, widths, columns, strict=True)
         )
-        # One write per line, ending in a newline: Django's ``OutputWrapper``
-        # appends one to any message that does not end in it. ``rstrip`` drops
-        # the padding of an empty or short last cell.
         stream.write(_GAP.join(cells).rstrip() + "\n")
 
 
@@ -124,21 +117,14 @@ def _columns(rows: Sequence[Mapping[str, Any]], output: Output | None) -> tuple[
 
 
 def _audience(field: OutputField) -> FieldAudience | None:
-    # Coverage sees no branch in a conditional expression, so each arm is
-    # named: test_an_unmarked_field_without_choices_is_shown_as_presented holds
-    # the ``None`` (without it ``None.audience`` raises), and
-    # test_a_hidden_field_is_no_column_and_every_other_audience_is_one the
-    # marking's own audience.
+    # ``None`` for an unmarked field, which has no audience to read.
     return None if field.marking is None else field.marking.audience
 
 
 def _column(field: OutputField) -> _Column:
-    # Only a handle keeps its value, not every marked field:
-    # test_a_handle_keeps_its_value_even_with_choices and
-    # test_a_label_with_choices_is_shown_by_its_display.
+    # Only a handle keeps its value, not every marked field.
     return _Column(
         field.name,
-        # ``str()`` for a lazy translation, read in the active language.
         field.name if field.label is None else str(field.label),
         right=field.type in _NUMERIC,
         choices=None if _audience(field) is FieldAudience.HANDLE else field.choices,
@@ -153,25 +139,14 @@ def _cell(value: Any, choices: tuple[tuple[Any, Any], ...] | None) -> str:
     if isinstance(value, str):
         return _text(value)
     encoded = compact_json(value)
-    # A value the encoder writes as a JSON string - a Decimal, a date-time, a
-    # UUID, a lazy translation - is shown without its quotes, as text is.
+    # A value the encoder writes as a JSON string is shown without its quotes, as text is.
     return _text(json.loads(encoded) if encoded.startswith('"') else encoded)
 
 
 def _display(value: Any, choices: tuple[tuple[Any, Any], ...]) -> Any:
-    """The display of the choice ``value`` names, or ``value`` itself.
-
-    Compared by equality rather than looked up in a dict, so an unhashable
-    value is compared rather than raising. A lazy display is left lazy: the
-    encoder in ``_cell`` reads it in the active language. An array of choices is displayed
-    member by member, as the agent projection speaks it. One ``isinstance``
-    over two kinds, so each is held by its own case of
-    test_an_array_of_choices_is_shown_member_by_member.
-    """
+    """The display of the choice ``value`` names, or ``value`` itself."""
     if isinstance(value, list | tuple):
         return [_display(member, choices) for member in value]
-    # Matched by type as well as value, as the declaration keeps them apart:
-    # ``1`` and ``True`` are equal to Python and two choices to a caller.
     return next(
         (display for choice, display in choices if type(choice) is type(value) and choice == value),
         value,

{django_spec_cli-0.6.0 → django_spec_cli-0.7.0}/django_spec_cli/render/utils.py

@@ -1,5 +1,3 @@
-"""Helpers the render modules share: one encoding of a value as JSON, for a line and for a cell."""
-
 from __future__ import annotations
 
 import json
@@ -9,8 +7,5 @@ from django.core.serializers.json import DjangoJSONEncoder
 
 
 def compact_json(value: Any) -> str:
-    """``value`` as compact JSON, its text written as itself, as ``DjangoJSONEncoder`` encodes it.
-
-    What the encoder has no spelling for raises ``TypeError``.
-    """
+    """``value`` as compact JSON, its text written as itself, as ``DjangoJSONEncoder`` does."""
     return json.dumps(value, cls=DjangoJSONEncoder, ensure_ascii=False, separators=(",", ":"))

{django_spec_cli-0.6.0 → django_spec_cli-0.7.0}/django_spec_cli/render/wants_table.py

@@ -1,5 +1,3 @@
-"""``wants_table`` - whether a command's result is written as a table or as JSON Lines."""
-
 from __future__ import annotations
 
 from typing import Literal, TextIO
@@ -29,9 +27,5 @@ def wants_table(stream: TextIO, *, requested: Literal["table", "json"] | None) -
     choice = requested if requested is not None else command_output()
     if choice == "auto":
         isatty = getattr(stream, "isatty", None)
-        # One branch to coverage, so each condition is held by its own test:
-        # test_a_stream_that_cannot_say_is_not_a_terminal (the first, without
-        # which ``None()`` raises) and
-        # test_a_terminal_gets_a_table_and_a_pipe_gets_json_lines (the second).
         return isatty is not None and bool(isatty())
     return choice == "table"