Caches — store management

DataCaches.Caches is a submodule (public, not exported) that provides a filesystem-style interface for managing the caches living in the DataCaches scratchspace directory (~/.julia/scratchspaces/<DataCaches-UUID>/).

The scratchspace organises stores into subdirectories by kind:

~/.julia/scratchspaces/<DataCaches-UUID>/
  caches/
    user/
      _AUTOCACHE/          ← active_autocache() store
      <name>/              ← DataCache(:name) stores
    module/<uuid>/<key>/   ← scratch_datacache!(uuid, key) stores

The Caches submodule lets you inspect, rename, copy, move, and remove stores without needing to construct or track the underlying path yourself.

Access all functions as DataCaches.Caches.<function>.

Inspection

using DataCaches

# Scratchspace root — the top-level scratchspaces directory for DataCaches
DataCaches.Caches.pwd()
# → "/home/user/.julia/scratchspaces/c1455f2b-6d6f-4f37-b463-919f923708a5"

# Path to a specific user store (directory need not exist yet)
DataCaches.Caches.pwd(:myproject)
# → ".../c1455f2b-.../caches/user/myproject"

# Path to the active autocache store (respects DATACACHES_AUTOCACHE_STORE env var)
DataCaches.Caches.autocachestore()
# → ".../c1455f2b-.../caches/user/_AUTOCACHE"

# Listing of the caches directory root (default)
DataCaches.Caches.ls()
# → [:user, :module]

# List user stores (DataCache(:name))
DataCaches.Caches.ls(:user)
# → [:_AUTOCACHE, :myproject, :taxonomy, :archived_results]

# List module-scoped stores (scratch_datacache!(uuid, key))
DataCaches.Caches.ls(:module)
# → [Symbol("00000000-.../results"), Symbol("aaaabbbb-.../datacache")]

Renaming and copying within the scratchspace

# Create some stores
queries = DataCache(:pbdb_queries)
taxa    = DataCache(:taxonomy)

# Rename
DataCaches.Caches.mv(:pbdb_queries, :paleodb_queries)

# Duplicate
DataCaches.Caches.cp(:taxonomy, :taxonomy_backup)

# Remove
DataCaches.Caches.rm(:taxonomy_backup)
DataCaches.Caches.rm(:nonexistent; force=true)  # no-op if absent

Moving and copying between scratchspace and filesystem

The mv and cp functions accept one Symbol (store name) and one AbstractString (filesystem path) in either order:

# Export — move a named cache out of the scratchspace to a filesystem path
DataCaches.Caches.mv(:paleodb_queries, "/data/exports/paleodb_queries")

# Import — move a filesystem directory into the scratchspace as a named cache
DataCaches.Caches.mv("/data/imports/shared_cache", :shared)

# Export copy (source stays in scratchspace)
DataCaches.Caches.cp(:taxonomy, "/tmp/taxonomy_snapshot")

# Import copy (source stays on filesystem)
DataCaches.Caches.cp("/data/reference/baseline", :baseline)

These round-trip cleanly with importcache! and movecache!: use Caches.mv/Caches.cp when working entirely with named stores, and importcache!/movecache! when working with arbitrary DataCache objects.

Quick-reference table

Function	Description
`Caches.pwd()`	Scratchspace root path
`Caches.pwd(:name)`	Path to a user named store (`caches/user/<name>`)
`Caches.autocachestore()`	Path to the active autocache store (`caches/user/_AUTOCACHE`)
`Caches.ls()`	Returns `Vector{Symbol}` — caches root listing (same as `ls(:root)`)
`Caches.ls(:root)`	Returns `Vector{Symbol}` — top-level caches subdirs (e.g. `[:user, :module]`)
`Caches.ls(:user)`	Returns `Vector{Symbol}` — names of `DataCache(:name)` stores
`Caches.ls(:module)`	Returns `Vector{Symbol}` — `"<uuid>/<key>"` entries for `scratch_datacache!` stores
`Caches.ls!(storetype; io)`	Prints the result of `ls(storetype)` to `io` (default `stdout`), returns `nothing`
`Caches.rm(:name; force=false)`	Remove a user named store
`Caches.mv(:old, :new)`	Rename user store within scratchspace
`Caches.mv(:name, path)`	Move (export) user store to filesystem path
`Caches.mv(path, :name)`	Move (import) filesystem directory into scratchspace
`Caches.cp(:old, :new)`	Copy user store within scratchspace
`Caches.cp(:name, path)`	Copy (export) user store to filesystem path
`Caches.cp(path, :name)`	Copy (import) filesystem directory into scratchspace

