Project¶

@classmethod
def load(cls, path: Path | str | None = None, *, root: Path | str | None = None) -> Project:
    """Load the project with the configuration given in *path*.

    Without *path*, ``opm.toml`` in the current directory is read if it
    exists; if not, the project has default settings. *root* defaults to
    the config file's directory.

    Raises:
        FileNotFoundError: *path* was given but is not a file.
    """
    if path is not None and not Path(path).is_file():
        raise FileNotFoundError(f'Config file not found: {path}')
    config_path = Path(path) if path is not None else Path(CONFIG_FILENAME)
    config = load_project_config(config_path)
    return cls(config, root=root if root is not None else config_path.absolute().parent)

def with_config(self, **changes: Any) -> Project:
    """A new project with some [`ProjectConfig`][opm.config.ProjectConfig] fields replaced.

    For example, ``project.with_config(document_css=Path('print.css'))``.
    """
    return Project(replace(self.config, **changes), root=self.root)

def compile(self, mode: str | None = None, odd: Path | str | None = None) -> ResolvedTransform:
    """Compile the ODD for output *mode*, or find it in the cache.

    The ODD is *odd*, else ``[transform.<mode>] odd``, else
    ``[transform] odd``, else the packaged ``teipublisher.odd``.

    Args:
        mode: An output mode such as ``web``, ``markdown``, ``docx``,
            ``typst`` or ``json`` (see [`opm.output_modes`][opm.output_modes]).
            Defaults to ``web``.
        odd: The ODD to use instead of the configured one.

    Raises:
        ValueError: *mode* is not an output mode.
    """
    name = output_mode(mode).name
    chosen = Path(odd) if odd is not None else self.config.odd_for_type(name)
    return self._resolve(name, chosen)

def module(self, mode: str | None = None, odd: Path | str | None = None) -> ModuleType:
    """The loaded transform module for *mode*; see [`compile`][opm.project.Project.compile]."""
    return self._load(self.compile(mode, odd).module_path)

def transform(
    self,
    source: Source,
    *,
    mode: str | None = None,
    odd: Path | str | None = None,
    xpath: str | None = None,
    parameters: dict[str, str] | None = None,
    xpath_extensions: Sequence[str] | None = None,
    webcomponents: bool | None = None,
    template: Path | None = None,
) -> str | bytes:
    """Transform *source*, as ``opm transform`` does.

    Args:
        source: An XML file, or a tree or element parsed with lxml. When
            an element comes from a parsed file, ``doc()`` resolves
            against that file and ``$parameters?input_path`` names it.
        mode: The output mode (``web`` by default); see [`compile`][opm.project.Project.compile].
        odd: The ODD to use instead of the configured one.
        xpath: XPath 3.1 expression selecting the element to transform.
            Unprefixed names use the document's default namespace.
        parameters: XPath ``$parameters``, over ``[transform.parameters]``.
        xpath_extensions: Extension modules to use instead of the
            configured ones.
        webcomponents: Enable web-component mode. ``None`` uses the config.
        template: The document template to use instead of the configured one.

    Returns:
        ``str`` for text output (HTML, Markdown, Typst, JSON) and ``bytes``
        for DOCX and EPUB.
    """
    return transform_with_config(
        self.module(mode, odd),
        _source_root(source),
        _source_path(source),
        self.config,
        xpath=xpath,
        parameters=parameters,
        xpath_extensions=xpath_extensions,
        webcomponents=webcomponents,
        template=template,
        documents=self._documents(),
    )

def chunk_output_dir(self, output_dir: Path | str | None = None) -> Path:
    """Where [`chunk`][opm.project.Project.chunk] writes: *output_dir*, else ``[chunking] output_dir``, below [`root`][opm.project.Project.root]."""
    return self.root / (output_dir if output_dir is not None else self._chunking().output_dir)

def chunk_modules(self, odd: Path | str | None = None) -> tuple[ResolvedTransform, ...]:
    """Compile the modules a chunk run uses: the main one, then one per fragment ODD.

    The main ODD is *odd*, else ``[chunking] odd``, else the packaged one.
    Fragments without an ODD of their own use the main module. For a
    ``[[chunking]]`` array this is the first run's set.

    Raises:
        ValueError: The config has no ``[chunking]`` section.
    """
    return self._run_modules(self._chunking(), odd)

