oodocs 1.0.1__py3-none-any.whl

oodocs/__init__.py

@@ -0,0 +1,294 @@
+"""Top-level package for oodocs."""
+
+from importlib.metadata import PackageNotFoundError, version as package_version
+
+from oodocs.core import OODocsError
+from oodocs.compatibility import OUTPUT_FORMATS, OutputFormat
+from oodocs.components.blocks import (
+    Assumption,
+    Axiom,
+    Box,
+    BulletList,
+    Chapter,
+    Claim,
+    CodeBlock,
+    ColumnSpan,
+    Conjecture,
+    CountableBlock,
+    Corollary,
+    Definition,
+    Divider,
+    Equation,
+    Example,
+    MAX_SECTION_LEVEL,
+    MIN_SECTION_LEVEL,
+    Lemma,
+    MultiColumn,
+    NumberedList,
+    PageBreak,
+    Paragraph,
+    Part,
+    Proof,
+    Proposition,
+    Remark,
+    Section,
+    Subsection,
+    Subsubsection,
+    Theorem,
+    VerticalSpace,
+    countable_kind,
+    section_for_level,
+    shift_heading_level,
+    shift_heading_levels,
+)
+from oodocs.components.generated import (
+    CommentsPage,
+    FigureList,
+    ReferencesPage,
+    TableList,
+    TableOfContents,
+    TocLevelStyle,
+)
+from oodocs.components.media import (
+    Figure,
+    ImageData,
+    SubFigure,
+    SubFigureGroup,
+    Table,
+    TableCell,
+    TableCellStyle,
+)
+from oodocs.components.markup import markup
+from oodocs.components.people import Affiliation, Author, AuthorLayout
+from oodocs.components.references import CitationLibrary, CitationSource
+from oodocs.components.positioning import ImageBox, Shape, TextBox
+from oodocs.document import Document
+from oodocs.importers.markdown import (
+    from_markdown,
+    from_markdown_file,
+    parse_markdown,
+    parse_markdown_file,
+)
+from oodocs.importers.notebook import (
+    from_ipynb,
+    from_notebook,
+    parse_ipynb,
+    parse_notebook,
+)
+from oodocs.components.inline import (
+    Comment,
+    Footnote,
+    InlineChip,
+    InlineChipStyle,
+    LineBreak,
+    Math,
+    Text,
+    badge,
+    bold,
+    code,
+    color,
+    cite,
+    comment,
+    footnote,
+    highlight,
+    italic,
+    keyboard,
+    link,
+    line_break,
+    math,
+    prescript,
+    reference,
+    status,
+    strike,
+    strikethrough,
+    styled,
+    subscript,
+    superscript,
+    tag,
+)
+from oodocs.settings import (
+    BlockOptions,
+    BoxStyle,
+    CaptionOptions,
+    CitationOptions,
+    DocumentSettings,
+    GeneratedPageOptions,
+    HeadingNumbering,
+    ListStyle,
+    PageNumberOptions,
+    PageMargins,
+    PageSize,
+    ParagraphStyle,
+    TableStyle,
+    TextStyle,
+    TitleMatterOptions,
+    TypographyOptions,
+    Theme,
+)
+from oodocs.validation import DocumentValidationError, ValidationIssue, ValidationResult
+from oodocs.workflows import (
+    RenderedOutputs,
+    build_python_document,
+    convert_source,
+    load_document,
+    load_python_document,
+    render_document,
+    validate_source,
+)
+
+
+_FALLBACK_VERSION = "1.0.1"
+
+
+def _resolve_version() -> str:
+    try:
+        return package_version("oodocs")
+    except PackageNotFoundError:
+        try:
+            from setuptools_scm import get_version
+        except ImportError:
+            return _FALLBACK_VERSION
+        return get_version(
+            root="../..",
+            relative_to=__file__,
+            fallback_version=_FALLBACK_VERSION,
+            tag_regex=r"^v(?P<version>\d+\.\d+\.\d+)$",
+        )
+
+
+__version__ = _resolve_version()
+
+__all__ = [
+    "Affiliation",
+    "Assumption",
+    "Author",
+    "AuthorLayout",
+    "Axiom",
+    "BlockOptions",
+    "Box",
+    "BoxStyle",
+    "BulletList",
+    "CaptionOptions",
+    "CitationOptions",
+    "CitationLibrary",
+    "CitationSource",
+    "Chapter",
+    "Claim",
+    "Comment",
+    "CommentsPage",
+    "CodeBlock",
+    "ColumnSpan",
+    "Conjecture",
+    "CountableBlock",
+    "Corollary",
+    "Definition",
+    "Document",
+    "DocumentSettings",
+    "OODocsError",
+    "Divider",
+    "Equation",
+    "Example",
+    "Figure",
+    "FigureList",
+    "Footnote",
+    "GeneratedPageOptions",
+    "HeadingNumbering",
+    "ImageBox",
+    "ImageData",
+    "InlineChip",
+    "InlineChipStyle",
+    "LineBreak",
+    "ListStyle",
+    "Lemma",
+    "Math",
+    "MAX_SECTION_LEVEL",
+    "MIN_SECTION_LEVEL",
+    "MultiColumn",
+    "NumberedList",
+    "OUTPUT_FORMATS",
+    "OutputFormat",
+    "PageNumberOptions",
+    "PageMargins",
+    "PageSize",
+    "PageBreak",
+    "Paragraph",
+    "Part",
+    "Proof",
+    "Proposition",
+    "ParagraphStyle",
+    "ReferencesPage",
+    "RenderedOutputs",
+    "Remark",
+    "Section",
+    "Shape",
+    "SubFigure",
+    "SubFigureGroup",
+    "Subsection",
+    "Subsubsection",
+    "Table",
+    "TableCell",
+    "TableCellStyle",
+    "TableStyle",
+    "TableOfContents",
+    "TableList",
+    "Text",
+    "TextBox",
+    "TextStyle",
+    "Theorem",
+    "TitleMatterOptions",
+    "Theme",
+    "TocLevelStyle",
+    "TypographyOptions",
+    "DocumentValidationError",
+    "ValidationIssue",
+    "ValidationResult",
+    "VerticalSpace",
+    "__version__",
+    "badge",
+    "bold",
+    "build_python_document",
+    "code",
+    "color",
+    "cite",
+    "comment",
+    "countable_kind",
+    "convert_source",
+    "footnote",
+    "from_ipynb",
+    "from_markdown",
+    "from_markdown_file",
+    "from_notebook",
+    "highlight",
+    "italic",
+    "keyboard",
+    "link",
+    "line_break",
+    "load_document",
+    "load_python_document",
+    "math",
+    "prescript",
+    "reference",
+    "render_document",
+    "status",
+    "strike",
+    "strikethrough",
+    "markup",
+    "styled",
+    "parse_ipynb",
+    "parse_markdown",
+    "parse_markdown_file",
+    "parse_notebook",
+    "section_for_level",
+    "shift_heading_level",
+    "shift_heading_levels",
+    "subscript",
+    "superscript",
+    "tag",
+    "validate_source",
+]
+
+for _module_name in ("components", "core", "document", "layout", "settings"):
+    globals().pop(_module_name, None)
+
+del _resolve_version
+del _module_name

