Setup Repo

Setting up of pkg directory and imports.

ska_sci_ops_data_analysis.setup_repo.setup_repo(user: str | None = None, *, package_name: str = 'ska_sci_ops_data_analysis', ensure_package: bool = False, clear_stale: bool = True, verbose: bool = True) → Dict[str, Path]

Configure a JupyterHub session to import this package from the local repository.

This helper ensures that the repository src/ directory is placed at the front of sys.path, allowing imports to resolve against the working tree rather than an installed package. It is primarily intended for notebook-based workflows running in long-lived JupyterHub kernels.

Optionally, previously imported copies of the package may be removed from sys.modules to avoid stale imports after code changes.

Parameters:

  • user (str, optional) – Username matching the directory name under the shared folder. If not provided, the function will attempt to infer it from environment variables USER or``USERNAME``.

  • package_name (str) – Importable package name located under <repo>/src (defaults to "ska_sci_ops_data_analysis").

  • ensure_package (bool) – If True, attempts to import and reload a common submodule to confirm that imports resolve to the expected code. By default this is False to avoid import side-effects in notebooks.

  • clear_stale (bool) – If True, remove the package and any submodules from sys.modules prior to import checks. This helps ensure subsequent imports come from the updated src/ tree rather than a previously-imported copy.

  • verbose (bool) – If True, prints resolved paths and the resulting sys.path[0] entry.

Returns:

A dictionary containing resolved paths and identifiers with the following keys: - "user": the resolved username (string) - "repo_root": repository root path - "src_dir": the src/ directory path - "pkg_dir": the resolved package directory under src/

Return type:

Dict[str, pathlib.Path]

Raises:

  • ValueError – If user is not provided and cannot be inferred from the environment.

  • FileNotFoundError – If the repository root, src/ directory, or package __init__.py cannot be found at the expected location.

..note:

The function chooses the shared base directory from the first existing candidate in:

/home/jovyan/shared
/home/joyvan/shared

It then forces <repo>/src to be the first entry in sys.path and removes any existing entries that resolve to the same real path, preventing duplicates and reducing the chance of shadowing by other environments.