Skip to content

workspace

_workspace

Workspace context detection for UV workspaces.

Detects whether a project path is a standalone package, a UV workspace root, or a member of a UV workspace. Used by the check engine to filter checks by context.

ProjectContext

Bases: StrEnum

Project context within a UV workspace layout.

Source code in packages/axm-init/src/axm_init/checks/_workspace.py
Python
34
35
36
37
38
39
class ProjectContext(StrEnum):
    """Project context within a UV workspace layout."""

    STANDALONE = "standalone"
    WORKSPACE = "workspace"
    MEMBER = "member"

detect_context(path)

Detect whether path is a standalone package, workspace, or member.

Detection logic:

  1. If path/pyproject.toml has [tool.uv.workspace] → WORKSPACE
  2. If a parent directory is a workspace root → MEMBER
  3. Otherwise → STANDALONE

Gracefully falls back to STANDALONE on missing or corrupt TOML.

Parameters:

Name Type Description Default
path Path

Project root directory to inspect.

 required

Returns:

Type Description
ProjectContext

The detected ProjectContext.
Source code in packages/axm-init/src/axm_init/checks/_workspace.py
Python
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def detect_context(path: Path) -> ProjectContext:
    """Detect whether *path* is a standalone package, workspace, or member.

    Detection logic:

    1. If *path*/pyproject.toml has ``[tool.uv.workspace]`` → ``WORKSPACE``
    2. If a parent directory is a workspace root → ``MEMBER``
    3. Otherwise → ``STANDALONE``

    Gracefully falls back to ``STANDALONE`` on missing or corrupt TOML.

    Args:
        path: Project root directory to inspect.

    Returns:
        The detected ``ProjectContext``.
    """
    data = _load_pyproject(path)

    # Case 1: this path IS a workspace root
    if data is not None and _has_workspace_section(data):
        return ProjectContext.WORKSPACE

    # Case 2: check if a parent is a workspace root
    root = find_workspace_root(path)
    if root is not None:
        return ProjectContext.MEMBER

    # Case 3: standalone (including missing/corrupt TOML)
    return ProjectContext.STANDALONE

find_workspace_root(path)

Walk parent directories looking for a UV workspace root.

A workspace root is a directory whose pyproject.toml contains a [tool.uv.workspace] section. Delegates to :func:axm_ingot.uv.find_workspace_root (identical walk-up semantics: first ancestor carrying [tool.uv.workspace]).

Parameters:

Name Type Description Default
path Path

Starting directory (typically a member package).

 required

Returns:

Type Description
Path | None

The workspace root Path, or None if not found.
Source code in packages/axm-init/src/axm_init/checks/_workspace.py
Python
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
def find_workspace_root(path: Path) -> Path | None:
    """Walk parent directories looking for a UV workspace root.

    A workspace root is a directory whose ``pyproject.toml`` contains a
    ``[tool.uv.workspace]`` section. Delegates to
    :func:`axm_ingot.uv.find_workspace_root` (identical walk-up semantics:
    first ancestor carrying ``[tool.uv.workspace]``).

    Args:
        path: Starting directory (typically a member package).

    Returns:
        The workspace root ``Path``, or ``None`` if not found.
    """
    return _ingot_find_workspace_root(path)

get_workspace_members(path)

Resolve workspace member package names from path.

Reads the members globs from [tool.uv.workspace] in the pyproject.toml at path, resolves them, and filters out directories matching exclude globs. Each resolved directory must contain a pyproject.toml to be considered a valid member.

Delegates resolution to :func:axm_ingot.uv.resolve_workspace and projects the member names.

Parameters:

Name Type Description Default
path Path

Workspace root directory.

 required

Returns:

Type Description
list[str]

Sorted list of member directory names (relative to path).
Source code in packages/axm-init/src/axm_init/checks/_workspace.py
Python
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
def get_workspace_members(path: Path) -> list[str]:
    """Resolve workspace member package names from *path*.

    Reads the ``members`` globs from ``[tool.uv.workspace]`` in the
    pyproject.toml at *path*, resolves them, and filters out directories
    matching ``exclude`` globs. Each resolved directory must contain a
    ``pyproject.toml`` to be considered a valid member.

    Delegates resolution to :func:`axm_ingot.uv.resolve_workspace` and
    projects the member names.

    Args:
        path: Workspace root directory.

    Returns:
        Sorted list of member directory names (relative to *path*).
    """
    workspace = resolve_workspace(path)
    return [member.name for member in workspace.members] if workspace else []