oodocs/__main__.py

@@ -0,0 +1,9 @@
+"""Run the OODocs command line interface with ``python -m oodocs``."""
+
+from __future__ import annotations
+
+from oodocs.cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

oodocs/cli.py

@@ -0,0 +1,191 @@
+"""Command line interface for OODocs workflows."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+import sys
+from typing import Sequence
+
+from oodocs.compatibility import normalize_output_formats
+from oodocs.validation import DocumentValidationError
+from oodocs.workflows import build_python_document, convert_source, validate_source
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the OODocs CLI."""
+
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except DocumentValidationError as exc:
+        print(exc, file=sys.stderr)
+        return 1
+    except (AttributeError, FileNotFoundError, ImportError, TypeError, ValueError) as exc:
+        print(f"oodocs: {exc}", file=sys.stderr)
+        return 2
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="oodocs",
+        description="Build, convert, and validate OODocs documents.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    build = subparsers.add_parser(
+        "build",
+        help="Build a Python-authored OODocs document.",
+    )
+    build.add_argument("source", help="Python file exposing a Document or build function.")
+    _add_render_options(build, default_out=".")
+    build.add_argument(
+        "--factory",
+        help="Document variable or zero-argument function to use from the Python source.",
+    )
+    build.add_argument(
+        "--no-chdir",
+        action="store_true",
+        help="Do not run the Python source with its directory as the working directory.",
+    )
+    build.set_defaults(func=_run_build)
+
+    convert = subparsers.add_parser(
+        "convert",
+        help="Convert Markdown or notebook source to rendered outputs.",
+    )
+    convert.add_argument("source", help="Markdown (.md) or notebook (.ipynb) file.")
+    _add_render_options(convert, default_out=None)
+    convert.add_argument("--title", help="Override the imported document title.")
+    convert.set_defaults(func=_run_convert)
+
+    validate = subparsers.add_parser(
+        "validate",
+        help="Validate a Python, Markdown, or notebook source document.",
+    )
+    validate.add_argument("source", help="Source file to validate.")
+    validate.add_argument(
+        "--to",
+        default="docx,pdf,html",
+        help="Comma-separated output formats to validate for. Defaults to docx,pdf,html.",
+    )
+    validate.add_argument(
+        "--type",
+        choices=("python", "py", "markdown", "md", "notebook", "ipynb"),
+        help="Override source type inference.",
+    )
+    validate.add_argument("--title", help="Override imported Markdown/notebook title.")
+    validate.add_argument(
+        "--factory",
+        help="Document variable or zero-argument function for Python sources.",
+    )
+    validate.add_argument(
+        "--strict",
+        action="store_true",
+        help="Return a non-zero exit code when warnings are present.",
+    )
+    validate.add_argument(
+        "--no-chdir",
+        action="store_true",
+        help="Do not run Python sources with their directory as the working directory.",
+    )
+    validate.set_defaults(func=_run_validate)
+
+    return parser
+
+
+def _add_render_options(
+    parser: argparse.ArgumentParser,
+    *,
+    default_out: str | None,
+) -> None:
+    parser.add_argument(
+        "--out",
+        default=default_out,
+        help=(
+            "Output directory. Defaults to the current directory for build and "
+            "the source directory for convert."
+        ),
+    )
+    parser.add_argument(
+        "--to",
+        default="docx,pdf,html",
+        help="Comma-separated output formats. Defaults to docx,pdf,html.",
+    )
+    parser.add_argument("--stem", help="Output filename stem.")
+    parser.add_argument(
+        "--no-validate",
+        action="store_true",
+        help="Skip validation before rendering.",
+    )
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Print slow major build steps.",
+    )
+
+
+def _run_build(args: argparse.Namespace) -> int:
+    formats = _parse_formats(args.to)
+    outputs = build_python_document(
+        args.source,
+        args.out,
+        formats=formats,
+        stem=args.stem,
+        factory=args.factory,
+        validate=not args.no_validate,
+        chdir=not args.no_chdir,
+        verbose=args.verbose,
+    )
+    _print_outputs(outputs.outputs)
+    return 0
+
+
+def _run_convert(args: argparse.Namespace) -> int:
+    formats = _parse_formats(args.to)
+    outputs = convert_source(
+        args.source,
+        args.out,
+        formats=formats,
+        stem=args.stem,
+        title=args.title,
+        validate=not args.no_validate,
+        verbose=args.verbose,
+    )
+    _print_outputs(outputs.outputs)
+    return 0
+
+
+def _run_validate(args: argparse.Namespace) -> int:
+    formats = _parse_formats(args.to)
+    result = validate_source(
+        args.source,
+        source_type=args.type,
+        title=args.title,
+        factory=args.factory,
+        formats=formats,
+        chdir=not args.no_chdir,
+    )
+    print(result.format_table(formats=formats))
+    if result.errors_for(formats):
+        return 1
+    if args.strict and result.warnings_for(formats):
+        return 1
+    return 0
+
+
+def _parse_formats(value: str) -> tuple[str, ...]:
+    pieces = tuple(piece.strip() for piece in value.split(",") if piece.strip())
+    if not pieces:
+        raise ValueError("--to must include at least one output format")
+    return normalize_output_formats(pieces)
+
+
+def _print_outputs(outputs: dict[object, Path]) -> None:
+    for output_format, path in outputs.items():
+        print(f"Wrote {output_format}: {path}")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

