settings

Classes:

• ArxProject –
• ArxProjectError –
• Arxpm –
• ArxpmDependencyGroup –
• Author –
• Build –
• DependencyGroupInclude –
• Environment –
• Project –
• Tests –
• Toolchain –

Functions:

• dump_settings –
• find_config_file –
• load_settings –
• load_settings_from_text –
• resolve_source_root –
• write_settings –

ArxProject dataclass

ArxProject(
    project: Project,
    environment: Environment | None = None,
    build: Build | None = None,
    toolchain: Toolchain | None = None,
    dependency_groups: dict[
        str, tuple[DependencyGroupEntry, ...]
    ] = dict(),
    arxpm: Arxpm | None = None,
    tests: Tests | None = None,
    source_path: Path | None = None,
)

ArxProjectError

Bases: Exception

Arxpm dataclass

Arxpm(
    dependencies: ArxpmDependencyGroup | None = None,
    dependencies_dev: ArxpmDependencyGroup | None = None,
    extras: dict[str, Any] = dict(),
)

ArxpmDependencyGroup dataclass

ArxpmDependencyGroup(dependencies: tuple[str, ...] = ())

Author dataclass

Author(name: str, email: str | None = None)

Build dataclass

Build(
    src_dir: str | None = None,
    package: str | None = None,
    out_dir: str | None = None,
    mode: str | None = None,
)

DependencyGroupInclude dataclass

DependencyGroupInclude(include_group: str)

Environment dataclass

Environment(
    kind: str | None = None,
    name: str | None = None,
    path: str | None = None,
)

Project dataclass

Project(
    name: str,
    version: str,
    edition: str | None = None,
    description: str | None = None,
    license: str | None = None,
    authors: tuple[Author, ...] = (),
    dependencies: tuple[str, ...] = (),
)

Tests dataclass

Tests(
    paths: tuple[str, ...] | None = None,
    exclude: tuple[str, ...] | None = None,
    file_pattern: str | None = None,
    function_pattern: str | None = None,
)

Toolchain dataclass

Toolchain(
    compiler: str | None = None, linker: str | None = None
)

dump_settings

dump_settings(settings: ArxProject) -> str

Source code in src/arx/settings.py

def dump_settings(settings: ArxProject) -> str:
    """
    title: Serialize settings into canonical ``.arxproject.toml`` text.
    parameters:
      settings:
        type: ArxProject
    returns:
      type: str
    """
    _validate_data(_settings_to_data(settings))

    lines: list[str] = []
    _append_project(lines, settings.project)
    _append_dependency_groups(lines, settings.dependency_groups)
    _append_environment(lines, settings.environment)
    _append_build(lines, settings.build)
    _append_toolchain(lines, settings.toolchain)
    _append_tests(lines, settings.tests)
    return "\n".join(lines) + "\n"

find_config_file

find_config_file(start: Path | None = None) -> Path | None

Source code in src/arx/settings.py

def find_config_file(start: Path | None = None) -> Path | None:
    """
    title: Walk upward from ``start`` to locate ``.arxproject.toml``.
    parameters:
      start:
        type: Path | None
    returns:
      type: Path | None
    """
    current = (start or Path.cwd()).resolve()
    while True:
        candidate = current / DEFAULT_CONFIG_FILENAME
        if candidate.is_file():
            return candidate
        if current.parent == current:
            return None
        current = current.parent

load_settings

load_settings(path: str | Path | None = None) -> ArxProject

Source code in src/arx/settings.py

def load_settings(path: str | Path | None = None) -> ArxProject:
    """
    title: Load and validate ``.arxproject.toml`` into a typed dataclass.
    parameters:
      path:
        type: str | Path | None
    returns:
      type: ArxProject
    """
    if path is None:
        discovered = find_config_file()
        if discovered is None:
            raise ArxProjectError(
                f"could not find {DEFAULT_CONFIG_FILENAME} in the current "
                "directory or any parent"
            )
        resolved = discovered
    else:
        resolved = Path(path)
        if not resolved.is_file():
            raise ArxProjectError(
                f"{DEFAULT_CONFIG_FILENAME} not found at {resolved}"
            )

    content = resolved.read_text(encoding="utf-8")
    return load_settings_from_text(content, source_path=resolved)

load_settings_from_text

load_settings_from_text(
    content: str, source_path: Path | None = None
) -> ArxProject

Source code in src/arx/settings.py

def load_settings_from_text(
    content: str,
    source_path: Path | None = None,
) -> ArxProject:
    """
    title: Parse and validate one ``.arxproject.toml`` string.
    parameters:
      content:
        type: str
      source_path:
        type: Path | None
    returns:
      type: ArxProject
    """
    try:
        data = tomllib.loads(content)
    except tomllib.TOMLDecodeError as err:
        raise ArxProjectError(
            f"Invalid TOML in .arxproject.toml: {err}"
        ) from err

    _validate_data(data)
    return _build_arx_project(data, source_path)

resolve_source_root

resolve_source_root(project: ArxProject) -> Path

Source code in src/arx/settings.py

def resolve_source_root(project: ArxProject) -> Path:
    """
    title: Resolve the effective source root from manifest defaults.
    parameters:
      project:
        type: ArxProject
    returns:
      type: Path
    """
    if project.source_path is None:
        raise ArxProjectError(
            "cannot resolve the project source root without a manifest path"
        )
    return (
        project.source_path.parent / _resolved_src_dir(project.build)
    ).resolve()

write_settings

write_settings(
    settings: ArxProject,
    path: str | Path = DEFAULT_CONFIG_FILENAME,
) -> Path

Source code in src/arx/settings.py

def write_settings(
    settings: ArxProject,
    path: str | Path = DEFAULT_CONFIG_FILENAME,
) -> Path:
    """
    title: Write canonical ``.arxproject.toml`` text to disk.
    parameters:
      settings:
        type: ArxProject
      path:
        type: str | Path
    returns:
      type: Path
    """
    target = Path(path)
    target.write_text(dump_settings(settings), encoding="utf-8")
    return target