rtfc 0.1.0__py3-none-any.whl

rtfc/__init__.py

@@ -0,0 +1,5 @@
+"""*Read the freaking changelog* is a tool to manage changelogs and versioning."""
+
+from rtfc._format import Format, RstFormat
+
+__all__ = ("Format", "RstFormat")

rtfc/__main__.py

@@ -0,0 +1,6 @@
+"""Support running the command line interface with ``python -m rtfc``."""
+
+from rtfc._cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

rtfc/_changelog.py

@@ -0,0 +1,46 @@
+"""Assembly of version blocks into the changelog document.
+
+The changelog document must contain an insert marker (a format comment, e.g.
+``.. rtfc-insert`` for rst): released version blocks are inserted right after
+it, newest first.
+"""
+
+from __future__ import annotations
+
+from rtfc._format import Format
+
+__all__ = ("ChangelogError", "insert_version")
+
+
+class ChangelogError(Exception):
+    """Raised when the changelog document cannot be updated."""
+
+
+def _with_trailing_newline(lines: list[str]) -> str:
+    text = "\n".join(lines)
+    return text if text.endswith("\n") else text + "\n"
+
+
+def insert_version(changelog: str, block: str, *, fmt: Format) -> str:
+    """Insert a released version block right after the insert marker.
+
+    Args:
+        changelog: The current changelog text.
+        block: The rendered version block.
+        fmt: The documentation format.
+
+    Raises:
+        ChangelogError: If the insert marker is missing.
+    """
+    lines = changelog.split("\n")
+    marker = fmt.insert_marker()
+    for index, line in enumerate(lines):
+        if line.strip() == marker:
+            rest = lines[index + 1 :]
+            while rest and not rest[0].strip():
+                rest.pop(0)
+            inserted = [*lines[: index + 1], "", *block.split("\n")]
+            if rest:
+                inserted += ["", *rest]
+            return _with_trailing_newline(inserted)
+    raise ChangelogError(f"Changelog is missing the {marker!r} insert marker")

rtfc/_cli.py

