numistalib Documentation
A Python caching API wrapper for the Numista numismatic database with RFC 9111-compliant HTTP caching, intelligent rate limiting, and resilient retry logic.
Includes an optional command-line interface with rich terminal output and sixel image support.
Features
Core API Features
RFC 9111-Compliant HTTP Caching: Persistent SQLite cache with configurable TTL and LRU eviction
Intelligent Rate Limiting: Transport-level throttling with configurable limits (respects Numista quotas)
Resilient Retry Logic: Exponential backoff with jitter for network failures and rate limit errors
Complete Type Safety: Full Pydantic v2 models with strict validation for all API entities
Sync & Async Support: Both synchronous and asynchronous client implementations
Cache Indicators: Visual feedback (💾/🌐) for cache hits/misses in responses
Optional CLI Features
Rich Terminal UI: Beautiful tables, panels, and formatted output
Sixel Image Support: Display coin images directly in terminal (Kitty, WezTerm, iTerm2, mlterm, foot, yaft)
Flexible Display Modes: Table or panel mode for different output preferences
Command Aliases: Short and long form commands
Getting Started
See the following sections to get started:
User Guide
- Installation
- Quickstart Guide
- Python API Guide
- Overview
- Basic Usage
- § 1 Types Service
- § 2 Catalogues Service
- § 3 Issuers Service
- § 4 Issues Service
- § 5 Mints Service
- § 6 Collections Service
- § 7 Image Search Service
- § 8 Literature Service
- § 9 Prices Service
- § 10 Users Service
- § 11 Async Usage
- § 12 Working with Models
- § 13 Cache Awareness
- § 14 Error Handling
- Complete Example
- Next Steps
- CLI Guide
- Configuration
- Configuration Methods
- § 1 Environment Variables
- § 2 .env File Configuration
- § 3 Programmatic Configuration
- § 4 Configuration Validation
- § 5 Viewing Current Configuration
- § 6 Multi-Environment Setup
- § 7 Docker Configuration
- § 8 Best Practices
- § 9 Troubleshooting
- § 10 Configuration Reference
- Next Steps
- Advanced Usage
Additional Information
About
Built With
This project leverages excellent open-source libraries:
httpx — Modern HTTP client with sync/async support
hishel — RFC 9111-compliant HTTP caching
pydantic — Data validation and settings management
pyrate-limiter — Sophisticated rate limiting
tenacity — Retry logic with exponential backoff
click — CLI framework
rich — Terminal UI and formatting
textual-image — Sixel protocol image display
Legal & Attribution
This project is an unofficial wrapper and is not affiliated with Numista. When using data from Numista, provide appropriate attribution and comply with Numista’s terms:
Respect Numista’s rate limits and any restrictions on caching or redistribution, particularly for pricing data.