fermilink.runner.scientific_packages module

exception fermilink.runner.scientific_packages.PackageError[source]

Bases: RuntimeError

Base error for scientific package management.

__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.runner.scientific_packages.PackageNotFoundError[source]

Bases: PackageError

Raised when a requested package is missing.

__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.runner.scientific_packages.PackageValidationError[source]

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.runner.scientific_packages.activate_package(scipkg_root, package_id)[source]

Set a package as active for future session resolution.

Parameters:

  • scipkg_root (Path) – Scientific package root.

  • package_id (str) – Raw or normalized package id.

Returns:

Metadata for the activated package.

Return type:

dict of str to Any

Raises:

PackageNotFoundError – Raised when the package id is not registered.

Register a legacy local MaxwellLink package when present.

Parameters:

scipkg_root (Path) – Scientific package root.

Returns:

Registered package id when local MaxwellLink exists, else None.

Return type:

str or None

fermilink.runner.scientific_packages.delete_package(scipkg_root, package_id, *, remove_files=True)[source]

Delete a registered package and optionally remove its managed files.

Parameters:

  • scipkg_root (Path) – Scientific package root.

  • package_id (str) – Raw or normalized package id.

  • remove_files (bool, optional) – Whether to delete package files when they are under managed packages/. Paths outside managed storage are never removed.

Returns:

Summary of deletion status and active-package update.

Return type:

dict[str, Any]

Raises:

PackageNotFoundError – Raised when the package id is not registered.

fermilink.runner.scientific_packages.find_project_root(start)[source]

Find the repository root by walking upward from a start path.

Parameters:

start (Path) – Starting path for upward project-root discovery.

Returns:

Detected repository/project root path.

Return type:

Path

fermilink.runner.scientific_packages.iter_package_entries(package_root, include_names=None)[source]

List exportable package root entries with optional filtering.

Parameters:

  • package_root (Path) – Installed package root directory.

  • include_names (list of str or None, optional) – Optional allow-list of top-level names to include.

Returns:

Selected entry paths and requested names that were missing.

Return type:

tuple of (list of Path, list of str)

Raises:

PackageValidationError – Raised when package_root is missing or not a directory.

fermilink.runner.scientific_packages.list_packages(scipkg_root)[source]

Return all registered packages.

Parameters:

scipkg_root (Path) – Scientific package root.

Returns:

Package metadata keyed by package id.

Return type:

dict of str to Any

fermilink.runner.scientific_packages.load_registry(scipkg_root)[source]

Load registry metadata under a file lock.

Parameters:

scipkg_root (Path) – Scientific package root.

Returns:

Current registry snapshot.

Return type:

dict of str to Any

fermilink.runner.scientific_packages.load_workspace_manifest(workspace_root)[source]

Load workspace package overlay manifest from disk.

Parameters:

workspace_root (Path) – Workspace root directory.

Returns:

Manifest payload when readable and valid, otherwise None.

Return type:

dict of str to Any or None

fermilink.runner.scientific_packages.normalize_package_id(value)[source]

Normalize a package id to a stable, filesystem-safe token.

Parameters:

value (str) – Raw package id value.

Returns:

Normalized package id containing lowercase alnum, -, and _.

Return type:

str

Raises:

PackageValidationError – Raised when the normalized id is empty.

fermilink.runner.scientific_packages.overlay_package_into_repo(repo_dir, workspace_root, package_id, package_meta, scipkg_root=None, *, allow_replace_existing=False)[source]

Overlay selected package entries into a workspace repository.

Parameters:

  • repo_dir (Path) – Workspace repository path that receives linked/copied entries.

  • workspace_root (Path) – Session workspace root storing the overlay manifest.

  • package_id (str) – Selected package id.

  • package_meta (dict of str to Any) – Package metadata containing installation details.

  • scipkg_root (Path or None, optional) – Scientific package root used to resolve dependency package metadata. Defaults to the configured global package root.

  • allow_replace_existing (bool, optional) – Whether existing repo entries may be replaced during overlay.