API reference

DataCaches.Caches.autocachestore — Method

DataCaches.Caches.autocachestore() → String

Return the absolute path to the active autocache store.

Respects the DATACACHES_AUTOCACHE_STORE environment variable; otherwise returns the path of the _AUTOCACHE store inside <root>/caches/user/.

Unlike active_autocache, this function does not create the directory.

source

DataCaches.Caches.cp — Method

DataCaches.Caches.cp(src::Symbol, dst::Symbol)
DataCaches.Caches.cp(src::Symbol, dst::AbstractString)
DataCaches.Caches.cp(src::AbstractString, dst::Symbol)

Copy a cache store. Three dispatch forms:

cp(src::Symbol, dst::Symbol) — copy depot cache src to dst within the user depot stores.
cp(src::Symbol, dst::AbstractString) — copy named depot cache src to filesystem path dst (export copy from depot).
cp(src::AbstractString, dst::Symbol) — copy a filesystem directory src into the depot as dst (import copy into depot).

Raises an error if the source does not exist or the destination already exists.

source

DataCaches.Caches.ls — Function

DataCaches.Caches.ls(storetype::Symbol = :root) → Vector{Symbol}

List the names of store categories or stores in the DataCaches cache directory.

storetype controls which category is listed:

:root (default) — subdirectory listing of the caches root directory (e.g. [:user, :module]).
:user — named stores created via DataCache(:name), living under <caches>/user/. Returns store names (e.g. [:myproject, :mydata]).
:module — stores created via scratch_datacache!(uuid, key), living under <caches>/module/<uuid>/<key>/. Returns Symbol("<uuid>/<key>") entries.

Returns an empty vector if the relevant directory does not yet exist.

See also ls! for a display-oriented variant that prints to an IO stream.

source

DataCaches.Caches.ls! — Function

DataCaches.Caches.ls!(storetype::Symbol = :root; io::IO = stdout) → nothing

Print the names of store categories or stores in the DataCaches cache directory to io.

Accepts the same storetype argument as ls. Returns nothing.

source

DataCaches.Caches.mv — Method

DataCaches.Caches.mv(src::Symbol, dst::Symbol)
DataCaches.Caches.mv(src::Symbol, dst::AbstractString)
DataCaches.Caches.mv(src::AbstractString, dst::Symbol)

Move a cache store. Three dispatch forms:

mv(src::Symbol, dst::Symbol) — rename src to dst within the user depot stores.
mv(src::Symbol, dst::AbstractString) — move named depot cache src to filesystem path dst (export from depot).
mv(src::AbstractString, dst::Symbol) — move a filesystem directory src into the depot as dst (import into depot).

Raises an error if the source does not exist or the destination already exists.

source

DataCaches.Caches.pwd — Method

DataCaches.Caches.pwd() → String
DataCaches.Caches.pwd(name::Symbol) → String

Return the absolute path to the DataCaches scratchspace root (no argument), or the path to the named user store name within the scratchspace (one argument).

The root is the scratchspaces directory managed by Scratch.jl for DataCaches. User stores live under <root>/caches/user/ and are created via DataCache(:name).

The path is returned whether or not the directory currently exists.

Examples

DataCaches.Caches.pwd()          # "~/.julia/scratchspaces/c1455f2b-.../
DataCaches.Caches.pwd(:mydata)   # "~/.julia/scratchspaces/c1455f2b-.../caches/user/mydata"

source

DataCaches.Caches.rm — Method

DataCaches.Caches.rm(name::Symbol; force=false)

Remove the named local cache store from the depot.

Raises an error if the store does not exist, unless force=true (in which case a missing store is silently ignored).

source