@@ -0,0 +1,227 @@
+"""Command line interface.
+
+Commands operate on the project in the current working directory, where the
+configuration is discovered.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime
+import os
+import subprocess
+import sys
+import tomllib
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+from rtfc._changelog import ChangelogError, insert_version
+from rtfc._config import Config, ConfigError, MetadataFieldConfig, SectionConfig, load_config
+from rtfc._entry import Entry, EntryError, load_entries
+from rtfc._format import Format, FormatError, get_format
+from rtfc._render import JinjaRenderer, RenderError
+from rtfc._validation import ValidationContext, ValidationError
+
+__all__ = ("main",)
+
+
+class _Args(argparse.Namespace):
+    command: str
+    # build:
+    version: str = ""
+    dry_run: bool = False
+    # new:
+    section: str | None = None
+    meta: list[tuple[str, Any]] | None = None
+    content: str | None = None
+
+
+def _parse_value(raw: str) -> Any:
+    """Parse ``raw`` as a TOML value, falling back to a plain string."""
+    try:
+        return tomllib.loads(f"value = {raw}")["value"]
+    except tomllib.TOMLDecodeError:
+        return raw
+
+
+def _meta_field(value: str) -> tuple[str, Any]:
+    """Parse a ``KEY=VALUE`` argument into a metadata item, used as an argparse type.
+
+    The value is parsed as TOML, falling back to a plain string.
+    """
+    key, separator, raw = value.partition("=")
+    if not separator:
+        raise argparse.ArgumentTypeError(f"{value!r} is not of the form KEY=VALUE")
+    return key, _parse_value(raw)
+
+
+def _build_parser(config: Config) -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="rtfc", description="Manage changelog entries and build changelogs.")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    subparsers.add_parser("check", help="Validate the configuration and all changelog entries.")
+
+    build = subparsers.add_parser("build", help="Combine the changelog entries into the changelog.")
+    build.add_argument("--version", required=True, help="Release version; entry files are deleted after building.")
+    build.add_argument(
+        "--dry-run", action="store_true", help="Print the version block instead of updating the changelog."
+    )
+
+    new = subparsers.add_parser("new", help="Create a changelog entry.", description="Create a changelog entry.")
+    new.add_argument("-s", "--section", choices=list(config.sections) or None, help="Section id of the entry.")
+    new.add_argument(
+        "--meta", action="append", type=_meta_field, metavar="KEY=VALUE", help="Metadata field; can be repeated."
+    )
+    new.add_argument("--content", help="Entry content; defaults to a placeholder, opened in $EDITOR when set.")
+
+    return parser
+
+
+def _docs_parser() -> argparse.ArgumentParser:
+    """Build the parser from a default configuration, for the sphinx-argparse documentation.
+
+    Running the actual command line interface requires a valid configuration.
+    ``construct()`` bypasses validation, so the documented ``--section``
+    choices are the default sections.
+    """
+    return _build_parser(Config.construct(changelog=Path("changelog.rst"), sections=['depends on configuration.']))
+
+
+def _load(config: Config) -> tuple[Format, list[Entry]]:
+    fmt = get_format(config.format)
+    entries = load_entries(config.directory, sections=config.sections, metadata_validator=config.metadata_validator())
+    return fmt, entries
+
+
+def _check(config: Config) -> int:
+    """Handle the ``check`` command: validate the configuration and all entries."""
+    fmt, entries = _load(config)
+    JinjaRenderer(config=config, fmt=fmt)  # Validates the entry template.
+    print(f"OK: {len(entries)} valid entries")
+    return 0
+
+
+def _build(args: _Args, config: Config) -> int:
+    """Handle the ``build`` command: combine the entries into the changelog."""
+    fmt, entries = _load(config)
+    if not entries:
+        print("No changelog entries found", file=sys.stderr)
+        return 1
+    renderer = JinjaRenderer(config=config, fmt=fmt)
+    header = fmt.version_header(args.version, datetime.date.today())
+    block = renderer.render_block(entries, header=header)
+    if args.dry_run:
+        print(block)
+        return 0
+
+    changelog = config.changelog.read_text(encoding="utf-8")
+    config.changelog.write_text(insert_version(changelog, block, fmt=fmt), encoding="utf-8")
+    for entry in entries:
+        entry.path.unlink()
+    print(f"Updated {config.changelog}")
+    return 0
+
+
+def _prompt_section(sections: dict[str, SectionConfig]) -> str | None:
+    """Prompt for the entry section; an empty answer means no section."""
+    ids = ", ".join(sections)
+    while True:
+        raw = input(f"Section ({ids}) [none]: ").strip()
+        if not raw:
+            return None
+        if raw in sections:
+            return raw
+        print(f"Unknown section {raw!r}")
+
+
+def _prompt_metadata(fields: dict[str, MetadataFieldConfig], metadata: dict[str, Any]) -> None:
+    """Prompt for the metadata fields of the configured schema not already provided.
+
+    An empty answer skips the field, leaving its schema default to apply;
+    invalid values are prompted for again.
+    """
+    for name, field in fields.items():
+        if name in metadata:
+            continue
+        if field.required:
+            hint = "required"
+        elif field.default is not None:
+            hint = f"default: {field.default!r}"
+        else:
+            hint = "optional"
+        while True:
+            raw = input(f"{name} ({field.type}, {hint}): ").strip()
+            if not raw:
+                if field.required:
+                    print(f"{name!r} is required")
+                    continue
+                break
+            # For string fields the raw input is the value; anything else goes
+            # through TOML parsing (so e.g. arrays can be entered as `["a", "b"]`):
+            value = raw if field.type == "string" else _parse_value(raw)
+            try:
+                field._validator().validate(value, ValidationContext(path=(name,)))
+            except ValidationError as exc:
+                print(exc)
+                continue
+            metadata[name] = value
+            break
+
+
+def _new(args: _Args, config: Config) -> int:
+    """Handle the ``new`` command: create a changelog entry.
+
+    When run from a terminal, prompts for the values not provided as command
+    line arguments, before opening ``$EDITOR`` on the created entry.
+    """
+    if args.section is not None and args.section not in config.sections:
+        expected = ", ".join(map(repr, config.sections))
+        print(f"Unknown section {args.section!r} (expected one of: {expected})", file=sys.stderr)
+        return 1
+
+    metadata = dict(args.meta or [])
+    if sys.stdin.isatty():
+        if args.section is None and config.sections:
+            args.section = _prompt_section(config.sections)
+        _prompt_metadata(config.metadata, metadata)
+
+    entry = Entry.create(
+        config.directory,
+        section=args.section,
+        metadata=metadata,
+        content=args.content if args.content is not None else "Describe the change.",
+    )
+    entry.write()
+    print(f"Created {entry.path}")
+
+    editor = os.getenv("EDITOR")
+    if args.content is None and editor:
+        subprocess.run([editor, str(entry.path)], check=False)
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the rtfc command line interface.
+
+    A valid configuration is required for any invocation: it is loaded first,
+    as the parser is built from it (e.g. the ``--section`` choices).
+    """
+    try:
+        config = load_config(Path.cwd())
+    except ConfigError as exc:
+        print(exc, file=sys.stderr)
+        return 1
+    args = _build_parser(config).parse_args(argv, namespace=_Args())
+    try:
+        if args.command == "check":
+            return _check(config)
+        if args.command == "build":
+            return _build(args, config)
+        return _new(args, config)
+    except (ChangelogError, EntryError, FormatError, RenderError) as exc:
+        print(exc, file=sys.stderr)
+        return 1
+    except (EOFError, KeyboardInterrupt):
+        print("Aborted", file=sys.stderr)
+        return 1

