Configuration

Speasy can be configured through the config module, environment variables, or by editing an INI file directly. For any entry, the environment variable (named SPEASY_<SECTION>_<ENTRY>) takes precedence over the config file, which takes precedence over the built-in default.

The configuration file is an INI file located in your platform’s user config directory: ~/.config/speasy/config.ini on Linux, ~/Library/Application Support/speasy/config.ini on macOS, %LOCALAPPDATA%\LPP\speasy\config.ini on Windows (the LPP author segment only appears on Windows). You can also find the exact path programmatically:

>>> import speasy as spz
>>> print(spz.config.SPEASY_CONFIG_FILE)

To display the current configuration:

>>> import speasy as spz
>>> spz.config.show()

Core section

Disabling data providers

Sometimes you may want to disable some data providers either to speed up Speasy import or because you don’t need them. This can be done by adding the provider name to the disabled_providers list in the configuration file. Valid names are amda, csa, cda (alias cdaweb), ssc (alias sscweb), archive (alias generic_archive), uiowaephtool (alias UiowaEphTool) and cdpp3dview (alias 3DView).

The value you set replaces the default rather than adding to it: the default is empty (every provider enabled), so setting disabled_providers = amda disables only AMDA.

For example, to disable AMDA and CDAWeb, add the following to the configuration file:

[CORE]
disabled_providers = amda,cdaweb

Or from Python:

>>> import speasy as spz
>>> spz.config.core.disabled_providers.set('amda,cdaweb')

Other core entries

Entry / env var	Default	Purpose
`http_rewrite_rules` / `SPEASY_CORE_HTTP_REWRITE_RULES`	`{"https://cdaweb.gsfc.nasa.gov/pub/": "https://sciqlop.lpp.polytechnique.fr/cdaweb-data/pub/"}`	A Python dict literal of URL prefixes to rewrite before sending requests (e.g. `{"http://example.com": "http://localhost:8000"}`).
`http_user_agent` / `SPEASY_CORE_HTTP_USER_AGENT`	`""`	User agent string sent with HTTP requests. Empty uses Speasy’s default user agent.
`urlib_pool_size` / `SPEASY_CORE_URLIB_POOL_SIZE`	`10`	Maximum number of connections to keep in the underlying `urllib3` connection pool.
`urlib_num_pools` / `SPEASY_CORE_URLIB_NUM_POOLS`	`10`	Maximum number of connection pools kept by `urllib3`.
`user_codecs_extra_dirs` / `SPEASY_CORE_USER_CODECS_EXTRA_DIRS`	(empty)	Comma-separated list of extra directories to scan for user-defined codecs.

Proxy section

Speasy can go through the SciQLop community proxy, a caching server shared by all Speasy users that avoids redundant downloads of the same data. This is unrelated to a corporate/network HTTP proxy — see Connecting behind an HTTP proxy below for that.

Entry / env var	Default	Purpose
`enabled` / `SPEASY_PROXY_ENABLED`	`True`	Whether to use the Speasy caching proxy at all.
`url` / `SPEASY_PROXY_URL`	`https://sciqlop.lpp.polytechnique.fr/cache`	URL of the Speasy caching proxy server.

[PROXY]
enabled = true
url = https://sciqlop.lpp.polytechnique.fr/cache

Or from Python:

>>> import speasy as spz
>>> spz.config.proxy.enabled.set(True)
>>> spz.config.proxy.url.set('https://sciqlop.lpp.polytechnique.fr/cache')

Cache section

Entry / env var	Default	Purpose
`path` / `SPEASY_CACHE_PATH`	platform user cache dir	Where Speasy stores the local disk cache.
`size` / `SPEASY_CACHE_SIZE`	`20e9` (20 GB)	Maximum cache size in bytes.
`migrate_by_moving` / `SPEASY_CACHE_MIGRATE_BY_MOVING`	`false`	Trades the migration rollback backup for lower peak disk usage — see Migrating with limited disk space below.

The default cache path follows your platform’s user cache directory: ~/.cache/speasy on Linux, ~/Library/Caches/speasy on macOS, %LOCALAPPDATA%\LPP\speasy\Cache on Windows (the LPP author segment only appears on Windows). Read the current value with spz.config.cache.path.get().

[CACHE]
path = /path/to/cache
size = 1e9

Or from Python:

>>> import speasy as spz
>>> spz.config.cache.path.set('/path/to/cache')
>>> spz.config.cache.size.set(1e9)

Inspecting and clearing the cache

>>> from speasy.core.cache import cache_len, cache_disk_size, entries, drop_item, drop_matching_entries
>>> cache_len()
130169
>>> cache_disk_size()
78207505517
>>> list(entries())[:1]
['UiowaEphTool_orbits/Callisto_Cassini_Co-rotational/2010-01-01T00:00:00+00:00']
>>> drop_item(list(entries())[0])
>>> drop_matching_entries(".*amda.*")
>>> # clears every entry
>>> drop_matching_entries(".*")

If your data still looks stale after clearing the cache, remember the local cache is only one layer: the Speasy proxy may also be serving a cached response, and provider-specific caches (e.g. AMDA’s user_cache_retention) apply on top.

Migrating an older cache

Speasy’s local disk cache is backed by pysciqlop-cache, a native cache library, replacing the pure-Python diskcache package used in older Speasy versions.

