Skip to content

Index

core

AXM Core package.

WorkspaceIdentity dataclass

A workspace's name, and where its repository and documentation live.

Attributes:

Name Type Description
name str

Root [project].name (or the checkout directory name).

repository str

GitHub owner/name of the workspace repository.

site_url str

Root URL of the workspace documentation site, without a trailing slash; each member is published under <site_url>/<name>/.

Source code in packages/axm-init/src/axm_init/core/scaffolder.py
Python
@dataclass(frozen=True, slots=True)
class WorkspaceIdentity:
    """A workspace's name, and where its repository and documentation live.

    Attributes:
        name: Root ``[project].name`` (or the checkout directory name).
        repository: GitHub ``owner/name`` of the workspace repository.
        site_url: Root URL of the workspace documentation site, without a
            trailing slash; each member is published under ``<site_url>/<name>/``.
    """

    name: str
    repository: str
    site_url: str

    @classmethod
    def on_github(cls, name: str, repository: str) -> WorkspaceIdentity:
        """Identity of a repository documented on its GitHub Pages site."""
        owner, _, repo = repository.partition("/")
        return cls(name, repository, f"https://{owner}.github.io/{repo}")
on_github(name, repository) classmethod

Identity of a repository documented on its GitHub Pages site.

Source code in packages/axm-init/src/axm_init/core/scaffolder.py
Python
@classmethod
def on_github(cls, name: str, repository: str) -> WorkspaceIdentity:
    """Identity of a repository documented on its GitHub Pages site."""
    owner, _, repo = repository.partition("/")
    return cls(name, repository, f"https://{owner}.github.io/{repo}")

build_member_data(member_name, workspace=None, scaffold_data=None, *, license_holder=None, private=None, **legacy)

Build copier template variables for a workspace member scaffold.

Parameters:

Name Type Description Default
member_name str

Name of the new member package.

required
workspace str | WorkspaceIdentity | None

Parent workspace, as resolved by :func:read_workspace_identity; a bare name stands for org/<name> documented on GitHub Pages. Required.

None
scaffold_data Mapping[str, str] | None

Caller identity fields — org, author_name, author_email, license and optionally description. Required.

None
license_holder str | None

Explicit LICENSE holder; falls back to org.

None
private bool | None

Publication guard forwarded to Copier when provided.

None
**legacy Unpack[_LegacyMemberKeywords]

workspace_name, the deprecated spelling of workspace (a bare name) kept for callers written against the former signature; it emits a :class:DeprecationWarning.

{}

Returns:

Type Description
dict[str, object]

The template-variable dict passed verbatim to copier. Identical inputs

dict[str, object]

yield a byte-identical dict whatever the calling interface.

Raises:

Type Description
TypeError

If scaffold_data or the workspace is missing, if both workspace and workspace_name are given, or on an unknown keyword.

Source code in packages/axm-init/src/axm_init/core/scaffolder.py
Python
def build_member_data(
    member_name: str,
    workspace: str | WorkspaceIdentity | None = None,
    scaffold_data: Mapping[str, str] | None = None,
    *,
    license_holder: str | None = None,
    private: bool | None = None,
    **legacy: Unpack[_LegacyMemberKeywords],
) -> dict[str, object]:
    """Build copier template variables for a workspace member scaffold.

    Args:
        member_name: Name of the new member package.
        workspace: Parent workspace, as resolved by
            :func:`read_workspace_identity`; a bare name stands for
            ``org/<name>`` documented on GitHub Pages. Required.
        scaffold_data: Caller identity fields — ``org``, ``author_name``,
            ``author_email``, ``license`` and optionally ``description``.
            Required.
        license_holder: Explicit LICENSE holder; falls back to ``org``.
        private: Publication guard forwarded to Copier when provided.
        **legacy: ``workspace_name``, the deprecated spelling of *workspace*
            (a bare name) kept for callers written against the former
            signature; it emits a :class:`DeprecationWarning`.

    Returns:
        The template-variable dict passed verbatim to copier. Identical inputs
        yield a byte-identical dict whatever the calling interface.

    Raises:
        TypeError: If *scaffold_data* or the workspace is missing, if both
            *workspace* and ``workspace_name`` are given, or on an unknown
            keyword.
    """
    if scaffold_data is None:
        msg = "build_member_data() missing required argument: 'scaffold_data'"
        raise TypeError(msg)
    org = scaffold_data["org"]
    workspace = _workspace_argument(workspace, legacy)
    if isinstance(workspace, str):
        workspace = WorkspaceIdentity.on_github(workspace, f"{org}/{workspace}")
    data: dict[str, object] = {
        "member_name": member_name,
        "workspace_name": workspace.name,
        "description": scaffold_data.get("description") or _DEFAULT_MEMBER_DESCRIPTION,
        "org": org,
        "license": scaffold_data["license"],
        "license_holder": license_holder or org,
        "author_name": scaffold_data["author_name"],
        "author_email": scaffold_data["author_email"],
        "repository": workspace.repository,
        "docs_url": f"{workspace.site_url}/{member_name}/",
    }
    if private is not None:
        data["private"] = private
    return data

