django-spec-cli 0.1.0__py3-none-any.whl

django_spec_cli/render/render_json_lines.py

@@ -0,0 +1,42 @@
+"""``render_json_lines`` - presented rows as JSON Lines, one object per line, streamed."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from typing import Any, TextIO
+
+from django_spec_cli.render.utils import compact_json
+
+# JSON escapes every C0 control character and leaves these three raw. Each is
+# a line break to some readers - Python's ``str.splitlines`` among them - so a
+# value carrying one would end a line where the JSON Lines format says no line
+# ends. They can only occur inside a JSON string, so replacing them in the
+# encoded text changes no structure and decodes to the same value.
+_LINE_BREAKS = {"
": "\\u2028", "
": "\\u2029", "\x85": "\\u0085"}
+
+
+def render_json_lines(rows: Iterable[Mapping[str, Any]], stream: TextIO) -> None:
+    """Write each row to ``stream`` as one line of JSON.
+
+    **Streamed**: each row is encoded and written before the next is read, so
+    a generator over a large result is never held in memory whole. That is
+    why the format is JSON Lines rather than one JSON array.
+
+    Each row is written as it was presented: every key, in the row's own
+    order, including a key no ``Output`` declares (the ``affordances``
+    ``present`` adds) and a field marked hidden, which is how an HTTP response
+    carries it too. Text is written as itself (``ensure_ascii=False``), and
+    ``DjangoJSONEncoder`` encodes what JSON has no type for: a ``Decimal`` as
+    its string, a date-time, date or time in ISO 8601, a ``UUID``, a lazy
+    translation in the active language. A value the encoder refuses raises
+    ``TypeError`` before its line is written.
+
+    One ``write`` per line, each ending in ``"\\n"``: Django's
+    ``OutputWrapper`` appends a newline to any message that does not end in
+    one, so a line written in pieces would come out broken.
+    """
+    for row in rows:
+        line = compact_json(row)
+        for raw, escaped in _LINE_BREAKS.items():
+            line = line.replace(raw, escaped)
+        stream.write(line + "\n")

django_spec_cli/render/render_result.py

@@ -0,0 +1,71 @@
+"""``render_result`` - what ``present`` returned, written as a table or as JSON Lines."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from typing import Any, TextIO
+
+from django_service_specs import Output
+
+from django_spec_cli.render.render_json_lines import render_json_lines
+from django_spec_cli.render.render_table import render_table
+
+# The column a value that is no row is shown under in a table.
+_RESULT = "result"
+
+
+def render_result(presented: Any, output: Output | None, stream: TextIO, *, table: bool) -> None:
+    """Write ``presented`` to ``stream``, as a table when ``table`` and JSON Lines when not.
+
+    ``presented`` is what
+    [`present`][django_service_specs.dispatch.present.present] returned for a
+    spec, and ``output`` what the spec declares (``spec.output()``), which
+    gives a table its columns. Read in this order:
+
+    - ``None``, what a service that returned nothing presents: **nothing is
+      written**, in either format. A header over no rows would read as an
+      empty list.
+    - **a mapping**, one row: a one-row table, or one line.
+    - **a string or bytes**, a scalar, though both are iterable: a string is
+      never read as rows of its characters. Bytes are refused by the JSON
+      encoder with ``TypeError``, as an HTTP response refuses them.
+    - **any other iterable**, rows: a table, or one line each, streamed, so a
+      generator is read one row at a time and nothing here turns it into a
+      list. A member that is no mapping - a spec with no presenter listing
+      plain values - is a row of one ``result`` column in a table, and its
+      own JSON on its own line.
+    - anything else, **a scalar**: a table of one ``result`` column and one
+      row, or one line holding its JSON (``42``, ``"done"``, ``true``).
+
+    A table reads every row before writing its first line; see
+    [`render_table`][django_spec_cli.render.render_table.render_table]
+    for its columns, cells and markings, and
+    [`render_json_lines`][django_spec_cli.render.render_json_lines.render_json_lines]
+    for the encoding. Only ``stream`` is written to.
+    """
+    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
+    if table:
+        render_table([_row(row) for row in rows], output, stream)
+    else:
+        render_json_lines(rows, stream)
+
+
+def _row(row: Any) -> Mapping[str, Any]:
+    return row if isinstance(row, Mapping) else {_RESULT: row}

django_spec_cli/render/render_table.py

