`asciidoctrine.loader`

File and resource loading abstractions for AsciiDoctrine.

This module decouples document parsing and preprocessing from physical disk I/O, enabling hermetic in-memory execution, browser-based Pyodide sandboxing, and customizable resource providers.

Module Contents

Classes

`FileProvider`	Abstract resource loader interface for resolving and reading document sources.
`FsLoader`	Concrete filesystem provider backed by the host operating system.
`MemoryLoader`	In-memory virtual filesystem loader backed by a dictionary.

API

class asciidoctrine.loader.FileProvider

Bases: abc.ABC

Abstract resource loader interface for resolving and reading document sources.

FileProvider provides a standardized interface for file reading, path resolution, and document discovery across different storage media (local filesystem, in-memory virtual dictionaries, network streams, etc.).

abstractmethod read_text(path: Union[str, pathlib.Path]) → str

Reads and returns the complete text content of a target document.

path: Canonical or relative path identifier for the file to read.

Must raise FileNotFoundError or PermissionError if the file cannot be accessed.

abstractmethod exists(path: Union[str, pathlib.Path]) → bool

Checks whether the specified path exists in the provider.

path: The file or directory path identifier to check.

abstractmethod is_file(path: Union[str, pathlib.Path]) → bool

Checks whether the specified path points to a readable file.

path: The path identifier to check.

abstractmethod resolve_path(path: Union[str, pathlib.Path], base_dir: Optional[Union[str, pathlib.Path]] = None) → str

Resolves a path relative to a base directory or workspace root.

path: The relative or absolute path to resolve.
base_dir: Optional reference directory for relative resolution. Defaults to the provider’s root.

abstractmethod find_files(pattern: str = '*.adoc', base_dir: Optional[Union[str, pathlib.Path]] = None) → List[str]

Discovers all files matching a glob pattern within the target directory.

pattern: Glob pattern to match against (e.g. "*.adoc").
base_dir: Optional sub-directory to start discovery from.

class asciidoctrine.loader.FsLoader(base_dir: Optional[Union[str, pathlib.Path]] = None, safe_mode: Union[bool, int] = True)

Bases: asciidoctrine.loader.FileProvider

Concrete filesystem provider backed by the host operating system.

FsLoader reads files from the local disk and enforces path traversal security

constraints when safe_mode is enabled.

Example:

from asciidoctrine.loader import FsLoader

loader = FsLoader(base_dir="/docs", safe_mode=True)
content = loader.read_text("chapter1/intro.adoc")

Initialization

Initializes the filesystem loader.

base_dir: Root directory against which relative paths are resolved. Defaults to current working directory.
safe_mode: If True (or integer >= 1), restricts file access to paths strictly contained inside base_dir.

_validate_safe_path(target_abs_path: str) → None: Enforces that target_abs_path resides within base_dir under safe_mode.

read_text(path: Union[str, pathlib.Path]) → str

exists(path: Union[str, pathlib.Path]) → bool

is_file(path: Union[str, pathlib.Path]) → bool

resolve_path(path: Union[str, pathlib.Path], base_dir: Optional[Union[str, pathlib.Path]] = None) → str

find_files(pattern: str = '*.adoc', base_dir: Optional[Union[str, pathlib.Path]] = None) → List[str]

class asciidoctrine.loader.MemoryLoader(files: Optional[Dict[str, str]] = None, base_dir: str = '/workspace', safe_mode: Union[bool, int] = True)

Bases: asciidoctrine.loader.FileProvider

In-memory virtual filesystem loader backed by a dictionary.

MemoryLoader stores file contents in a Python dictionary mapping POSIX-style relative paths to file content strings. It enables 100% hermetic unit testing, instant AST fixture assembly, and browser-native execution without touching the disk.

Example:

from asciidoctrine.loader import MemoryLoader

files = {
    "main.adoc": "= Title\n\ninclude::chapter1.adoc[]",
    "chapter1.adoc": "== Chapter 1\n\nContent text."
}
loader = MemoryLoader(files, base_dir="/workspace")
content = loader.read_text("main.adoc")

Initialization

Initializes the in-memory loader.

files: Dictionary mapping relative path strings to source text strings.
base_dir: Canonical root prefix for virtual file resolution (e.g. "/workspace").
safe_mode: If True, restricts virtual file resolution to within base_dir.

static _normalize_posix_path(path: Union[str, pathlib.Path]) → str

put(path: Union[str, pathlib.Path], content: str) → None

Adds or updates a virtual file in the in-memory filesystem.

path: Relative or absolute path for the file.
content: String content of the document.

resolve_path(path: Union[str, pathlib.Path], base_dir: Optional[Union[str, pathlib.Path]] = None) → str

read_text(path: Union[str, pathlib.Path]) → str

exists(path: Union[str, pathlib.Path]) → bool

is_file(path: Union[str, pathlib.Path]) → bool

find_files(pattern: str = '*.adoc', base_dir: Optional[Union[str, pathlib.Path]] = None) → List[str]

asciidoctrine.loader

Module Contents

Classes

API

`asciidoctrine.loader`