Skip to main content

Managing the cache

The SDK creates a cache folder to temporarily store files you're actively working with. You don’t need to re-download files in the cache when you create new sessions or objects.

The cache_manager handles temporary storage of files used by the SDK, reducing redundant downloads and improving performance across sessions. You can:

  • Use the Python API to inspect and maintain the cache
  • Configure cache settings via a configuration file for persistent, version-controlled setups
  • Configure cache settings via environment variables for quick, per-session changes

The SDK automatically searches for this configuration file in the following locations:

  • Linux: $HOME/.config/treble/tsdk_config.toml
  • Windows: %USERPROFILE%\AppData\Local\treble\tsdk\tsdk_config.toml or %USERPROFILE%\AppData\Roaming\treble\tsdk\tsdk_config.toml
  • macOS: $HOME/Library/Application Support/treble/tsdk_config.toml

Basic examples​

Cache manager Python API​

Access the cache_manager through your SDK object to inspect and maintain the cache.

The following code gets cache information:

import treble_sdk as tsdk

# Get current cache directory
print(tsdk.cache_manager.cache_dir)

# Print cache summary (directory, file count, size, etc.)
tsdk.cache_manager.print_cache_info()

The following code runs cache maintenance:

# Run cleanup based on current configuration rules
tsdk.cache_manager.cache_cleanup()

# Remove all files from cache
tsdk.cache_manager.purge_cache()

Cache directory environment variable​

Set the TSDK_CACHE_DIR environment variable to specify a custom cache location.

export TSDK_CACHE_DIR="<path_to_cache>"

Configuration file​

Create a tsdk_config.toml file in the default search location with your preferred settings. The following example shows an example configuration:

[TSDK]
cache_dir = "<path_to_cache>"
max_cache_size_kb = 1024
cache_persistence = "SESSION"
default_log_level = "INFO"
cache_cleanup_max_days_unused = 7
cache_cleanup_max_days_old = 30

Cache configuration​

The cache has the following default settings. Configure these using either environment variables or a configuration file.

Cache directory​

This setting has the following properties:

  • Description: Location of the cache directory.
  • Default: $HOME/.cache/treble (Linux), %USERPROFILE%\AppData\Local\treble\cache (Windows), $HOME/Library/Caches/treble/cache (macOS)
  • Environment variable: TSDK_CACHE_DIR
  • Config key: cache_dir

Maximum cache size​

This setting has the following properties:

  • Description: Maximum data retained in cache; SDK warns if limit exceeded on initialization.
  • Default: 5 GB (5,000,000 KB)
  • Environment variable: TSDK_MAX_CACHE_SIZE_KB
  • Config key: max_cache_size_kb

Cache persistence​

This setting has the following properties:

  • Description: Retention mode: persistent keeps cache between sessions; session clears cache on session end.
  • Default: persistent
  • Environment variable: TSDK_CACHE_PERSISTENCE
  • Config key: cache_persistence

Maximum unused days​

This setting has the following properties:

  • Description: Files not accessed in this many days are removed.
  • Default: 7 days
  • Environment variable: TSDK_CACHE_CLEANUP_MAX_DAYS_UNUSED
  • Config key: cache_cleanup_max_days_unused

Maximum days old​

This setting has the following properties:

  • Description: Files downloaded this many days ago are removed.
  • Default: 30 days
  • Environment variable: TSDK_CACHE_CLEANUP_MAX_DAYS_OLD
  • Config key: cache_cleanup_max_days_old

Config file path​

This setting has the following properties:

  • Description: Path to custom configuration file.
  • Default: None
  • Environment variable: TSDK_CONFIG_PATH
  • Config key: N/A

Default log level​

This setting has the following properties:

  • Description: Controls verbosity of cache_manager log output. INFO for normal operations, WARNING for fallbacks, DEBUG for internal details for debugging purposes. Exceptions are raised instead of ERROR logs.
  • Default: INFO
  • Environment variable: TSDK_DEFAULT_LOG_LEVEL
  • Config key: default_log_level