@@ -0,0 +1,203 @@
+"""``render_table`` - presented rows as an aligned plain-text table."""
+
+from __future__ import annotations
+
+import json
+import unicodedata
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any, TextIO
+
+from django_service_specs import FieldAudience, Output, OutputField
+
+from django_spec_cli.render.utils import compact_json
+
+# Two spaces between columns: one reads as a space inside a value.
+_GAP = "  "
+# Unicode categories that move the cursor or the line rather than print: the
+# C0 and C1 controls (newline, tab, the escape that starts a terminal
+# sequence) and the line and paragraph separators. Written escaped, so a row
+# can neither split itself across two lines nor drive the operator's terminal.
+_BREAKING = frozenset({"Cc", "Zl", "Zp"})
+_NUMERIC = frozenset({"integer", "number"})
+# East Asian wide and full-width: two terminal columns each.
+_WIDE = frozenset({"W", "F"})
+# Nonspacing and enclosing marks and format characters: drawn on or between
+# their neighbours, so no column of their own. ``unicodedata.combining`` is
+# not this test - it answers a canonical combining class, which a variation
+# selector and an enclosing mark both have as zero.
+_ZERO_WIDTH = frozenset({"Mn", "Me", "Cf"})
+
+
+@dataclass(frozen=True)
+class _Column:
+    name: str
+    header: str
+    right: bool = False
+    # ``None`` where the value is shown as presented: no choices declared, or a
+    # handle, whose value is what the next command takes.
+    choices: tuple[tuple[Any, Any], ...] | None = None
+
+
+def render_table(rows: Sequence[Mapping[str, Any]], output: Output | None, stream: TextIO) -> None:
+    """Write ``rows`` to ``stream`` as a table with a header line.
+
+    **The columns are the declared ``output``'s, never the rows'**: its fields
+    in declaration order, each headed by its ``label``, else its name. So an
+    empty result still prints its header, a row with a null never shifts a
+    column, and a key a row carries that ``output`` does not declare - the
+    ``affordances`` that ``present`` adds - is no column. JSON Lines, which
+    writes each row whole, is where such a key is read.
+
+    A cell is:
+
+    - **empty** for a null, and for a key the row leaves out, as a presenter
+      may for a field not ``always_present``. The table cannot tell the two
+      apart; JSON Lines can.
+    - a choice's **display** rather than its value, read in the active
+      language, member by member for an array of choices. A value no choice
+      names is shown as itself. A field marked as a handle keeps its value,
+      because the operator pastes it into the next command, which takes the
+      value.
+    - **compact JSON** for a nested object or array, in one cell.
+    - otherwise the value in JSON's spelling with a string's quotes left off:
+      ``true``, ``12.50`` for a ``Decimal``, ISO 8601 for a date-time.
+
+    A line break, tab or other control character inside a value is written
+    escaped (``\\n``, ``\\x1b``), so a row stays on one line and a value
+    cannot send the terminal an escape sequence.
+
+    **Markings.** A field marked hidden is no column. Its marking says it is
+    plumbing, and the projection for an agent drops it for that reason; a
+    person reading a table has no more use for it. That is a choice of
+    readability and not a secret kept: no marking means a field never leaves
+    the server, so an HTTP response and JSON Lines both carry a hidden field.
+    Label, handle and ordinary content fields are columns. A marking's
+    formatter is how an agent audience reads a value, and a command names no
+    audience, so it is not applied.
+
+    ``output=None``, a spec that declares no output, is the one case a row is
+    read for its columns: the first row's keys, in its order. With no rows
+    there are then no columns, and nothing is printed; an ``Output`` with no
+    fields prints nothing either.
+
+    Plain text: columns padded with spaces, separated by two, numbers
+    (``integer`` and ``number`` fields) right-aligned and everything else
+    left-aligned, no colour and no box drawing, and no line ending in
+    whitespace. Widths are measured in terminal columns, per character: an
+    East Asian wide or full-width character counts two, most emoji among
+    them; a combining or enclosing mark and a format character (a zero-width
+    joiner, a variation selector) count none; anything else counts one. That
+    is an approximation of what a terminal draws, not a measurement of it:
+    an East Asian ambiguous character a terminal draws wide, or an emoji
+    sequence it draws as one glyph, leaves its row a column or two off.
+
+    **Every row is read before the first line is written**, because a
+    column's width is its widest cell. A table therefore holds the whole
+    result in memory; JSON Lines is the format that streams.
+    """
+    columns = _columns(rows, output)
+    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),
+    ]
+    widths = [max(_width(line[n]) for line in lines) for n in range(len(columns))]
+    for line in lines:
+        cells = (
+            _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")
+
+
+def _columns(rows: Sequence[Mapping[str, Any]], output: Output | None) -> tuple[_Column, ...]:
+    if output is None:
+        return tuple(_Column(str(key), str(key)) for key in rows[0]) if rows else ()
+    return tuple(_column(field) for field in output if _audience(field) is not FieldAudience.HIDDEN)
+
+
+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.
+    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.
+    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,
+    )
+
+
+def _cell(value: Any, choices: tuple[tuple[Any, Any], ...] | None) -> str:
+    if value is None:
+        return ""
+    if choices is not None:
+        value = _display(value, choices)
+    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.
+    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.
+    """
+    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,
+    )
+
+
+def _text(value: str) -> str:
+    return "".join(
+        char.encode("unicode_escape").decode("ascii")
+        if unicodedata.category(char) in _BREAKING
+        else char
+        for char in value
+    )
+
+
+def _width(text: str) -> int:
+    return sum(
+        0
+        if unicodedata.category(char) in _ZERO_WIDTH
+        else 2
+        if unicodedata.east_asian_width(char) in _WIDE
+        else 1
+        for char in text
+    )
+
+
+def _pad(text: str, width: int, *, right: bool) -> str:
+    fill = " " * (width - _width(text))
+    return fill + text if right else text + fill

django_spec_cli/render/utils.py

@@ -0,0 +1,16 @@
+"""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
+from typing import Any
+
+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``.
+    """
+    return json.dumps(value, cls=DjangoJSONEncoder, ensure_ascii=False, separators=(",", ":"))

django_spec_cli/render/wants_table.py

@@ -0,0 +1,37 @@
+"""``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
+
+from django_spec_cli.settings import command_output
+
+
+def wants_table(stream: TextIO, *, requested: Literal["table", "json"] | None) -> bool:
+    """Whether to write a table to ``stream`` rather than JSON Lines.
+
+    Three answers, the first that decides winning:
+
+    1. ``requested``: what the operator asked for with ``--table`` or
+       ``--json``. The setting is not read at all when the flag decides, so a
+       misconfigured setting never overrides an explicit request.
+    2. The project's ``SPEC_CLI_OUTPUT`` setting, when it pins
+       ``"table"`` or ``"json"``.
+    3. ``stream.isatty()``: a table for a person at a terminal, JSON Lines for
+       a pipe, a file or a test's buffer. A stream with no ``isatty`` cannot
+       say it is a terminal and gets JSON Lines.
+
+    That third answer means an interactive run and CI print different things
+    by default, which is why both the flag and the setting exist. Django's
+    ``OutputWrapper``, which is what a command's ``self.stdout`` is, answers
+    ``isatty`` for the stream it wraps.
+    """
+    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"