def chunk(
    self,
    source: Path | str,
    *,
    format: str = 'html',
    output_dir: Path | str | None = None,
    template: Path | None = None,
    depth: int | None = None,
    odd: Path | str | None = None,
    doc_path: str | None = None,
    webcomponents: bool | None = None,
    xpath_extensions: Sequence[str] | None = None,
    overwrite: bool = False,
    on_document: Callable[[int, Path], None] | None = None,
    on_progress: Callable[[int, int], None] | None = None,
) -> ChunkRun:
    """Split *source* into pages, as ``opm chunk`` does.

    *source* is one XML file or a directory of them. For a directory,
    each document goes to a subdirectory named after it, and an HTML run
    also writes ``index.html`` listing the documents. ``pb-view`` output
    puts every document's data under ``<doc_path>/<name>.xml/`` instead.

    The arguments override the ``[chunking]`` settings of the same name.

    Args:
        source: An XML file, or a directory of XML files (not searched
            recursively).
        format: ``html`` (pages rendered with the chunk template),
            ``json`` (one JSON file per chunk, for static site
            generators) or ``pb-view`` (data for the ``pb-view`` web
            component in static mode).
        output_dir: Output directory, relative to [`root`][opm.project.Project.root].
        template: Page template for HTML output.
        depth: Maximum section depth to split at.
        odd: The ODD to use instead of ``[chunking] odd``.
        doc_path: For ``pb-view``: the ``pb-document`` path the data is
            written under.
        webcomponents: Enable web-component mode for HTML output. JSON
            and ``pb-view`` output always use it.
        xpath_extensions: Extension modules to use instead of the
            configured ones.
        overwrite: Replace the output directory if it exists. Without
            it, an existing directory raises `FileExistsError`.
        on_document: Called with the position and path of each document
            before it is chunked.
        on_progress: Called with ``(done, total)`` chunks as each
            document is processed.

    Raises:
        ValueError: The config has no ``[chunking]`` section, *format* is
            unknown, or a directory contains no XML files.
        FileExistsError: The output directory exists and *overwrite*
            does not allow replacing it.
    """
    if format not in CHUNK_FORMATS:
        raise ValueError(f'format must be "html", "json" or "pb-view", got {format!r}')
    source = Path(source)
    files = chunk_input_files(source)
    by_directory = source.is_dir()
    if by_directory and not files:
        raise ValueError(f'no XML files found in directory {source}.')

    overrides: dict[str, Any] = {}
    if output_dir is not None:
        overrides['output_dir'] = str(output_dir)
    if template is not None:
        overrides['template'] = Path(template)
    if depth is not None:
        overrides['depth'] = depth
    if odd is not None:
        overrides['odd'] = Path(odd)

    # One or several runs ([[chunking]]), each with its modules compiled
    # and the call's overrides applied. They share the output directory.
    runs: list[ChunkingConfig] = []
    all_modules: list[ResolvedTransform] = []
    for run in self._chunking_runs():
        modules = self._run_modules(run, odd)
        all_modules.extend(modules)
        changes: dict[str, Any] = {'module': modules[0].module_path, **overrides}
        if run.fragments:
            compiled = iter(modules[1:])
            changes['fragments'] = [
                replace(fragment, module=next(compiled).module_path if fragment.odd else None)
                for fragment in run.fragments
            ]
        runs.append(replace(run, **changes))
    chunking = runs[0]

    out_dir = self.chunk_output_dir(chunking.output_dir)
    _clear_output_dir(out_dir, overwrite)

    enabled = (
        True if format in ('json', 'pb-view')
        else webcomponents if webcomponents is not None
        else bool(self.config.webcomponents_enabled)
    )
    extensions = tuple(xpath_extensions) if xpath_extensions else None
    base_doc_path = doc_path or chunking.doc_path
    # What each document's directory is called: its file name, or the
    # first run's document_name. pb-view data stays addressed by file.
    doc_names = document_names(
        files,
        None if format == 'pb-view' else chunking.document_name,
        self.config,
        extensions=extensions,
    )
    # Built once and shared: templates test links against it.
    names = frozenset(doc_names.values())

    for position, xml_file in enumerate(files):
        if on_document is not None:
            on_document(position, xml_file)
        if by_directory and format == 'pb-view':
            document_doc_path = (
                f'{base_doc_path.rstrip("/")}/{xml_file.name}' if base_doc_path
                else xml_file.name
            )
        else:
            document_doc_path = base_doc_path

        # Each run of this document is handed the anchors of the runs
        # before it, so links between their pages resolve.
        anchors: dict[str, str] = {}
        written = 0
        for index, run in enumerate(runs):
            progress = on_progress
            if on_progress is not None and written:
                # One count per document across its runs.
                def progress(done: int, total: int, _base: int = written) -> None:
                    on_progress(_base + done, _base + total)
            anchors = chunk_document(
                module_path=run.module,
                xml_path=xml_file,
                config=_document_config(run, xml_file, format, doc_names[xml_file]),
                project_root=self.root,
                template_path=run.template,
                on_progress=progress,
                project_config=self.config,
                webcomponents=enabled,
                xpath_extensions=extensions,
                output_format=format,
                doc_path=document_doc_path,
                documents=names,
                anchors=anchors,
                merge_manifest=index > 0,
            ) or {}  # a wrapped or stubbed chunk_document may still return None
            written = len(set(anchors.values()))

    # Every HTML run leaves one subdirectory per document, which a web
    # server would otherwise show as a bare listing.
    index_file: Path | None = None
    if format == 'html':
        index_file = build_index(
            out_dir,
            template_path=chunking.index_template,
            title=chunking.index_title or source.name,
            module_path=chunking.module,
            project_config=self.config,
            project_root=self.root,
            chunking_config=chunking,
            webcomponents=enabled,
        )
    return ChunkRun(
        output_dir=out_dir,
        documents=tuple(files),
        format=format,
        modules=tuple(all_modules),
        index_file=index_file,
    )

