fermilink.packages package

Scientific package-management namespace.

fermilink.packages.atomic_write_json(path, payload)

Write JSON payload to disk atomically.

Parameters:

• path (Path) – Filesystem path to read/write.

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

Returns:

No return value.

Return type:

None

fermilink.packages.build_default_registry(*, updated_at)

Build an empty package registry payload with standard fields.

Parameters:

updated_at (str) – Timestamp string written into normalized payload metadata.

Returns:

Default registry payload with empty package map.

Return type:

dict[str, Any]

fermilink.packages.extract_manifest_dependency_ids(manifest)

Extract managed dependency package ids from a workspace manifest.

Parameters:

manifest (dict[str, Any] | None) – Workspace manifest payload tracking managed overlays/dependencies.

Returns:

Set of managed dependency package ids.

Return type:

set[str]

fermilink.packages.extract_manifest_entry_names(manifest)

Extract managed overlay entry names from a workspace manifest.

Parameters:

manifest (dict[str, Any] | None) – Workspace manifest payload tracking managed overlays/dependencies.

Returns:

Set of managed overlay entry names.

Return type:

set[str]

fermilink.packages.is_exportable_entry_name(name)

Return whether a package entry name is exportable to a workspace overlay.

Parameters:

name (str) – Candidate file/directory entry name.

Returns:

Whether the entry is eligible for workspace overlay.

Return type:

bool

fermilink.packages.link_or_copy_entry(src, dst)

Materialize one package entry as a symlink or copy in the workspace.

Parameters:

• src (Path) – Source path for the entry being linked or copied.

• dst (Path) – Destination path where the entry is materialized.

Returns:

Operation mode used (symlink or copy).

Return type:

str

fermilink.packages.load_registry_file(path, *, default_registry, normalize_registry)

Load and normalize a package registry file from disk.

Parameters:

• path (Path) – Filesystem path to read/write.

• default_registry (Callable[[], dict[str, Any]]) – Factory callback that returns a default registry payload.

• normalize_registry (Callable[[Any], dict[str, Any]]) – Callback that validates and normalizes registry payloads.

Returns:

Normalized registry payload loaded from disk or defaults.

Return type:

dict[str, Any]

fermilink.packages.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.normalize_registry_payload(payload, *, updated_at, normalize_package_id, dependency_key=PACKAGE_DEPENDENCY_IDS_KEY, dependency_normalizer=None, coerce_non_dict_meta_to_empty=True, fallback_active_to_first_package=True)

Normalize and validate registry payload structure and package metadata.

Parameters:

• payload (Any) – JSON-like payload to normalize or persist.

• updated_at (str) – Timestamp string written into normalized payload metadata.

• normalize_package_id (Callable[[str], str]) – Callback used to validate and normalize package ids.

• dependency_key (str) – Registry metadata key used for dependency id storage.

• dependency_normalizer (Callable[[Any, str], list[str] | None] | None) – Optional callback used to normalize dependency metadata fields.

• coerce_non_dict_meta_to_empty (bool) – Whether non-dict package metadata should be coerced to empty dicts.

• fallback_active_to_first_package (bool) – Whether to set active_package to first package when missing/invalid.

Returns:

Normalized registry payload ready for persistence.

Return type:

dict[str, Any]

fermilink.packages.overlay_package_into_repo_core(*, repo_dir, workspace_root, package_id, package_meta, allow_replace_existing, now_iso, resolve_package_meta_path, normalize_overlay_entries, normalize_dependency_ids, iter_package_entries, load_workspace_manifest, save_workspace_manifest, normalize_package_id, get_package_map, replace_existing_entries_for_previous_names, remove_non_symlink_managed_entries, overlay_entries_key=PACKAGE_OVERLAY_ENTRIES_KEY, dependency_ids_key=PACKAGE_DEPENDENCY_IDS_KEY, dependencies_dirname=PACKAGE_DEPENDENCIES_DIRNAME, remove_existing=remove_existing_entry, link_or_copy=link_or_copy_entry)

Overlay package entries into a workspace and persist manifest ownership.

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.

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

• now_iso (Callable[[], str]) – Callback that returns the current ISO timestamp.

• resolve_package_meta_path (Callable[[dict[str, Any]], Path]) – Callback that resolves package metadata to install directory path.

• normalize_overlay_entries (Callable[[Any], list[str] | None]) – Callback that normalizes overlay entry metadata.

• normalize_dependency_ids (Callable[..., list[str] | None]) – Callback that normalizes dependency package id metadata.

• iter_package_entries (Callable[[Path, list[str] | None], tuple[list[Path], list[str]]]) – Callback that lists installable package entries from package root.

• load_workspace_manifest (Callable[[Path], dict[str, Any] | None]) – Callback that loads workspace manifest data.

• save_workspace_manifest (Callable[[Path, dict[str, Any]], None]) – Callback that saves workspace manifest data.

• normalize_package_id (Callable[[str], str]) – Callback used to validate and normalize package ids.

• get_package_map (Callable[[str, dict[str, Any]], dict[str, Any]]) – Callback that retrieves package metadata mappings for dependency resolution.

• replace_existing_entries_for_previous_names (bool) – Whether to clear stale managed entry names from previous overlays.

• remove_non_symlink_managed_entries (bool) – Whether managed regular files/directories can be removed during cleanup.

