fermilink.packages.package_registry module

exception fermilink.packages.package_registry.PackageError

Bases: RuntimeError

Base package-management error.

__init__(*args, **kwargs)

classmethod __new__(*args, **kwargs)

add_note(object, /)

Exception.add_note(note) – add a note to the exception

args

with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception fermilink.packages.package_registry.PackageNotFoundError

Bases: PackageError

Raised when a package id cannot be found.

__init__(*args, **kwargs)

classmethod __new__(*args, **kwargs)

add_note(object, /)

Exception.add_note(note) – add a note to the exception

args

with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception fermilink.packages.package_registry.PackageValidationError

Bases: PackageError

Raised when package metadata is invalid.

__init__(*args, **kwargs)

classmethod __new__(*args, **kwargs)

add_note(object, /)

Exception.add_note(note) – add a note to the exception

args

with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

fermilink.packages.package_registry.activate_package(scipkg_root, package_id)

Set a package as the active package in registry state.

Parameters:

• scipkg_root (Path) – Scientific package root containing registry and package files.

• package_id (str) – Normalized package identifier.

Returns:

Package metadata for the newly active package.

Return type:

dict[str, Any]

fermilink.packages.package_registry.delete_package(scipkg_root, package_id, *, remove_files=True)

Delete a package from registry state and optionally remove files.

Parameters:

• scipkg_root (Path) – Scientific package root containing registry and package files.

• package_id (str) – Normalized package identifier.

• remove_files (bool) – Whether installed package files should be deleted from disk.

Returns:

Package metadata for the deleted package.

Return type:

dict[str, Any]

fermilink.packages.package_registry.install_from_local_path(scipkg_root, package_id, *, local_path, title=None, activate=False, force=False)

Install a package from a local path and register it.

Parameters:

• scipkg_root (Path) – Scientific package root containing registry and package files.

• package_id (str) – Normalized package identifier.

• local_path (Path) – Local package directory path to install from.

• title (str | None) – Optional human-readable package title.

• activate (bool) – Whether to mark the package as active after operation completion.

• force (bool) – Whether existing package ids may be overwritten.

Returns:

Package metadata for the installed package.

Return type:

dict[str, Any]

fermilink.packages.package_registry.install_from_zip(scipkg_root, package_id, *, zip_url, title=None, activate=False, force=False, max_zip_bytes=800 * 1024 * 1024)

Install a package from a zip archive URL and register it.

Parameters:

• scipkg_root (Path) – Scientific package root containing registry and package files.

• package_id (str) – Normalized package identifier.

• zip_url (str) – URL of the zip archive to download and install.

• title (str | None) – Optional human-readable package title.

• activate (bool) – Whether to mark the package as active after operation completion.

• force (bool) – Whether existing package ids may be overwritten.

• max_zip_bytes (int) – Maximum allowed zip size in bytes before aborting download/install.

Returns:

Package metadata for the installed package.

Return type:

dict[str, Any]

fermilink.packages.package_registry.iter_package_entries(package_root, include_names=None)

Enumerate installable package entries from a package directory.

Parameters:

• package_root (Path) – Root directory of one installed package.

• include_names (list[str] | None) – Optional allowlist of entry names to include when enumerating package contents.

Returns:

Tuple of (entries, skipped_names) from package directory traversal.

Return type:

tuple[list[Path], list[str]]

fermilink.packages.package_registry.list_packages(scipkg_root)

Return package metadata entries from the registry.

Parameters:

scipkg_root (Path) – Scientific package root containing registry and package files.

Returns:

Package metadata mapping keyed by package id.

Return type:

dict[str, Any]

fermilink.packages.package_registry.load_registry(scipkg_root)

Load the package registry for a scientific package root.

Parameters:

scipkg_root (Path) – Scientific package root containing registry and package files.

Returns:

Normalized registry payload.

Return type:

dict[str, Any]

fermilink.packages.package_registry.load_workspace_manifest(workspace_root)

Load workspace overlay manifest state from disk.

Parameters:

workspace_root (Path) – Workspace root where manifest state is stored.

Returns:

Workspace manifest payload, or None when absent/invalid.

Return type:

dict[str, Any] | None

fermilink.packages.package_registry.normalize_package_id(value)

Normalize and validate a package identifier.

Parameters:

value (str) – Raw value to normalize.

