rlsbl v0.92.0 /rlsbl.workspace
Updated
On this page

Workspace data layer for monorepo support handling discovery, loading, saving, and resolution of workspaces from workspace.toml config.

#rlsbl.workspace

#rlsbl.workspace

Workspace data layer for monorepo support handling discovery, loading, saving, and resolution of workspaces from workspace.toml config.

#get_releasable_dir

python
def get_releasable_dir(workspace_root, releasable_name)

Return the directory path for a releasable's state files.

Path: /.rlsbl-monorepo/releasables//

Args:

  • workspace_root: path to the monorepo root.
  • releasable_name: name of the releasable.

Returns:

  • Absolute path string to the releasable directory.

#get_releasable_changes_dir

python
def get_releasable_changes_dir(workspace_root, releasable_name)

Return the path to a releasable's changelog changes directory.

Path: /.rlsbl-monorepo/releasables//changes/

Args:

  • workspace_root: path to the monorepo root.
  • releasable_name: name of the releasable.

Returns:

  • Absolute path string to the changes directory.

#get_releasable_version_path

python
def get_releasable_version_path(workspace_root, releasable_name)

Return the path to a releasable's version file.

Path: /.rlsbl-monorepo/releasables//version

Args:

  • workspace_root: path to the monorepo root.
  • releasable_name: name of the releasable.

Returns:

  • Absolute path string to the version file.

#read_releasable_version

python
def read_releasable_version(workspace_root, releasable_name)

Read the version string from a releasable's version file.

Args:

  • workspace_root: path to the monorepo root.
  • releasable_name: name of the releasable.

Returns:

  • The version string (stripped of whitespace).

Raises:

  • WorkspaceError: if the version file does not exist or is empty.

#write_releasable_version

python
def write_releasable_version(workspace_root, releasable_name, version)

Write a version string to a releasable's version file atomically.

Creates the releasable directory if it does not exist. Writes to a temporary file in the same directory and then atomically replaces the target file via os.replace().

Args:

  • workspace_root: path to the monorepo root.
  • releasable_name: name of the releasable.
  • version: the version string to write.

#is_explicit_mode

python
def is_explicit_mode(workspace_root)

Check whether the workspace has a [[releasables]] section.

Returns True when [[releasables]] is present in workspace.toml, False otherwise.

Args:

  • workspace_root: path to the monorepo root.

Returns:

  • bool

#Releasable

A named unit of versioning: a group of packages sharing version, changelog, and release.

Releasables are defined via [[releasables]] in workspace.toml.

#WorkspaceProject

Typed wrapper over a workspace.toml project dict.

Provides typed property access for known fields while preserving the underlying dict for round-trip serialization. Unknown fields are kept intact. Dict-like [], get(), and in access is supported for backward compatibility with code that treats projects as dicts.

#name

python
def name(self) -> str

#path

python
def path(self) -> str

#watch

python
def watch(self) -> list[str]

#library

python
def library(self) -> bool

#dev_only

python
def dev_only(self) -> bool

#dev_node

python
def dev_node(self) -> bool

Derived shorthand: True when dev_only and not a member of any releasable.

A project is considered non-releasable when releasable is explicitly False, OR when releasable is None and the legacy dev_node flag is set.

#is_releasable

python
def is_releasable(self) -> bool

Whether this project can produce releases.

A project is releasable when it belongs to some releasable unit (releasable = "name"). Returns False when releasable = false is set explicitly, or when the project is a dev_node.

#depends_on

python
def depends_on(self) -> list[str]

#releasable

python
def releasable(self) -> 'str | bool | None'

The releasable this project belongs to.

Returns:

  • str: name of the releasable group this project belongs to.
  • False: project is explicitly unversioned (no releases).
  • None: field not set.

#import_name

python
def import_name(self) -> str

#registry_name

python
def registry_name(self) -> str

#get

python
def get(self, key, default=None)

Dict-like access for backward compatibility.

#to_dict

python
def to_dict(self) -> dict

Return the underlying dict for serialization.

#project_is_dev_only

python
def project_is_dev_only(proj) -> bool

Check if a project is dev_only (works with WorkspaceProject or dict).

#project_is_releasable

python
def project_is_releasable(proj) -> bool

Check if a project is releasable (works with WorkspaceProject or dict).

