an.library.root#
Where a package’s library lives on disk: one root per package (ADR 0005 §2, plan §1 decisions 7–8).
The root is resolved in this order, first match wins:
an explicit
root=(tests, power users, a team share);the environment variable
<PKG>_HOME(AN_HOME,CUTAN_HOME) — one switch for a whole shell or CI job;the platform data folder:
$XDG_DATA_HOME/<pkg>whenXDG_DATA_HOMEis set to an absolute path, else~/.local/share/<pkg>on Linux and macOS;%LOCALAPPDATA%\<pkg>on Windows. On macOS this is deliberately~/.local/share, not~/Library/Application Support— the maintainer’s choice, and the one the fleet’s storage rules use.
This is the data-folder half of config2py.get_app_folder, vendored (plan
§1 decision 8): twenty lines are cheaper than a dependency, and the dependency is
taken only if more than this is ever needed.
Under the root, one sub-folder per kind of data, never files at the top:
library/ (records, versions, blobs) and projects/ (agent-made videos).
Resolving a root never creates it and never raises at import; the stores create
their folders on first use.
>>> env = {"AN_HOME": "/srv/an-lib"}
>>> library_root(package="an", environ=env).as_posix()
'/srv/an-lib'
>>> library_root(package="cutan", environ={"XDG_DATA_HOME": "/data"}, platform="linux").as_posix()
'/data/cutan'
Module Attributes
The core package, whose library every genre's search path reads after its own. |
|
The sub-folder of a root that holds the library stores. |
|
The sub-folder of a root that holds agent-made projects (design §7.5). |
Functions
|
The git work tree containing |
|
The override variable for |
|
The data root of |
|
The default directory of the agent-made project |
|
Where agent-made projects go by default: |
Exceptions
Library data, or private material checked out of it, sits inside a git work tree. |
- an.library.root.CORE_PACKAGE: str = 'an'#
The core package, whose library every genre’s search path reads after its own.
- an.library.root.LIBRARY_DIRNAME: str = 'library'#
The sub-folder of a root that holds the library stores.
- exception an.library.root.LibraryLocationWarning[source]#
Bases:
UserWarningLibrary data, or private material checked out of it, sits inside a git work tree.
ADR 0005 decision 2: a library root is never inside a repository. The default guarantees it; an explicit
root,<PKG>_HOMEor a project in a repo can break it, and the library may hold private-study material.
- an.library.root.PROJECTS_DIRNAME: str = 'projects'#
The sub-folder of a root that holds agent-made projects (design §7.5).
- an.library.root.git_worktree_of(path)[source]#
The git work tree containing
path(or its nearest existing ancestor), if any.>>> import tempfile >>> with tempfile.TemporaryDirectory() as d: ... git_worktree_of(d) is None True
- an.library.root.home_env_var(package)[source]#
The override variable for
package’s root.- Return type:
>>> home_env_var("an"), home_env_var("my-genre") ('AN_HOME', 'MY_GENRE_HOME')
- an.library.root.library_root(root=None, *, package='an', environ=None, platform=None)[source]#
The data root of
package— its library and its projects live under it.- Return type:
root: an explicit root; wins over everything package: the package whose root this is (
anfor the core library, agenre’s own name for its library)
environ: the environment to read (default
os.environ; injectable for tests) platform:sys.platformvalue to resolve for (default: this one)>>> library_root("~/x", package="an").name 'x'
- an.library.root.project_dir(project_id, root=None, *, package='an', environ=None)[source]#
The default directory of the agent-made project
project_id(design §7.5).an init <dir>with an explicit directory keeps working anywhere; this is the default for projects an agent makes (an init --id <id>), so they never land in a session’s working folder or a repository.packageis the library package of the genre the video is made in (an.genres.genre_library(); the core’s,an, by default — the core names no genre).- Return type:
>>> project_dir("alice-and-bob", "/lib").as_posix() '/lib/projects/alice-and-bob' >>> project_dir("../escape", "/lib") Traceback (most recent call last): ValueError: ...