Returns:

Normalized package id.

Return type:

str

fermilink.packages.package_registry.overlay_package_into_repo(repo_dir, workspace_root, package_id, package_meta, *, scipkg_root, allow_replace_existing=False)

Overlay an installed package into a workspace repository.

Parameters:

• repo_dir (Path) – Workspace repository path receiving overlaid entries.

• workspace_root (Path) – Workspace root where manifest state is stored.

• package_id (str) – Normalized package identifier.

• package_meta (dict[str, Any]) – Installed package metadata record from the registry.

• scipkg_root (Path) – Scientific package root containing registry and package files.

• allow_replace_existing (bool) – Whether existing destination entries may be replaced.

Returns:

Overlay result payload with applied entries and manifest metadata.

Return type:

dict[str, Any]

fermilink.packages.package_registry.packages_root(scipkg_root)

Return the package storage root and ensure it exists.

Parameters:

scipkg_root (Path) – Scientific package root containing registry and package files.

Returns:

Directory path where installed packages are stored.

Return type:

Path

fermilink.packages.package_registry.register_package(scipkg_root, package_id, *, installed_path, source, title=None, activate=False, extra=None)

Register or update a package entry in the registry.

Parameters:

• scipkg_root (Path) – Scientific package root containing registry and package files.

• package_id (str) – Normalized package identifier.

• installed_path (Path) – Filesystem path of the installed package content.

• source (str) – Source label recorded in package metadata.

• title (str | None) – Optional human-readable package title.

• activate (bool) – Whether to mark the package as active after operation completion.

• extra (dict[str, Any] | None) – Additional metadata fields merged into the package record.

Returns:

Package metadata for the registered package.

Return type:

dict[str, Any]

fermilink.packages.package_registry.registry_path(scipkg_root)

Return the package registry file path.

Parameters:

scipkg_root (Path) – Scientific package root containing registry and package files.

Returns:

Path to the registry JSON file.

Return type:

Path

fermilink.packages.package_registry.resolve_session_package(scipkg_root, workspace_root, requested_package_id=None)

Resolve the package to use for the current session/workspace.

Parameters:

• scipkg_root (Path) – Scientific package root containing registry and package files.

• workspace_root (Path) – Workspace root where manifest state is stored.

• requested_package_id (str | None) – Optional package id explicitly requested for the session.

Returns:

Tuple containing resolved package id and metadata, or (None, None).

Return type:

tuple[str, dict[str, Any]] | tuple[None, None]

fermilink.packages.package_registry.save_registry(scipkg_root, payload)

Save and normalize package registry state for a scientific package root.

Parameters:

• scipkg_root (Path) – Scientific package root containing registry and package files.

• payload (dict[str, Any]) – JSON-like payload to normalize or persist.

Returns:

Normalized registry payload after persistence.

Return type:

dict[str, Any]

fermilink.packages.package_registry.save_workspace_manifest(workspace_root, payload)

Save workspace overlay manifest state to disk.

Parameters:

• workspace_root (Path) – Workspace root where manifest state is stored.

• payload (dict[str, Any]) – JSON-like payload to normalize or persist.

Returns:

No return value.

Return type:

None

fermilink.packages.package_registry.set_package_dependency_ids(scipkg_root, package_id, dependency_package_ids)

Persist dependency package ids for an installed package.

Parameters:

• scipkg_root (Path) – Scientific package root containing registry and package files.

• package_id (str) – Normalized package identifier.

• dependency_package_ids (list[str] | None) – Dependency package ids to persist for this package.

Returns:

Updated package metadata after dependency persistence.

Return type:

dict[str, Any]

fermilink.packages.package_registry.set_package_overlay_entries(scipkg_root, package_id, entries)

Persist overlay entry names for an installed package.

Parameters:

• scipkg_root (Path) – Scientific package root containing registry and package files.

• package_id (str) – Normalized package identifier.

• entries (list[str] | None) – Overlay entry names to persist for this package.

Returns:

Updated package metadata after overlay entry persistence.

Return type:

dict[str, Any]

fermilink.packages.package_registry.workspace_manifest_path(workspace_root)

Return the workspace manifest file path.

Parameters:

workspace_root (Path) – Workspace root where manifest state is stored.

Returns:

Path to the workspace manifest JSON file.

Return type:

Path