oodocs/compatibility.py

@@ -0,0 +1,102 @@
+"""Shared output-format compatibility helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable, Literal
+
+
+OutputFormat = Literal["docx", "pdf", "html"]
+OUTPUT_FORMATS: tuple[OutputFormat, ...] = ("docx", "pdf", "html")
+OUTPUT_FORMAT_LABELS: dict[OutputFormat, str] = {
+    "docx": "Word",
+    "pdf": "PDF",
+    "html": "HTML",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class CompatibilityNote:
+    """Renderer compatibility note surfaced by document validation."""
+
+    code: str
+    message: str
+    formats: tuple[OutputFormat, ...]
+
+
+COMPATIBILITY_NOTES: dict[str, CompatibilityNote] = {
+    "html-toc-page-numbers": CompatibilityNote(
+        code="html-toc-page-numbers",
+        message=(
+            "HTML output does not have stable rendered page numbers, "
+            "so the TOC is link-only there."
+        ),
+        formats=("html",),
+    ),
+}
+
+
+def compatibility_note(code: str) -> CompatibilityNote:
+    """Return a named compatibility note."""
+
+    try:
+        return COMPATIBILITY_NOTES[code]
+    except KeyError as exc:
+        raise KeyError(f"Unknown compatibility note: {code}") from exc
+
+
+def normalize_output_format(value: str) -> OutputFormat:
+    """Normalize a renderer/output format name."""
+
+    normalized = value.lower().strip().removeprefix(".")
+    if normalized == "htm":
+        normalized = "html"
+    if normalized not in OUTPUT_FORMATS:
+        raise ValueError(
+            "Unsupported document output format. Use one of: .docx, .pdf, .html "
+            "(or docx, pdf, html in save_all)."
+        )
+    return normalized  # type: ignore[return-value]
+
+
+def normalize_output_formats(
+    values: Iterable[str] | None = None,
+) -> tuple[OutputFormat, ...]:
+    """Normalize a sequence of output formats while preserving order."""
+
+    if values is None:
+        return OUTPUT_FORMATS
+
+    normalized: list[OutputFormat] = []
+    seen: set[OutputFormat] = set()
+    for value in values:
+        output_format = normalize_output_format(value)
+        if output_format in seen:
+            continue
+        normalized.append(output_format)
+        seen.add(output_format)
+    return tuple(normalized)
+
+
+def format_output_formats(formats: Iterable[OutputFormat]) -> str:
+    """Return a compact display label for output formats."""
+
+    normalized = normalize_output_formats(formats)
+    if not normalized:
+        return "None"
+    if set(normalized) == set(OUTPUT_FORMATS):
+        return "All"
+    return "/".join(OUTPUT_FORMAT_LABELS[output_format] for output_format in normalized)
+
+
+__all__ = [
+    "COMPATIBILITY_NOTES",
+    "OUTPUT_FORMATS",
+    "OUTPUT_FORMAT_LABELS",
+    "CompatibilityNote",
+    "OutputFormat",
+    "compatibility_note",
+    "format_output_formats",
+    "normalize_output_format",
+    "normalize_output_formats",
+]

oodocs/components/__init__.py

@@ -0,0 +1,106 @@
+"""Grouped component namespaces for more granular imports."""
+
+from __future__ import annotations
+
+from importlib import import_module
+
+
+_EXPORTS = {
+    "Affiliation": "oodocs.components.people",
+    "Assumption": "oodocs.components.blocks",
+    "Author": "oodocs.components.people",
+    "AuthorLayout": "oodocs.components.people",
+    "Axiom": "oodocs.components.blocks",
+    "Bold": "oodocs.components.inline",
+    "Box": "oodocs.components.blocks",
+    "BulletList": "oodocs.components.blocks",
+    "Chapter": "oodocs.components.blocks",
+    "Citation": "oodocs.components.inline",
+    "CitationLibrary": "oodocs.components.references",
+    "CitationSource": "oodocs.components.references",
+    "Claim": "oodocs.components.blocks",
+    "CodeBlock": "oodocs.components.blocks",
+    "ColumnSpan": "oodocs.components.blocks",
+    "Comment": "oodocs.components.inline",
+    "Conjecture": "oodocs.components.blocks",
+    "CommentsPage": "oodocs.components.generated",
+    "Corollary": "oodocs.components.blocks",
+    "CountableBlock": "oodocs.components.blocks",
+    "Definition": "oodocs.components.blocks",
+    "Divider": "oodocs.components.blocks",
+    "Equation": "oodocs.components.blocks",
+    "Example": "oodocs.components.blocks",
+    "Figure": "oodocs.components.media",
+    "FigureList": "oodocs.components.generated",
+    "Footnote": "oodocs.components.inline",
+    "FootnotesPage": "oodocs.components.generated",
+    "Highlight": "oodocs.components.inline",
+    "Hyperlink": "oodocs.components.inline",
+    "ImageBox": "oodocs.components.positioning",
+    "ImageData": "oodocs.components.media",
+    "InlineChip": "oodocs.components.inline",
+    "InlineChipStyle": "oodocs.components.inline",
+    "Italic": "oodocs.components.inline",
+    "Lemma": "oodocs.components.blocks",
+    "LineBreak": "oodocs.components.inline",
+    "Math": "oodocs.components.inline",
+    "Monospace": "oodocs.components.inline",
+    "MultiColumn": "oodocs.components.blocks",
+    "NumberedList": "oodocs.components.blocks",
+    "Paragraph": "oodocs.components.blocks",
+    "Part": "oodocs.components.blocks",
+    "Proposition": "oodocs.components.blocks",
+    "Proof": "oodocs.components.blocks",
+    "ReferencesPage": "oodocs.components.generated",
+    "Remark": "oodocs.components.blocks",
+    "Section": "oodocs.components.blocks",
+    "Shape": "oodocs.components.positioning",
+    "SubFigure": "oodocs.components.media",
+    "SubFigureGroup": "oodocs.components.media",
+    "Subsection": "oodocs.components.blocks",
+    "Subsubsection": "oodocs.components.blocks",
+    "Table": "oodocs.components.media",
+    "TableCell": "oodocs.components.media",
+    "TableCellStyle": "oodocs.components.media",
+    "TableList": "oodocs.components.generated",
+    "TableOfContents": "oodocs.components.generated",
+    "Text": "oodocs.components.inline",
+    "TextBox": "oodocs.components.positioning",
+    "Theorem": "oodocs.components.blocks",
+    "VerticalSpace": "oodocs.components.blocks",
+    "badge": "oodocs.components.inline",
+    "bold": "oodocs.components.inline",
+    "code": "oodocs.components.inline",
+    "color": "oodocs.components.inline",
+    "cite": "oodocs.components.inline",
+    "comment": "oodocs.components.inline",
+    "countable_kind": "oodocs.components.blocks",
+    "footnote": "oodocs.components.inline",
+    "highlight": "oodocs.components.inline",
+    "italic": "oodocs.components.inline",
+    "keyboard": "oodocs.components.inline",
+    "link": "oodocs.components.inline",
+    "line_break": "oodocs.components.inline",
+    "math": "oodocs.components.inline",
+    "markup": "oodocs.components.markup",
+    "prescript": "oodocs.components.inline",
+    "reference": "oodocs.components.inline",
+    "status": "oodocs.components.inline",
+    "strike": "oodocs.components.inline",
+    "strikethrough": "oodocs.components.inline",
+    "styled": "oodocs.components.inline",
+    "subscript": "oodocs.components.inline",
+    "superscript": "oodocs.components.inline",
+    "tag": "oodocs.components.inline",
+}
+
+__all__ = list(_EXPORTS)
+
+
+def __getattr__(name: str) -> object:
+    module_name = _EXPORTS.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    value = getattr(import_module(module_name), name)
+    globals()[name] = value
+    return value