If you had already used an older Speasy version, the first import of the new version detects your existing diskcache-format cache and migrates it automatically:

This is a one-time operation and can take a few minutes for a large cache; subsequent imports are unaffected.
Your old cache is renamed to <cache path>.diskcache.backup and kept alongside the new one. Speasy reminds you with a warning on every import for as long as a backup still exists.
Speasy still depends on diskcache precisely so this migration can run out of the box, with no extra install step needed. In the unlikely case it’s unavailable in your environment (e.g. a custom install with --no-deps), Speasy logs a warning and starts a fresh cache instead of migrating; your old cache is left untouched on disk and nothing is lost.
If you switch back to a pre-1.8 Speasy version after already migrating (which doesn’t know about sciqlop-cache, so it writes its own fresh diskcache alongside the live cache) and fetch new data, the next 1.8+ import detects and merges those new entries into the live cache automatically — you won’t lose anything by switching back and forth.

Once you’ve confirmed the new cache works, delete the backup(s) with:

>>> from speasy.core.cache import migration_backups, delete_migration_backups
>>> migration_backups()
['/home/user/.cache/speasy/Cache.diskcache.backup', '/home/user/.local/share/speasy/index.diskcache.backup']
>>> delete_migration_backups()
['/home/user/.cache/speasy/Cache.diskcache.backup', '/home/user/.local/share/speasy/index.diskcache.backup']

delete_migration_backups() only ever removes these .diskcache.backup directories, never a live cache.

Note

Speasy has no compiled pysciqlop-cache build for WASM/Pyodide (e.g. JupyterLite); on that platform caching is transparently disabled (a no-op cache) rather than causing an import error.

Migrating with limited disk space

By default, migration is a copy: your old cache is renamed to <cache path>.diskcache.backup and kept fully intact while every entry is also written into the new cache — so for a short window, both copies exist on disk at once (roughly double the cache’s size in free space needed).

If disk space is tight, set migrate_by_moving to move instead: each entry is deleted from the old cache as soon as it’s written to the new one, so at most one entry’s worth of duplication ever exists at a time.

[CACHE]
migrate_by_moving = true

Warning

Moving trades away the rollback safety net: once an entry is moved, it’s gone from the old cache, so there’s nothing left to fall back to if the new cache turns out to have a problem afterwards. Prefer the default (copy) unless you’re genuinely short on disk space.

Index section

Entry / env var	Default	Purpose
`path` / `SPEASY_INDEX_PATH`	platform user data dir + `/index`	Where Speasy stores its product index database.

CDAWeb section

Entry / env var	Default	Purpose
`inventory_data_path` / `SPEASY_CDAWEB_INVENTORY_DATA_PATH`	platform user data dir + `/cda_inventory`	Where Speasy caches the CDAWeb inventory.
`preferred_access_method` / `SPEASY_CDAWEB_PREFERRED_ACCESS_METHOD`	`BEST`	`API`, `FILE`, or `BEST`; see Coordinated Data Analysis Web (CDAWeb) for what each one means.

AMDA section

Entry / env var	Default	Purpose
`username` / `SPEASY_AMDA_USERNAME`	`""`	Your AMDA username. Once set (together with `password`), you can access your private AMDA products.
`password` / `SPEASY_AMDA_PASSWORD`	`""`	Your AMDA password.
`user_cache_retention` / `SPEASY_AMDA_USER_CACHE_RETENTION`	`900` (15 minutes)	Cache retention, in seconds, for AMDA requests such as `list_catalogs`; see Automated Multi-Dataset Analysis (AMDA) for when a change takes effect.
`max_chunk_size_days` / `SPEASY_AMDA_MAX_CHUNK_SIZE_DAYS`	`10`	Maximum request duration in days; longer requests are automatically split into smaller ones.
`entry_point` / `SPEASY_AMDA_ENTRY_POINT`	`https://amda.irap.omp.eu`	Base URL of the AMDA web service.
`output_format` / `SPEASY_AMDA_OUTPUT_FORMAT`	`CDF_ISTP`	File format requested from AMDA. Only `CDF_ISTP` is supported today.

For example, from Python:

>>> import speasy as spz
>>> spz.config.amda.username.set('my_amda_username')
>>> spz.config.amda.password.set('my_amda_password')

Archive section

Entry / env var	Default	Purpose
`extra_inventory_lookup_dirs` / `SPEASY_ARCHIVE_EXTRA_INVENTORY_LOOKUP_DIRS`	(empty)	Comma-separated list of extra directories the Direct Archive provider scans for YAML inventory files, beyond its default user directory. See Direct archive access.

Inventories section

Entry / env var	Default	Purpose
`cache_retention_days` / `SPEASY_INVENTORIES_CACHE_RETENTION_DAYS`	`2`	Maximum age, in days, Speasy keeps a provider’s inventory cached before re-fetching it.

Connecting behind an HTTP proxy

If your network requires going through a forward HTTP proxy to reach the internet, Speasy honors the standard HTTP_PROXY environment variable for its HTTP traffic. Note that HTTPS_PROXY is not currently read — set HTTP_PROXY even for HTTPS requests. This is unrelated to the Speasy caching proxy described in the Proxy section above.