django_spec_cli/report/__init__.py

@@ -0,0 +1,7 @@
+"""The wording of a registry's open specs, shared by a command's ``--explain`` and the system check."""
+
+from django_spec_cli.report.unguarded_message import unguarded_message
+
+__all__ = [
+    "unguarded_message",
+]

django_spec_cli/report/unguarded_message.py

@@ -0,0 +1,29 @@
+"""``unguarded_message`` - the sentence that reports one unguarded spec."""
+
+from __future__ import annotations
+
+from django_service_specs import UnguardedReason, UnguardedSpec
+
+# One clause per reason, indexed rather than branched on, so a member added
+# without its sentence fails test_every_reason_has_its_own_wording instead of
+# printing another member's.
+_WHY = {
+    UnguardedReason.UNRESTRICTED: "every permission check it declares is Unrestricted",
+}
+
+
+def unguarded_message(spec: UnguardedSpec, command_label: str) -> str:
+    """The one-line report of ``spec``, served by the command ``command_label``.
+
+    ``command_label`` is the name an operator types after ``manage.py``. The
+    system check and the command's own listing both print this, so the two
+    read the same.
+
+    The sentence says "any active user": dispatch refuses a deactivated
+    principal whatever the spec's checks allow, so an open spec is open to
+    every account that can still sign in, and to no other.
+    """
+    return (
+        f"{spec.name!r} in manage.py {command_label} authorizes nothing: "
+        f"{_WHY[spec.reason]}, so any active user named by --as-user may run it."
+    )

django_spec_cli/settings.py

@@ -0,0 +1,36 @@
+"""The Django setting this package reads, read at the call rather than at import."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
+
+_COMMAND_OUTPUT = "SPEC_CLI_OUTPUT"
+_COMMAND_OUTPUTS = ("auto", "table", "json")
+
+
+def command_output() -> Literal["auto", "table", "json"]:
+    """``SPEC_CLI_OUTPUT``: the format a ``SpecCommand`` writes its result in.
+
+    ``"auto"`` when the project sets nothing: a table on a terminal and JSON
+    Lines on anything else, so a person reads one and a script parses the
+    other. ``"table"`` or ``"json"`` pins the format project-wide, for a
+    project whose CI should print what an interactive run does. A command's
+    own ``--table`` or ``--json`` still wins over either.
+
+    Read on every call, never at import, as every setting the kernel reads is.
+
+    Raises:
+        ImproperlyConfigured: anything but one of the three strings, matched
+            exactly, so ``"TABLE"`` or ``"jsonl"`` is refused by name rather
+            than quietly read as the default.
+    """
+    value: Any = getattr(settings, _COMMAND_OUTPUT, "auto")
+    if value not in _COMMAND_OUTPUTS:
+        raise ImproperlyConfigured(
+            f"{_COMMAND_OUTPUT} must be one of 'auto', 'table' or 'json'; got {value!r}. It is "
+            "the format a SpecCommand writes its result in."
+        )
+    return value