def index(
    self,
    sources: Path | str | Iterable[Path | str],
    *,
    odd: Path | str | None = None,
    options: IndexOptions | None = None,
) -> list[dict]:
    """Search-index records for *sources*, as ``opm index`` makes them.

    Args:
        sources: An XML file, a directory (searched recursively), or a
            list of either.
        odd: The ODD to use instead of ``[transform.json] odd``.
        options: Rollup settings. ``None`` uses ``[index]`` from the config.

    Write the result with [`opm.indexing.write_jsonl`][opm.indexing.write_jsonl].
    """
    from opm.indexing import index_document

    base_css = resolve_base_css(self.config.document_css, self.root)
    records: list[dict] = []
    for path in _corpus_files(sources):
        records.extend(
            index_document(
                path,
                cfg=self.config,
                odd=Path(odd) if odd is not None else None,
                project_root=self.root,
                options=options,
                base_css=base_css,
            ),
        )
    return records

def coverage(
    self,
    sources: Path | str | Iterable[Path | str],
    *,
    mode: str = 'json',
    odd: Path | str | None = None,
    parameters: dict[str, str] | None = None,
) -> CoverageReport:
    """Measure the ODD against *sources*, as ``opm odd coverage`` does.

    Args:
        sources: An XML file, a directory (searched recursively), or a
            list of either.
        mode: ``json`` for the web channel, or ``json-<channel>`` for
            another one (``json-print``, ``json-typst``, …).
        odd: The ODD to use instead of ``[transform.json] odd``.
        parameters: XPath ``$parameters``, over ``[transform.parameters]``.
    """
    from opm.coverage import analyze

    name = output_mode(mode).name
    chosen = Path(odd) if odd is not None else self.config.odd_for_type(name)
    return analyze(
        _corpus_files(sources),
        cfg=self.config,
        odd=chosen,
        output_mode=name,
        parameters=parameters,
        base_css=resolve_base_css(self.config.document_css, self.root),
    )