#find_workspace_root

python
def find_workspace_root(start_path='.')

Walk up from start_path looking for a .rlsbl-monorepo/workspace.toml.

Returns the directory containing .rlsbl-monorepo/, or None if not found.

#load_workspace

python
def load_workspace(root)

Read and validate workspace.toml, returning a list of WorkspaceProject.

Each project has at least 'path' (str) and 'name' (str, defaults to basename of path). The returned WorkspaceProject instances support dict-like access for backward compatibility.

Raises FileNotFoundError if workspace.toml doesn't exist. Raises WorkspaceError on invalid structure.

#load_releasables

python
def load_releasables(root, projects=None)

Load releasable definitions from workspace.toml.

Reads and validates the [[releasables]] section, then validates that every releasable project has a valid releasable field referencing a defined releasable name (or false).

Args:

  • root: path to the monorepo root (containing .rlsbl-monorepo/).
  • projects: optional pre-loaded project list. If None, loads via

load_workspace(root).

Returns:

  • A list of Releasable instances.

Raises:

  • WorkspaceError if [[releasables]] is missing, or on invalid
  • releasable definitions or missing/invalid project releasable fields.

#_load_explicit_releasables

python
def _load_explicit_releasables(raw_releasables, projects)

Parse [[releasables]] section and validate project membership.

Every releasable project must have a releasable field that is either a string referencing a defined releasable name, or false.

#members_of

python
def members_of(releasable_name, projects)

Return the list of projects that belong to a given releasable.

Projects with releasable = "" matching the given name are returned as members.

Args:

  • releasable_name: the releasable name to look up.
  • projects: list of WorkspaceProject or dict instances.

Returns:

  • List of projects that are members of the releasable.

#resolve_releasable_for_project

python
def resolve_releasable_for_project(proj, releasables)

Return the Releasable that a project belongs to, or None.

Looks up the project's releasable field and matches it against the list of releasables.

Args:

  • proj: WorkspaceProject or dict with at least name and optionally

releasable.

  • releasables: list of Releasable instances.

Returns:

  • The matching Releasable, or None if the project is not releasable
  • (releasable = false) or no match is found.

#_get_releasable_value

python
def _get_releasable_value(proj)

Extract the releasable value from a project (WorkspaceProject or dict).

Returns str, False, or None. Does not validate -- just reads the raw value.

#save_workspace

python
def save_workspace(root, projects, releasables=None)

Write workspace.toml atomically using tomlkit for clean TOML output.

Preserves top-level sections, comments, and formatting from the existing file by reading it with tomlkit first and modifying the [[projects]] array in-place. Falls back to creating a new document when the file does not yet exist.

When releasables is passed (a list of Releasable instances), the [[releasables]] section is replaced. When releasables is None, any existing [[releasables]] section is preserved as-is. Pass an empty list to explicitly remove the section.

Creates .rlsbl-monorepo/ directory if it doesn't exist.

#resolve_project

python
def resolve_project(root, cwd='.')

Determine which project cwd is inside, returning a WorkspaceProject or None.

If multiple projects match (nested paths), returns the most specific one.

#_derive_standalone_name

python
def _derive_standalone_name(project_root)

Derive a project name for the standalone releasable.

Tries target read_name (first detected target), then falls back to the directory basename.

Args:

  • project_root: path to the project root (str or Path).

Returns:

  • A non-empty name string.

#load_standalone_releasable

python
def load_standalone_releasable(project_root)

Load an explicit releasable definition from .rlsbl/releasable.toml.

If the file exists, reads name and tag_format from it. If absent, returns None (caller should use create_standalone_releasable).

Args:

  • project_root: path to the project root (str or Path).

Returns:

  • A Releasable instance, or None if the file does not exist.

Raises:

  • WorkspaceError on invalid file contents.

#create_standalone_releasable

python
def create_standalone_releasable(project_root)

Return a Releasable representing a single-project repo.

If .rlsbl/releasable.toml exists, uses its explicit configuration. Otherwise, derives the name from the project's target metadata (e.g., pyproject.toml [project].name) or the directory basename, and uses the standalone tag format (v{version}).

This function does NOT create any files on disk -- the releasable is purely an internal abstraction.

Args:

  • project_root: path to the project root (str or Path).

Returns:

  • A Releasable instance.