Returns:

Overlay summary including linked entries, collisions, and requested entry diagnostics, plus dependency package link diagnostics.

Return type:

dict[str, Any]

fermilink.runner.scientific_packages.packages_root(scipkg_root)[source]

Return the managed packages/ directory under the registry root.

Parameters:

scipkg_root (Path) – Scientific package root.

Returns:

Directory that stores installed package contents.

Return type:

Path

fermilink.runner.scientific_packages.register_package(scipkg_root, package_id, *, installed_path, source, title=None, activate=False, extra=None)[source]

Create or update package metadata in the registry.

Parameters:

  • scipkg_root (Path) – Scientific package root.

  • package_id (str) – Raw or normalized package id.

  • installed_path (Path) – On-disk package directory to register.

  • source (str) – Source descriptor (URL or local path marker).

  • title (str or None, optional) – Human-readable package title.

  • activate (bool, optional) – Whether to set this package as active immediately.

  • extra (dict of str to Any or None, optional) – Additional metadata fields to merge.

Returns:

Stored metadata for the package.

Return type:

dict of str to Any

Raises:

PackageValidationError – Raised when installed_path is missing or not a directory.

fermilink.runner.scientific_packages.registry_path(scipkg_root)[source]

Build the path to the package registry JSON file.

Parameters:

scipkg_root (Path) – Scientific package root.

Returns:

Absolute or relative registry file path.

Return type:

Path

fermilink.runner.scientific_packages.resolve_scipkg_root()[source]

Resolve and create the scientific package root directory.

Returns:

Existing or newly created scientific package root path.

Return type:

Path

fermilink.runner.scientific_packages.resolve_session_package(scipkg_root, workspace_root, requested_package_id=None)[source]

Resolve which package should be overlaid for a workspace session.

Resolution order is explicit request, workspace manifest pin, FERMILINK_SCIPKG_ACTIVE, then registry active package.

Parameters:

  • scipkg_root (Path) – Scientific package root.

  • workspace_root (Path) – Session workspace root.

  • requested_package_id (str or None, optional) – Optional explicit package id from the run request.

Returns:

(package_id, package_meta) when a valid package is selected; (None, None) when no package is available.

Return type:

tuple

Raises:

PackageNotFoundError – Raised when the requested package id does not exist.

fermilink.runner.scientific_packages.save_workspace_manifest(workspace_root, payload)[source]

Persist workspace package overlay manifest.

Parameters:

  • workspace_root (Path) – Workspace root directory.

  • payload (dict of str to Any) – Manifest payload to write.

Returns:

Manifest file is updated in place.

Return type:

None

fermilink.runner.scientific_packages.set_package_dependency_ids(scipkg_root, package_id, dependency_package_ids)[source]

Update package-level dependency package metadata.

Parameters:

  • scipkg_root (Path) – Scientific package root.

  • package_id (str) – Raw or normalized package id.

  • dependency_package_ids (list of str or None) – Dependency package ids required by this package. None clears configured dependencies.

Returns:

Updated package metadata.

Return type:

dict of str to Any

Raises:

PackageNotFoundError – Raised when the package id is not registered or dependency package ids reference unknown packages.

fermilink.runner.scientific_packages.set_package_overlay_entries(scipkg_root, package_id, entries)[source]

Update package-level overlay entry selection metadata.

Parameters:

  • scipkg_root (Path) – Scientific package root.

  • package_id (str) – Raw or normalized package id.

  • entries (list of str or None) – Allowed top-level entry names. None clears the custom selection.

Returns:

Updated package metadata.

Return type:

dict of str to Any

Raises:

PackageNotFoundError – Raised when the package id is not registered.

fermilink.runner.scientific_packages.workspace_manifest_path(workspace_root)[source]

Build the path to a workspace package manifest file.

Parameters:

workspace_root (Path) – Workspace root directory.

Returns:

Manifest file path under the workspace root.

Return type:

Path