jellycell.paths

The :class:Project value object — discovered project root + validated config.

Every downstream layer takes a :class:Project, not raw paths. This is the only place that resolves filesystem paths, and :meth:Project.resolve rejects paths that escape declared roots (spec §2.1).

Module Contents

Classes

Project

A validated jellycell project.

API

exception jellycell.paths.ProjectNotFoundError

Bases: Exception

Raised when no jellycell.toml is found walking up from a start path.

Initialization

Initialize self. See help(type(self)) for accurate signature.

exception jellycell.paths.PathEscapeError

Bases: Exception

Raised when a requested path would resolve outside the project root.

Initialization

Initialize self. See help(type(self)) for accurate signature.

exception jellycell.paths.UnknownOverrideKeyError

Bases: Exception

Raised when a PEP-723 [tool.jellycell] override uses a disallowed key.

Initialization

Initialize self. See help(type(self)) for accurate signature.

class jellycell.paths.Project

A validated jellycell project.

Holds the root path and parsed :class:Config. Discover one with

Meth:

from_path; construct directly from known root + config otherwise.

root: pathlib.Path

None

config: jellycell.config.Config

None

classmethod from_path(start: pathlib.Path) → jellycell.paths.Project

Walk up from start looking for jellycell.toml.

Raises: ProjectNotFoundError: If no config is found before reaching the FS root.

classmethod from_root(root: pathlib.Path) → jellycell.paths.Project

Load a project directly from a known root directory.

Unlike :meth:from_path, doesn’t walk up — the caller is asserting root is the project root. Used when the user passes --project explicitly.

Raises: ProjectNotFoundError: If root/jellycell.toml doesn’t exist.

resolve(*parts: str | pathlib.Path) → pathlib.Path

Resolve a project-relative path. Rejects escapes.

Args: *parts: Path components to join to :attr:root.

Returns: The absolute resolved path.

Raises: PathEscapeError: If the resolved path is not under :attr:root.

property notebooks_dir: pathlib.Path

Absolute path to the notebooks root.

property data_dir: pathlib.Path

Absolute path to the data root.

property artifacts_dir: pathlib.Path

Absolute path to the artifacts root.

property site_dir: pathlib.Path

Absolute path to the static-site root.

Where jellycell render writes HTML + _assets/, and where jellycell export ipynb/md drop their derived files. The live viewer reads this directory (and shares the same _assets/ mount with the static render so relative image hrefs resolve cleanly in both modes).

property manuscripts_dir: pathlib.Path

Absolute path to the manuscripts root.

property cache_dir: pathlib.Path

Absolute path to the cache root (usually .jellycell/cache).

with_overrides(overrides: dict[str, Any]) → jellycell.paths.Project

Return a copy with selected config fields overridden at file scope.

Consumes the parsed [tool.jellycell] table from a notebook’s PEP-723 block. Unknown keys raise :class:UnknownOverrideKeyError so typos don’t silently no-op.

Supported keys (spec §7): project.name, run.kernel, run.timeout_seconds. Flat keys (timeout_seconds) are also accepted and dispatched to their natural section for ergonomics.

property declared_roots: list[pathlib.Path]

All project-declared paths. Used by the lint layer for write guards.