cayu.workspaces.local

Public Cayu API. Definitions are grouped by their public source module, and definitions from private implementation modules appear on their package’s page; adding a symbol does not move existing links. The import shown at each entry is a supported public namespace. Read the Python API overview and install the required extra.

LocalWorkspace

from cayu.workspaces import LocalWorkspace

Filesystem workspace rooted at one local directory.

excluded_directory_names and excluded_path_patterns remove matching paths from listing and reject every direct read, resolution, or mutation. This opt-in projected view does not advertise workspace branching because a branch must not regain access to excluded source authority.

Bases: Workspace, WorkspaceGitModeMutator, WorkspaceDirectoryPruner.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
id	str	required

reference_binding (method)

LocalWorkspace.reference_binding() -> WorkspaceReferenceBinding

Bind application data to this workspace incarnation.

The default is object-lifetime scoped and fails closed after reopening. Durable adapters may override this method only when they can preserve an incarnation across recovery and rotate it on replacement. Never restore a generation from the application reference being validated.

read_bytes (method)

async LocalWorkspace.read_bytes(path: str, *, offset: int=0, max_bytes: int | None=None) -> WorkspaceReadResult

bounded_read_limit (method)

LocalWorkspace.bounded_read_limit(max_bytes: int) -> int

write_bytes (method)

async LocalWorkspace.write_bytes(path: str, content: bytes) -> None

delete (method)

async LocalWorkspace.delete(path: str) -> None

create_bytes (method)

async LocalWorkspace.create_bytes(path: str, content: bytes) -> WorkspaceMutationResult

replace_bytes (method)

async LocalWorkspace.replace_bytes(path: str, content: bytes, *, expected_revision: str) -> WorkspaceMutationResult

delete_if_revision (method)

async LocalWorkspace.delete_if_revision(path: str, *, expected_revision: str) -> WorkspaceMutationResult

require_absent (method)

async LocalWorkspace.require_absent(path: str) -> None

move_if_revision (method)

async LocalWorkspace.move_if_revision(source_path: str, destination_path: str, *, expected_source_revision: str, require_destination_absent: bool=True) -> WorkspaceMoveResult

list (method)

async LocalWorkspace.list(pattern: str='**/*', *, limit: int | None=None) -> WorkspaceListResult

list_git_entries (method)

async LocalWorkspace.list_git_entries(*, limit: int) -> WorkspaceGitEntryListResult

resource_key (property)

LocalWorkspace.resource_key() -> tuple[object, ...]

tar_copy_policy_identity (method)

LocalWorkspace.tar_copy_policy_identity() -> tuple[object, ...]

bounded_tar_stream_reader (method)

LocalWorkspace.bounded_tar_stream_reader() -> BoundedTarStreamReader | None

Return an explicit bounded streaming-tar reader capability, if any.

tar_stream_writer (method)

LocalWorkspace.tar_stream_writer() -> TarStreamWriter | None

Return an explicit streaming-tar writer capability, if any.

branch_capabilities (method)

LocalWorkspace.branch_capabilities() -> WorkspaceBranchCapabilities

branch_lifecycle_summary (method)

LocalWorkspace.branch_lifecycle_summary() -> WorkspaceBranchLifecycleSummary

create_branch (method)

async LocalWorkspace.create_branch(request: WorkspaceBranchRequest) -> WorkspaceBranchCreationResult

write_bytes_with_git_mode (method)

async LocalWorkspace.write_bytes_with_git_mode(path: str, content: bytes, *, git_mode: WorkspaceGitMode) -> None

create_bytes_with_git_mode (method)

async LocalWorkspace.create_bytes_with_git_mode(path: str, content: bytes, *, git_mode: WorkspaceGitMode) -> WorkspaceMutationResult

replace_bytes_with_git_mode (method)

async LocalWorkspace.replace_bytes_with_git_mode(path: str, content: bytes, *, expected_revision: str, expected_git_mode: WorkspaceGitMode, git_mode: WorkspaceGitMode) -> WorkspaceMutationResult

prune_empty_directories (method)

async LocalWorkspace.prune_empty_directories(path: str, *, max_directories: int) -> None

init (method)

LocalWorkspace.__init__(root: str | Path, *, workspace_id: str | None=None, excluded_directory_names: Iterable[str]=(), excluded_path_patterns: Iterable[str]=(), branch_store: WorkspaceBranchStore | None=None, branch_authority_resolver: WorkspaceBranchBindingAuthorityProvider | None=None) -> None

require_path_operations_supported (method)

LocalWorkspace.require_path_operations_supported() -> None

Require the primitives used by secure path-addressed operations.

recover_branch (method)

async LocalWorkspace.recover_branch(request: WorkspaceBranchRecoveryRequest) -> WorkspaceBranchRecoveryResult

Recover one durable local branch from store and filesystem evidence.

resolve (method)

LocalWorkspace.resolve(path: str) -> Path

resolve_no_symlinks (method)

LocalWorkspace.resolve_no_symlinks(path: str) -> Path

Release source · Runtime guarantees · Capability guides