read_workspace_identity(workspace_root, org)

Resolve a workspace's name, repository and documentation site.

The root mkdocs.yml (repo_url, site_url) wins, since it is what the published site uses; then the root [project.urls] (Repository or Homepage, Documentation); then org/<checkout directory> on GitHub Pages. The root [project].name is never used: workspaces often name their root project <repository>-workspace.

Source code in packages/axm-init/src/axm_init/core/scaffolder.py
Python
def read_workspace_identity(workspace_root: Path, org: str) -> WorkspaceIdentity:
    """Resolve a workspace's name, repository and documentation site.

    The root ``mkdocs.yml`` (``repo_url``, ``site_url``) wins, since it is what
    the published site uses; then the root ``[project.urls]`` (``Repository``
    or ``Homepage``, ``Documentation``); then ``org/<checkout directory>`` on
    GitHub Pages. The root ``[project].name`` is never used: workspaces often
    name their root project ``<repository>-workspace``.
    """
    mkdocs = _mkdocs_links(workspace_root / "mkdocs.yml")
    urls = _project_urls(workspace_root / "pyproject.toml")
    repository = (
        _github_repository(mkdocs.get("repo_url"))
        or _github_repository(urls.get("Repository"))
        or _github_repository(urls.get("Homepage"))
        or f"{org}/{workspace_root.name}"
    )
    documentation = urls.get("Documentation")
    site_url = mkdocs.get("site_url") or (
        documentation if isinstance(documentation, str) else None
    )
    name = read_workspace_name(workspace_root)
    if not site_url:
        return WorkspaceIdentity.on_github(name, repository)
    return WorkspaceIdentity(name, repository, site_url.rstrip("/"))

read_workspace_name(workspace_root)

Read the workspace name from pyproject.toml or fall back to dir name.

Source code in packages/axm-init/src/axm_init/core/scaffolder.py
Python
def read_workspace_name(workspace_root: Path) -> str:
    """Read the workspace name from ``pyproject.toml`` or fall back to dir name."""
    root_pyproject = workspace_root / "pyproject.toml"
    if root_pyproject.is_file():
        with open(root_pyproject, "rb") as f:
            root_data = tomllib.load(f)
        return str(root_data.get("project", {}).get("name", workspace_root.name))
    return workspace_root.name

resolve_workspace_root(target_path)

Resolve the workspace root for target_path, or None.

Returns target_path itself when it is a workspace root, the parent workspace root when target_path is a member, and None otherwise.

Source code in packages/axm-init/src/axm_init/core/scaffolder.py
Python
def resolve_workspace_root(target_path: Path) -> Path | None:
    """Resolve the workspace root for *target_path*, or ``None``.

    Returns *target_path* itself when it is a workspace root, the parent
    workspace root when *target_path* is a member, and ``None`` otherwise.
    """
    from axm_init.checks._workspace import (
        ProjectContext,
        detect_context,
        find_workspace_root,
    )

    context = detect_context(target_path)
    if context == ProjectContext.WORKSPACE:
        return target_path
    if context == ProjectContext.MEMBER:
        return find_workspace_root(target_path)
    return None