rtfc/_config.py

@@ -0,0 +1,298 @@
+"""Configuration discovery and loading.
+
+Configuration is read from the ``[rtfc]`` table of ``rtfc.toml`` or, as a
+fallback, the ``[tool.rtfc]`` table of ``pyproject.toml``. Files are only
+looked up in the invocation directory.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+from typing import Any, cast
+
+from rtfc._validation import (
+    Field,
+    Issue,
+    Schema,
+    ValidationContext,
+    ValidationError,
+    Validator,
+    any_,
+    bool_,
+    dict_of,
+    dir_path,
+    file_path,
+    float_,
+    int_,
+    iso_date,
+    list_of,
+    nullable,
+    one_of,
+    record,
+    str_,
+)
+
+__all__ = ("Config", "ConfigError", "MetadataFieldConfig", "RenderConfig", "SectionConfig", "load_config")
+
+
+class ConfigError(Exception):
+    """Raised when the configuration is missing or invalid."""
+
+
+_DEFAULT_ENTRY_TEMPLATE = "{{ content }}"
+
+_DEFAULT_TEMPLATE = """\
+{{ header }}
+{% for section in sections if section.entries %}
+
+{% if section.label %}
+{{ section_header(section.label) }}
+
+{% endif %}
+{% for entry in section.entries | sort_entries %}
+{{ list_item(render_entry(entry)) }}
+{% endfor %}
+{% endfor %}
+"""
+
+
+class SectionConfig(Schema):
+    """Configuration of a changelog section (an entry category)."""
+
+    id = Field(str_)
+    """Id of the section, as used in the ``section`` field of entries."""
+
+    label = Field(str_)
+    """Heading used for the section in the changelog."""
+
+
+def _derive_label(section_id: str) -> str:
+    """Derive a section label from its id, e.g. ``'breaking_change'`` gives ``'Breaking change'``."""
+    return section_id.replace("_", " ").replace("-", " ").capitalize()
+
+
+class _SectionsValidator(Validator[dict[str, SectionConfig]]):
+    """Validates the ``sections`` list into an id-keyed mapping, in list order."""
+
+    def validate(self, value: object, context: ValidationContext) -> dict[str, SectionConfig]:
+        if isinstance(value, dict) and all(isinstance(section, SectionConfig) for section in value.values()):
+            # Already-normalized mappings (e.g. the field default) are passed through:
+            return cast("dict[str, SectionConfig]", value)
+        if type(value) is not list:
+            raise ValidationError.single(context.path, f"expected list, got {type(value).__name__}")
+        sections: dict[str, SectionConfig] = {}
+        issues: list[Issue] = []
+        for i, item in enumerate(value):
+            item_context = context.at(i)
+            if type(item) is str:
+                section = SectionConfig.construct(id=item, label=_derive_label(item))
+            else:
+                try:
+                    section = SectionConfig.validate(item, item_context)
+                except ValidationError as exc:
+                    issues.extend(exc.issues)
+                    continue
+            if section.id in sections:
+                issues.append(Issue(item_context.path, f"duplicate section id {section.id!r}"))
+            else:
+                sections[section.id] = section
+        if issues:
+            raise ValidationError(issues)
+        return sections
+
+
+_METADATA_TYPES: dict[str, Validator[Any]] = {
+    "string": str_,
+    "integer": int_,
+    "boolean": bool_,
+    "number": float_,
+    "date": iso_date,
+}
+
+
+class MetadataFieldConfig(Schema):
+    """Configuration of an entry metadata field."""
+
+    type = Field(one_of(*_METADATA_TYPES, "array"))
+    """Type of the field value: ``'string'``, ``'integer'``, ``'boolean'``, ``'number'``,
+    ``'date'``, or ``'array'`` (requires ``items``)."""
+
+    items = Field(nullable(one_of(*_METADATA_TYPES)), default=None)
+    """Type of the array items. Required and only allowed when ``type`` is ``'array'``."""
+
+    required = Field(bool_, default=False)
+    """Whether the field must be present on every entry. Mutually exclusive with ``default``."""
+
+    default = Field(any_, default=None)
+    """Value applied when the field is absent. Mutually exclusive with ``required``."""
+
+    def _validator(self) -> Validator[Any]:
+        """The validator for values of this field."""
+        if self.type == "array":
+            assert self.items is not None
+            return list_of(_METADATA_TYPES[self.items])
+        return _METADATA_TYPES[self.type]
+
+    def __post_validate__(self, context: ValidationContext) -> None:
+        if (self.type == "array") != (self.items is not None):
+            message = (
+                "'items' is required for 'array' fields"
+                if self.items is None
+                else "'items' is only allowed for 'array' fields"
+            )
+            raise ValidationError.single(context.path, message)
+        if self.default is not None:
+            if self.required:
+                raise ValidationError.single(context.path, "'required' and 'default' are mutually exclusive")
+            self._validator().validate(self.default, context.at("default"))
+
+
+class RenderConfig(Schema):
+    """Configuration of how entries are combined into the changelog."""
+
+    template = Field(nullable(str_), default=None)
+    """Jinja template rendering a version block. Mutually exclusive with ``template_file``."""
+
+    template_file = Field(nullable(file_path), default=None)
+    """Path to a file containing the version block template, relative to the invocation
+    directory (resolved at validation time)."""
+
+    entry_template = Field(nullable(str_), default=None)
+    """Jinja template rendering a single entry. Mutually exclusive with ``entry_template_file``."""
+
+    entry_template_file = Field(nullable(file_path), default=None)
+    """Path to a file containing the entry template, relative to the configuration file."""
+
+    def resolve_template(self) -> str:
+        """Return the effective version block template text.
+
+        Raises:
+            ConfigError: If the template file cannot be read.
+        """
+        if self.template_file is not None:
+            try:
+                return self.template_file.read_text(encoding="utf-8")
+            except OSError as exc:
+                raise ConfigError(f"Cannot read template file: {exc}") from exc
+        if self.template is not None:
+            return self.template
+        return _DEFAULT_TEMPLATE
+
+    def resolve_entry_template(self) -> str:
+        """Return the effective entry template text.
+
+        Raises:
+            ConfigError: If the template file cannot be read.
+        """
+        if self.entry_template_file is not None:
+            try:
+                return self.entry_template_file.read_text(encoding="utf-8")
+            except OSError as exc:
+                raise ConfigError(f"Cannot read entry template file: {exc}") from exc
+        if self.entry_template is not None:
+            return self.entry_template
+        return _DEFAULT_ENTRY_TEMPLATE
+
+    def __post_validate__(self, context: ValidationContext) -> None:
+        if self.template is not None and self.template_file is not None:
+            raise ValidationError.single(context.path, "'template' and 'template_file' are mutually exclusive")
+        if self.entry_template is not None and self.entry_template_file is not None:
+            raise ValidationError.single(
+                context.path, "'entry_template' and 'entry_template_file' are mutually exclusive"
+            )
+
+
+def _default_sections() -> dict[str, SectionConfig]:
+    return {
+        "change": SectionConfig.construct(id="change", label="Changes"),
+        "feature": SectionConfig.construct(id="feature", label="Features"),
+        "bugfix": SectionConfig.construct(id="bugfix", label="Bug fixes"),
+    }
+
+
+class Config(Schema):
+    """Top-level rtfc configuration."""
+
+    directory = Field(dir_path, default=Path("changelog"))
+    """Directory holding the changelog entry files, relative to the configuration file."""
+
+    changelog = Field(file_path)
+    """Path to the changelog file entries are combined into, relative to the configuration file."""
+
+    format = Field(str_, default="rst")
+    """Name of the documentation format used for entries and the changelog."""
+
+    sections = Field(_SectionsValidator(), default_factory=_default_sections)
+    """Changelog sections by id."""
+
+    metadata = Field(dict_of(MetadataFieldConfig), default_factory=dict)
+    """Schema of the entry metadata fields. When empty, metadata is free-form."""
+
+    render = Field(RenderConfig, default_factory=RenderConfig.construct)
+    """Rendering options."""
+
+    def metadata_validator(self) -> Validator[dict[str, Any]] | None:
+        """Build a validator for entry metadata from the configured schema.
+
+        Returns ``None`` when no metadata schema is configured. Optional fields
+        without a default take ``None`` when absent.
+        """
+        if not self.metadata:
+            return None
+        fields: dict[str, Field[Any]] = {}
+        for name, metadata_field in self.metadata.items():
+            type_validator = metadata_field._validator()
+            if metadata_field.required:
+                fields[name] = Field(type_validator)
+            elif metadata_field.default is not None:
+                fields[name] = Field(type_validator, default=metadata_field.default)
+            else:
+                fields[name] = Field(nullable(type_validator), default=None)
+        return record(fields)
+
+
+def _load_toml(file: Path) -> dict[str, Any]:
+    try:
+        with file.open("rb") as f:
+            return tomllib.load(f)
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"{file.name}: invalid TOML: {exc}") from exc
+
+
+def _validate_config(data: object, context: ValidationContext, file_name: str) -> Config:
+    try:
+        return Config.validate(data, context)
+    except ValidationError as exc:
+        raise ConfigError(f"{file_name}: invalid configuration:\n{exc}") from exc
+
+
+def load_config(directory: Path) -> Config:
+    """Load the rtfc configuration from ``directory``.
+
+    The ``[rtfc]`` table of ``rtfc.toml`` takes priority over the
+    ``[tool.rtfc]`` table of ``pyproject.toml``. Only ``directory`` itself is
+    searched.
+
+    Args:
+        directory: Directory containing the configuration file.
+
+    Raises:
+        ConfigError: If no configuration is found or it is invalid.
+    """
+    rtfc_toml = directory / "rtfc.toml"
+    if rtfc_toml.is_file():
+        data = _load_toml(rtfc_toml)
+        if "rtfc" not in data:
+            raise ConfigError(f"{rtfc_toml.name}: missing the [rtfc] table")
+        context = ValidationContext(path=("rtfc",), current_directory=directory)
+        return _validate_config(data["rtfc"], context, rtfc_toml.name)
+
+    pyproject = directory / "pyproject.toml"
+    if pyproject.is_file():
+        tool = _load_toml(pyproject).get("tool")
+        if isinstance(tool, dict) and "rtfc" in tool:
+            context = ValidationContext(path=("tool", "rtfc"), current_directory=directory)
+            return _validate_config(tool["rtfc"], context, pyproject.name)
+
+    raise ConfigError("No configuration found: define an 'rtfc.toml' file or a '[tool.rtfc]' table in 'pyproject.toml'")