• overlay_entries_key (str) – Package metadata key that stores overlaid entry names.

• dependency_ids_key (str) – Package metadata key that stores dependency package ids.

• dependencies_dirname (str) – Workspace subdirectory name used for dependency overlays.

• remove_existing (Callable[[Path], None]) – Callback used to remove filesystem entries.

• link_or_copy (Callable[[Path, Path], str]) – Callback that links/copies an entry into the workspace.

Returns:

Overlay result payload with applied entries and manifest metadata.

Return type:

dict[str, Any]

fermilink.packages.remove_existing_entry(path)

Remove an existing file, directory, or symlink path.

Parameters:

path (Path) – Filesystem path to read/write.

Returns:

No return value.

Return type:

None

fermilink.packages.remove_managed_dependency_links(repo_dir, manifest, *, normalize_package_id, only_package_ids=None, dependencies_dirname=PACKAGE_DEPENDENCIES_DIRNAME, remove_existing=remove_existing_entry)

Remove managed dependency links recorded in workspace manifest state.

Parameters:

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

• manifest (dict[str, Any] | None) – Workspace manifest payload tracking managed overlays/dependencies.

• normalize_package_id (Callable[[str], str]) – Callback used to validate and normalize package ids.

• only_package_ids (set[str] | None) – Optional subset of dependency package ids to remove.

• dependencies_dirname (str) – Workspace subdirectory name used for dependency overlays.

• remove_existing (Callable[[Path], None]) – Callback used to remove filesystem entries.

Returns:

No return value.

Return type:

None

fermilink.packages.remove_managed_entries(repo_dir, manifest, *, only_names=None, remove_non_symlink_entries=False, remove_existing=remove_existing_entry)

Remove managed overlay entries recorded in workspace manifest state.

Parameters:

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

• manifest (dict[str, Any] | None) – Workspace manifest payload tracking managed overlays/dependencies.

• only_names (set[str] | None) – Optional subset of managed entry names to remove.

• remove_non_symlink_entries (bool) – Whether to also remove managed non-symlink entries.

• remove_existing (Callable[[Path], None]) – Callback used to remove filesystem entries.

Returns:

No return value.

Return type:

None

fermilink.packages.save_registry_file(path, payload, *, updated_at, normalize_registry)

Normalize and save a package registry payload to disk.

Parameters:

• path (Path) – Filesystem path to read/write.

• payload (Any) – JSON-like payload to normalize or persist.

• updated_at (str) – Timestamp string written into normalized payload metadata.

• normalize_registry (Callable[[Any], dict[str, Any]]) – Callback that validates and normalizes registry payloads.

Returns:

Normalized payload that was persisted to disk.

Return type:

dict[str, Any]

Submodules

• fermilink.packages.curated_channels module
  • ChannelPackage
    • ChannelPackage.__init__()
    • ChannelPackage.default_version
    • ChannelPackage.description
    • ChannelPackage.homepage_url
    • ChannelPackage.package_id
    • ChannelPackage.tags
    • ChannelPackage.title
    • ChannelPackage.upstream_repo_url
    • ChannelPackage.versions
    • ChannelPackage.zip_url
  • ChannelPackageVersion
    • ChannelPackageVersion.__init__()
    • ChannelPackageVersion.notes
    • ChannelPackageVersion.source_archive_url
    • ChannelPackageVersion.source_ref_type
    • ChannelPackageVersion.source_ref_value
    • ChannelPackageVersion.verified
    • ChannelPackageVersion.version_id
  • list_curated_packages()
  • normalize_channel_id()
  • resolve_curated_package()
  • select_package_version()
• fermilink.packages.package_core module
  • atomic_write_json()
  • build_default_registry()
  • extract_manifest_dependency_ids()
  • extract_manifest_entry_names()
  • is_exportable_entry_name()
  • link_or_copy_entry()
  • load_registry_file()
  • normalize_package_id()
  • normalize_registry_payload()
  • overlay_package_into_repo_core()
  • remove_existing_entry()
  • remove_managed_dependency_links()
  • remove_managed_entries()
  • save_registry_file()
• fermilink.packages.package_registry module
  • PackageError
    • PackageError.__init__()
    • PackageError.__new__()
    • PackageError.add_note()
    • PackageError.args
    • PackageError.with_traceback()
  • PackageNotFoundError
    • PackageNotFoundError.__init__()
    • PackageNotFoundError.__new__()
    • PackageNotFoundError.add_note()
    • PackageNotFoundError.args
    • PackageNotFoundError.with_traceback()
  • PackageValidationError
    • PackageValidationError.__init__()
    • PackageValidationError.__new__()
    • PackageValidationError.add_note()
    • PackageValidationError.args
    • PackageValidationError.with_traceback()
  • activate_package()
  • delete_package()
  • install_from_local_path()
  • install_from_zip()
  • iter_package_entries()
  • list_packages()
  • load_registry()
  • load_workspace_manifest()
  • normalize_package_id()
  • overlay_package_into_repo()
  • packages_root()
  • register_package()
  • registry_path()
  • resolve_session_package()
  • save_registry()
  • save_workspace_manifest()
  • set_package_dependency_ids()
  • set_package_overlay_entries()
  • workspace_manifest_path()