Fleche Documentation

Welcome to the Fleche library documentation.

• What is Fleche? A persistent caching library for Python functions — like lru_cache but persisted across runs. The @fleche() decorator wraps functions, generates content-based cache keys via SHA256 hashing, and stores results in configurable backends (file, SQL, memory, HDF5).

• Key features

  • Persistent caching – results survive process restarts

  • Flexible storage backends – filesystem, SQL, in-memory, and HDF5

  • Intelligent hashing – content-based SHA256 keys with type-aware support for numpy, pandas, and custom types

  • Query support – search and inspect cached calls as pandas DataFrames

  • Configurable – TOML-based project and global configuration

  • Thread-safe – ContextVar-based state management

• Get started – see the Installation Guide.

Getting Started

• Installation Guide
  • Normal installation
  • Installing with conda
  • Optional dependencies
  • Installing documentation (optional)
  • Building the docs locally

Using Fleche

• Decorator Helpers
  • Helper Methods
  • Accessing the Original Function
  • Per-Function Static Caching
  • Usage with Decorated Methods
• Lazy Loading
  • What is a LazyCall?
  • Parity with Call
  • LazyArguments
  • When lazy loading helps most
• Querying cached calls
  • Overview
  • Querying from a wrapper
  • Querying with a QueryCall template
  • Behavior details
  • Performance

Digests

• Digests as Arguments
  • Usage
  • Behavior
  • The D Wrapper
• Digest Equivalence
  • Dataclasses and attrs classes

Caches & Storage

• Configuration
  • Reserved Cache Names
  • The [default] section
  • Cache sections
  • Full Configuration Example
• CacheStack
  • Behavior
  • Example
• Security
  • Enabling Security
  • Backward Compatibility
  • Key Rotation and Distributed Trust

Advanced

• Parallel Execution
  • ThreadPoolExecutor
  • ProcessPoolExecutor
  • BoundWrapper — Freezing State for Workers
  • executorlib
  • Future Pass-Through — Caching Async-style Results
  • wrap_executor — Transparent Submit Interception
  • When to prefer each pattern
  • The isolate Flag
  • Quick Reference
  • Known Limitations

Development

• Customizing Digests
  • The __digest__ Method
  • Using add_hook
  • Registering Entry Points
• Developer Guide
  • Per-function metadata: FunctionProfile
  • Extending the destructurer
  • Testing the SQL backend on non-sqlite dialects
• SshCache internals
  • Security model
  • Goals and constraints
  • Process and stream layout
  • Wire protocol
  • Lifecycle
  • Diagnostics: the info RPC
  • Testing strategy
  • Adding a new RPC

Notebooks

• Getting Started with Fleche
• Extra Methods in Fleche
• Fleche Storage Backends
• Secure Storage
• CacheStack
• Concurrent Execution with Fleche

API Reference

• fleche
  • Submodules
  • Attributes
  • Classes
  • Functions
  • Package Contents

Indices and tables

• Index

• Module Index

• Search Page