TradeChart 2.1.2__tar.gz → 2.2.1__tar.gz

{tradechart-2.1.2 → tradechart-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TradeChart
-Version: 2.1.2
+Version: 2.2.1
 Summary: Production-quality financial chart generator — candlestick, line, area, OHLC, Heikin-Ashi, performance heatmaps, and sector group charts.
 Author-email: "TRADELY.DEV" <dev@tradely.dev>
 License: Apache-2.0
@@ -45,11 +45,11 @@ Requires-Dist: build>=1.0; extra == "dev"
 Requires-Dist: twine>=5.0; extra == "dev"
 Dynamic: license-file
 
-# TradeChart — Library Edition v2.1.2
+# TradeChart — Library Edition v2.2.1
 
 **Python → Financial Charts**  
 Generate production-quality candlestick, line, area, OHLC, Heikin-Ashi, and performance heatmap charts from code.  
-Automatic multi-provider data fetching · 7 technical indicators · 3 themes · PNG/SVG/PDF output · 14 built-in sector groups.
+Automatic multi-provider data fetching · persistent disk store · 7 technical indicators · 3 themes · PNG/SVG/PDF output · 14 built-in sector groups.
 
 ---
 
@@ -84,6 +84,93 @@ tc.chart("AAPL", "1mo", "candle", indicators=["sma", "bollinger"])
 
 ---
 
+## Persistent Data Store
+
+`tc.store()` adds a two-level cache on top of the existing in-memory TTL cache: data fetched from any provider is written to a `tradechart_FetchData/` folder and reloaded automatically in future sessions, eliminating redundant network requests.
+
+### Set the store location
+
+Call `tc.store()` once with a filesystem path. The folder `tradechart_FetchData/` is created there automatically.
+
+```python
+import tradechart as tc
+
+tc.store("/data/myproject")      # absolute path
+tc.store(".")                    # current working directory
+tc.store("~/market_data")        # tilde expansion supported
+```
+
+### Pre-fetch tickers and groups
+
+After setting the path, call `tc.store()` again on subsequent lines listing any combination of individual ticker symbols, named sector group keys, or plain lists. An optional duration string as the last argument controls the fetch window (defaults to `"1mo"`).
+
+```python
+tc.store("AAPL")                           # single ticker, default duration (1mo)
+tc.store("AAPL", "MSFT", "NVDA", "3mo")   # three tickers for 3 months
+tc.store("mag7", "6mo")                    # named group — fetches all 7 tickers
+tc.store("tech", "finance", "1y")          # two named groups for 1 year
+tc.store(tc.SECTOR_GROUPS["crypto"], "3mo") # list passed directly
+```
+
+Any valid `SECTOR_GROUPS` key (`"mag7"`, `"tech"`, `"finance"`, `"energy"`, …) is expanded to its full ticker list automatically.
+
+### How it works
+
+Once a store path is configured, every call to `chart()`, `data()`, `export()`, `compare()`, or `heatmap()` uses a three-level lookup before touching the network:
+
+1. **In-memory cache** — sub-millisecond, TTL-based (existing behaviour).
+2. **Disk store (fresh)** — if the stored file is younger than the bar-resolution threshold, it is served as-is. No network call.
+3. **Disk store (stale) + live fetch** — if the stored file is older than the threshold, the library fetches the current window from a live provider to get the missing bars, then **merges** those new rows on top of the stored history. Historical bars are never discarded or re-requested. The merged result is written back to disk and served.
+
+The staleness threshold matches the resolution of the data so charts are never more than one bar behind:
+
+| Duration | Bar resolution | Refreshes after |
+|---|---|---|
+| `"1d"`, `"5d"` | 5 / 15-min bars | 4 hours |
+| `"1mo"`, `"3mo"`, `"6mo"` | Daily bars | 24 hours |
+| `"1y"`, `"2y"`, `"5y"` | Weekly bars | 7 days |
+| `"10y"`, `"max"` | Monthly bars | 30 days |
+
+```python
+tc.store("/data/myproject")
+tc.store("AAPL", "MSFT", "mag7", "3mo")   # fetch once, write to disk
+
+# Later — same session or a completely new one:
+tc.chart("AAPL", "3mo")                   # served from disk, no network call
+tc.data("MSFT", "3mo")                    # same
+
+# After 24 hours (daily bars): only the new day's bar is fetched and merged
+# in — the months of stored history are kept and reused as-is
+tc.chart("AAPL", "3mo")                   # delta fetch + merge, then cached
+```
+
+### Clearing stored data
+
+```python
+tc.clear_cache()           # flush in-memory cache only (default)
+tc.clear_cache(disk=True)  # also delete all CSV files in tradechart_FetchData/
+```
+
+### Store folder layout
+
+```
+/data/myproject/
+└── tradechart_FetchData/
+    ├── AAPL_3mo.csv
+    ├── MSFT_3mo.csv
+    ├── NVDA_3mo.csv
+    └── ...
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `*args` | `str \| list \| tuple` | A single path string **or** any mix of ticker symbols, named sector group keys, and/or lists — optionally ending with a duration string. |
+| `duration` | `str` (keyword) | Fallback duration when none is provided in `*args`. Default `"1mo"`. |
+
+**Returns:** the `tradechart_FetchData/` `Path` when setting the store; `None` when pre-fetching.
+
+---
+
 ## Ticker Groups — Averaged Series
 
 `tc.chart()`, `tc.data()`, and `tc.export()` accept a **list or tuple of ticker symbols** in addition to a single string. When a group is supplied the library:
@@ -137,12 +224,14 @@ If one or more tickers in the group fail to fetch data, they are **skipped with
 | `tc.theme(name)` | Set chart colour theme |
 | `tc.watermark(enabled)` | Toggle the TRADELY logo watermark |
 | `tc.config(**kwargs)` | Batch-set multiple global options at once |
+| `tc.store(path)` | Set persistent data-store directory |
+| `tc.store(ticker, ...)` | Pre-fetch and persist tickers / groups |
 | `tc.chart(...)` | Fetch data and render a chart image |
 | `tc.compare(...)` | Overlay multiple tickers on one chart |
 | `tc.heatmap(...)` | Render a performance heatmap for a ticker group |
 | `tc.data(...)` | Fetch raw OHLCV data as a DataFrame |
 | `tc.export(...)` | Export market data to CSV / JSON / XLSX |
-| `tc.clear_cache()` | Flush the in-memory data cache |
+| `tc.clear_cache(disk=False)` | Flush in-memory cache; optionally wipe disk store |
 | `tc.SECTOR_GROUPS` | Dict of 14 pre-defined ticker lists (sectors, indices, crypto, …) |
 
 ---
@@ -252,7 +341,7 @@ Tile sizes use a **squarified treemap** algorithm to minimise wasted space while
 
 ## `tc.SECTOR_GROUPS` — Pre-defined Ticker Lists
 
-A dictionary of curated ticker groups ready to pass into `tc.heatmap()`, `tc.compare()`, `tc.chart()`, or `tc.export()`.
+A dictionary of curated ticker groups ready to pass into `tc.heatmap()`, `tc.compare()`, `tc.chart()`, `tc.store()`, or `tc.export()`.
 
 ```python
 import tradechart as tc
@@ -417,10 +506,15 @@ The TRADELY logo is stamped in the bottom-left corner of every chart by default.
 ## `tc.clear_cache()` — Flush Data Cache
 
 ```python
-tc.clear_cache()
+tc.clear_cache()            # flush in-memory cache only
+tc.clear_cache(disk=True)   # also wipe all CSVs in tradechart_FetchData/
 ```
 
-Clears all in-memory cached market data, forcing the next fetch to go to the network. Useful after a TTL has not yet expired but you need fresh data (e.g. during live market hours).
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `disk` | `bool` | `False` | When `True`, deletes all CSV files in the disk store (the folder is kept). Has no effect if no store path has been set. |
+
+Clears in-memory cached market data, forcing the next fetch to check the disk store (or go to the network if no store is configured). Useful during live market hours when TTL has not yet expired but you need a fresh quote.
 
 ---
 
@@ -475,18 +569,22 @@ TradeChart tries providers in priority order and falls back automatically on fai
 
 | Priority | Provider | Requires | Notes |
 |---|---|---|---|
-| 1 | **yfinance** | Included by default | Primary source. Covers stocks, ETFs, indices, crypto, forex. |
+| 0 | **Disk store** | `tc.store(path)` called once | Served from local CSV when fresh. When stale, only the missing bars are fetched from a live provider and merged on top — historical rows are never re-requested. |
+| 1 | **yfinance** | Included by default | Primary live source. Covers stocks, ETFs, indices, crypto, forex. |
 | 2 | **TradingView** | `pip install TradeChart[tradingview]` | Tried if yfinance returns empty or fails. Attempts multiple exchanges automatically (`NASDAQ`, `NYSE`, `AMEX`, `CRYPTO`, `FX`). |
 | 3 | **Stooq** | Nothing — free CSV endpoint | Final fallback. No API key required. Duration mapped to a rolling date range. |
 
-If all three providers fail, a `DataFetchError` is raised with a list of each provider's error message.
+If all live providers fail and no disk data exists, a `DataFetchError` is raised with a list of each provider's error message.
 
 ---
 
 ## Notes
 
-**Caching**  
-Fetched data is cached in-memory for `cache_ttl` seconds (default 300 s / 5 minutes). All subsequent calls with the same ticker and duration within that window are served from cache. Call `tc.clear_cache()` to force a re-fetch, or set `tc.config(cache_ttl=0)` to disable caching entirely.
+**Persistent disk store**  
+When `tc.store()` is configured, every successful live fetch is written to `tradechart_FetchData/` as a CSV file. On subsequent requests the library checks whether the stored data is fresh enough (based on bar resolution — 24 hours for daily bars, 4 hours for intraday, etc.). If fresh, it is served directly with no network call. If stale, only the most recent bars are fetched from a live provider and merged on top of the stored history — historical rows are never discarded or re-fetched. Use `tc.clear_cache(disk=True)` to wipe stored files and force a full re-fetch.
+
+**In-memory caching**  
+Fetched data is also cached in-memory for `cache_ttl` seconds (default 300 s / 5 minutes). All subsequent calls with the same ticker and duration within that window are served from the memory cache. Call `tc.clear_cache()` to force re-evaluation (disk store is still checked before going to the network). Set `tc.config(cache_ttl=0)` to disable the memory cache entirely.
 
 **File collision handling**  
 By default (`overwrite=False`), TradeChart appends a counter to avoid overwriting existing files: `chart.png` → `chart_1.png` → `chart_2.png`. Set `tc.config(overwrite=True)` to overwrite silently.
@@ -518,7 +616,7 @@ All TradeChart exceptions inherit from `TradeChartError`.
 | `InvalidTickerError` | The ticker string fails validation (too long, invalid characters) |
 | `RenderError` | Chart rendering fails (e.g. empty dataset after cleaning) |
 | `OutputError` | The chart cannot be saved (e.g. permission denied) |
-| `ConfigError` | An unknown key is passed to `tc.config()` |
+| `ConfigError` | An unknown key is passed to `tc.config()`, or `tc.store()` is called with tickers before a path is set |
 
 ```python
 import tradechart as tc

{tradechart-2.1.2 → tradechart-2.2.1}/README.md

@@ -1,8 +1,8 @@
-# TradeChart — Library Edition v2.1.2
+# TradeChart — Library Edition v2.2.1
 
 **Python → Financial Charts**  
 Generate production-quality candlestick, line, area, OHLC, Heikin-Ashi, and performance heatmap charts from code.  
-Automatic multi-provider data fetching · 7 technical indicators · 3 themes · PNG/SVG/PDF output · 14 built-in sector groups.
+Automatic multi-provider data fetching · persistent disk store · 7 technical indicators · 3 themes · PNG/SVG/PDF output · 14 built-in sector groups.
 
 ---
 
@@ -37,6 +37,93 @@ tc.chart("AAPL", "1mo", "candle", indicators=["sma", "bollinger"])
 
 ---
 
+## Persistent Data Store
+
+`tc.store()` adds a two-level cache on top of the existing in-memory TTL cache: data fetched from any provider is written to a `tradechart_FetchData/` folder and reloaded automatically in future sessions, eliminating redundant network requests.
+
+### Set the store location
+
+Call `tc.store()` once with a filesystem path. The folder `tradechart_FetchData/` is created there automatically.
+
+```python
+import tradechart as tc
+
+tc.store("/data/myproject")      # absolute path
+tc.store(".")                    # current working directory
+tc.store("~/market_data")        # tilde expansion supported
+```
+
+### Pre-fetch tickers and groups
+
+After setting the path, call `tc.store()` again on subsequent lines listing any combination of individual ticker symbols, named sector group keys, or plain lists. An optional duration string as the last argument controls the fetch window (defaults to `"1mo"`).
+
+```python
+tc.store("AAPL")                           # single ticker, default duration (1mo)
+tc.store("AAPL", "MSFT", "NVDA", "3mo")   # three tickers for 3 months
+tc.store("mag7", "6mo")                    # named group — fetches all 7 tickers
+tc.store("tech", "finance", "1y")          # two named groups for 1 year
+tc.store(tc.SECTOR_GROUPS["crypto"], "3mo") # list passed directly
+```
+
+Any valid `SECTOR_GROUPS` key (`"mag7"`, `"tech"`, `"finance"`, `"energy"`, …) is expanded to its full ticker list automatically.
+
+### How it works
+
+Once a store path is configured, every call to `chart()`, `data()`, `export()`, `compare()`, or `heatmap()` uses a three-level lookup before touching the network:
+
+1. **In-memory cache** — sub-millisecond, TTL-based (existing behaviour).
+2. **Disk store (fresh)** — if the stored file is younger than the bar-resolution threshold, it is served as-is. No network call.
+3. **Disk store (stale) + live fetch** — if the stored file is older than the threshold, the library fetches the current window from a live provider to get the missing bars, then **merges** those new rows on top of the stored history. Historical bars are never discarded or re-requested. The merged result is written back to disk and served.
+
+The staleness threshold matches the resolution of the data so charts are never more than one bar behind:
+
+| Duration | Bar resolution | Refreshes after |
+|---|---|---|
+| `"1d"`, `"5d"` | 5 / 15-min bars | 4 hours |
+| `"1mo"`, `"3mo"`, `"6mo"` | Daily bars | 24 hours |
+| `"1y"`, `"2y"`, `"5y"` | Weekly bars | 7 days |
+| `"10y"`, `"max"` | Monthly bars | 30 days |
+
+```python
+tc.store("/data/myproject")
+tc.store("AAPL", "MSFT", "mag7", "3mo")   # fetch once, write to disk
+
+# Later — same session or a completely new one:
+tc.chart("AAPL", "3mo")                   # served from disk, no network call
+tc.data("MSFT", "3mo")                    # same
+
+# After 24 hours (daily bars): only the new day's bar is fetched and merged
+# in — the months of stored history are kept and reused as-is
+tc.chart("AAPL", "3mo")                   # delta fetch + merge, then cached
+```
+
+### Clearing stored data
+
+```python
+tc.clear_cache()           # flush in-memory cache only (default)
+tc.clear_cache(disk=True)  # also delete all CSV files in tradechart_FetchData/
+```
+
+### Store folder layout
+
+```
+/data/myproject/
+└── tradechart_FetchData/
+    ├── AAPL_3mo.csv
+    ├── MSFT_3mo.csv
+    ├── NVDA_3mo.csv
+    └── ...
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `*args` | `str \| list \| tuple` | A single path string **or** any mix of ticker symbols, named sector group keys, and/or lists — optionally ending with a duration string. |
+| `duration` | `str` (keyword) | Fallback duration when none is provided in `*args`. Default `"1mo"`. |
+
+**Returns:** the `tradechart_FetchData/` `Path` when setting the store; `None` when pre-fetching.
+
+---
+
 ## Ticker Groups — Averaged Series
 
 `tc.chart()`, `tc.data()`, and `tc.export()` accept a **list or tuple of ticker symbols** in addition to a single string. When a group is supplied the library:
@@ -90,12 +177,14 @@ If one or more tickers in the group fail to fetch data, they are **skipped with
 | `tc.theme(name)` | Set chart colour theme |
 | `tc.watermark(enabled)` | Toggle the TRADELY logo watermark |
 | `tc.config(**kwargs)` | Batch-set multiple global options at once |
+| `tc.store(path)` | Set persistent data-store directory |
+| `tc.store(ticker, ...)` | Pre-fetch and persist tickers / groups |
 | `tc.chart(...)` | Fetch data and render a chart image |
 | `tc.compare(...)` | Overlay multiple tickers on one chart |
 | `tc.heatmap(...)` | Render a performance heatmap for a ticker group |
 | `tc.data(...)` | Fetch raw OHLCV data as a DataFrame |
 | `tc.export(...)` | Export market data to CSV / JSON / XLSX |
-| `tc.clear_cache()` | Flush the in-memory data cache |
+| `tc.clear_cache(disk=False)` | Flush in-memory cache; optionally wipe disk store |
 | `tc.SECTOR_GROUPS` | Dict of 14 pre-defined ticker lists (sectors, indices, crypto, …) |
 
 ---
@@ -205,7 +294,7 @@ Tile sizes use a **squarified treemap** algorithm to minimise wasted space while
 
 ## `tc.SECTOR_GROUPS` — Pre-defined Ticker Lists
 
-A dictionary of curated ticker groups ready to pass into `tc.heatmap()`, `tc.compare()`, `tc.chart()`, or `tc.export()`.
+A dictionary of curated ticker groups ready to pass into `tc.heatmap()`, `tc.compare()`, `tc.chart()`, `tc.store()`, or `tc.export()`.
 
 ```python
 import tradechart as tc
@@ -370,10 +459,15 @@ The TRADELY logo is stamped in the bottom-left corner of every chart by default.
 ## `tc.clear_cache()` — Flush Data Cache
 
 ```python
-tc.clear_cache()
+tc.clear_cache()            # flush in-memory cache only
+tc.clear_cache(disk=True)   # also wipe all CSVs in tradechart_FetchData/
 ```
 
-Clears all in-memory cached market data, forcing the next fetch to go to the network. Useful after a TTL has not yet expired but you need fresh data (e.g. during live market hours).
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `disk` | `bool` | `False` | When `True`, deletes all CSV files in the disk store (the folder is kept). Has no effect if no store path has been set. |
+
+Clears in-memory cached market data, forcing the next fetch to check the disk store (or go to the network if no store is configured). Useful during live market hours when TTL has not yet expired but you need a fresh quote.
 
 ---
 
@@ -428,18 +522,22 @@ TradeChart tries providers in priority order and falls back automatically on fai
 
 | Priority | Provider | Requires | Notes |
 |---|---|---|---|
-| 1 | **yfinance** | Included by default | Primary source. Covers stocks, ETFs, indices, crypto, forex. |
+| 0 | **Disk store** | `tc.store(path)` called once | Served from local CSV when fresh. When stale, only the missing bars are fetched from a live provider and merged on top — historical rows are never re-requested. |
+| 1 | **yfinance** | Included by default | Primary live source. Covers stocks, ETFs, indices, crypto, forex. |
 | 2 | **TradingView** | `pip install TradeChart[tradingview]` | Tried if yfinance returns empty or fails. Attempts multiple exchanges automatically (`NASDAQ`, `NYSE`, `AMEX`, `CRYPTO`, `FX`). |
 | 3 | **Stooq** | Nothing — free CSV endpoint | Final fallback. No API key required. Duration mapped to a rolling date range. |
 
-If all three providers fail, a `DataFetchError` is raised with a list of each provider's error message.
+If all live providers fail and no disk data exists, a `DataFetchError` is raised with a list of each provider's error message.
 
 ---
 
 ## Notes
 
-**Caching**  
-Fetched data is cached in-memory for `cache_ttl` seconds (default 300 s / 5 minutes). All subsequent calls with the same ticker and duration within that window are served from cache. Call `tc.clear_cache()` to force a re-fetch, or set `tc.config(cache_ttl=0)` to disable caching entirely.
+**Persistent disk store**  
+When `tc.store()` is configured, every successful live fetch is written to `tradechart_FetchData/` as a CSV file. On subsequent requests the library checks whether the stored data is fresh enough (based on bar resolution — 24 hours for daily bars, 4 hours for intraday, etc.). If fresh, it is served directly with no network call. If stale, only the most recent bars are fetched from a live provider and merged on top of the stored history — historical rows are never discarded or re-fetched. Use `tc.clear_cache(disk=True)` to wipe stored files and force a full re-fetch.
+
+**In-memory caching**  
+Fetched data is also cached in-memory for `cache_ttl` seconds (default 300 s / 5 minutes). All subsequent calls with the same ticker and duration within that window are served from the memory cache. Call `tc.clear_cache()` to force re-evaluation (disk store is still checked before going to the network). Set `tc.config(cache_ttl=0)` to disable the memory cache entirely.
 
 **File collision handling**  
 By default (`overwrite=False`), TradeChart appends a counter to avoid overwriting existing files: `chart.png` → `chart_1.png` → `chart_2.png`. Set `tc.config(overwrite=True)` to overwrite silently.
@@ -471,7 +569,7 @@ All TradeChart exceptions inherit from `TradeChartError`.
 | `InvalidTickerError` | The ticker string fails validation (too long, invalid characters) |
 | `RenderError` | Chart rendering fails (e.g. empty dataset after cleaning) |
 | `OutputError` | The chart cannot be saved (e.g. permission denied) |
-| `ConfigError` | An unknown key is passed to `tc.config()` |
+| `ConfigError` | An unknown key is passed to `tc.config()`, or `tc.store()` is called with tickers before a path is set |
 
 ```python
 import tradechart as tc

{tradechart-2.1.2 → tradechart-2.2.1}/TradeChart.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TradeChart
-Version: 2.1.2
+Version: 2.2.1
 Summary: Production-quality financial chart generator — candlestick, line, area, OHLC, Heikin-Ashi, performance heatmaps, and sector group charts.
 Author-email: "TRADELY.DEV" <dev@tradely.dev>
 License: Apache-2.0
@@ -45,11 +45,11 @@ Requires-Dist: build>=1.0; extra == "dev"
 Requires-Dist: twine>=5.0; extra == "dev"
 Dynamic: license-file
 
-# TradeChart — Library Edition v2.1.2
+# TradeChart — Library Edition v2.2.1
 
 **Python → Financial Charts**  
 Generate production-quality candlestick, line, area, OHLC, Heikin-Ashi, and performance heatmap charts from code.  
-Automatic multi-provider data fetching · 7 technical indicators · 3 themes · PNG/SVG/PDF output · 14 built-in sector groups.
+Automatic multi-provider data fetching · persistent disk store · 7 technical indicators · 3 themes · PNG/SVG/PDF output · 14 built-in sector groups.
 
 ---
 
@@ -84,6 +84,93 @@ tc.chart("AAPL", "1mo", "candle", indicators=["sma", "bollinger"])
 
 ---
 
+## Persistent Data Store
+
+`tc.store()` adds a two-level cache on top of the existing in-memory TTL cache: data fetched from any provider is written to a `tradechart_FetchData/` folder and reloaded automatically in future sessions, eliminating redundant network requests.
+
+### Set the store location
+
+Call `tc.store()` once with a filesystem path. The folder `tradechart_FetchData/` is created there automatically.
+
+```python
+import tradechart as tc
+
+tc.store("/data/myproject")      # absolute path
+tc.store(".")                    # current working directory
+tc.store("~/market_data")        # tilde expansion supported
+```
+
+### Pre-fetch tickers and groups
+
+After setting the path, call `tc.store()` again on subsequent lines listing any combination of individual ticker symbols, named sector group keys, or plain lists. An optional duration string as the last argument controls the fetch window (defaults to `"1mo"`).
+
+```python
+tc.store("AAPL")                           # single ticker, default duration (1mo)
+tc.store("AAPL", "MSFT", "NVDA", "3mo")   # three tickers for 3 months
+tc.store("mag7", "6mo")                    # named group — fetches all 7 tickers
+tc.store("tech", "finance", "1y")          # two named groups for 1 year
+tc.store(tc.SECTOR_GROUPS["crypto"], "3mo") # list passed directly
+```
+
+Any valid `SECTOR_GROUPS` key (`"mag7"`, `"tech"`, `"finance"`, `"energy"`, …) is expanded to its full ticker list automatically.
+
+### How it works
+
+Once a store path is configured, every call to `chart()`, `data()`, `export()`, `compare()`, or `heatmap()` uses a three-level lookup before touching the network:
+
+1. **In-memory cache** — sub-millisecond, TTL-based (existing behaviour).
+2. **Disk store (fresh)** — if the stored file is younger than the bar-resolution threshold, it is served as-is. No network call.
+3. **Disk store (stale) + live fetch** — if the stored file is older than the threshold, the library fetches the current window from a live provider to get the missing bars, then **merges** those new rows on top of the stored history. Historical bars are never discarded or re-requested. The merged result is written back to disk and served.
+
+The staleness threshold matches the resolution of the data so charts are never more than one bar behind:
+
+| Duration | Bar resolution | Refreshes after |
+|---|---|---|
+| `"1d"`, `"5d"` | 5 / 15-min bars | 4 hours |
+| `"1mo"`, `"3mo"`, `"6mo"` | Daily bars | 24 hours |
+| `"1y"`, `"2y"`, `"5y"` | Weekly bars | 7 days |
+| `"10y"`, `"max"` | Monthly bars | 30 days |
+
+```python
+tc.store("/data/myproject")
+tc.store("AAPL", "MSFT", "mag7", "3mo")   # fetch once, write to disk
+
+# Later — same session or a completely new one:
+tc.chart("AAPL", "3mo")                   # served from disk, no network call
+tc.data("MSFT", "3mo")                    # same
+
+# After 24 hours (daily bars): only the new day's bar is fetched and merged
+# in — the months of stored history are kept and reused as-is
+tc.chart("AAPL", "3mo")                   # delta fetch + merge, then cached
+```
+
+### Clearing stored data
+
+```python
+tc.clear_cache()           # flush in-memory cache only (default)
+tc.clear_cache(disk=True)  # also delete all CSV files in tradechart_FetchData/
+```
+
+### Store folder layout
+
+```
+/data/myproject/
+└── tradechart_FetchData/
+    ├── AAPL_3mo.csv
+    ├── MSFT_3mo.csv
+    ├── NVDA_3mo.csv
+    └── ...
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `*args` | `str \| list \| tuple` | A single path string **or** any mix of ticker symbols, named sector group keys, and/or lists — optionally ending with a duration string. |
+| `duration` | `str` (keyword) | Fallback duration when none is provided in `*args`. Default `"1mo"`. |
+
+**Returns:** the `tradechart_FetchData/` `Path` when setting the store; `None` when pre-fetching.
+
+---
+
 ## Ticker Groups — Averaged Series
 
 `tc.chart()`, `tc.data()`, and `tc.export()` accept a **list or tuple of ticker symbols** in addition to a single string. When a group is supplied the library:
@@ -137,12 +224,14 @@ If one or more tickers in the group fail to fetch data, they are **skipped with
 | `tc.theme(name)` | Set chart colour theme |
 | `tc.watermark(enabled)` | Toggle the TRADELY logo watermark |
 | `tc.config(**kwargs)` | Batch-set multiple global options at once |
+| `tc.store(path)` | Set persistent data-store directory |
+| `tc.store(ticker, ...)` | Pre-fetch and persist tickers / groups |
 | `tc.chart(...)` | Fetch data and render a chart image |
 | `tc.compare(...)` | Overlay multiple tickers on one chart |
 | `tc.heatmap(...)` | Render a performance heatmap for a ticker group |
 | `tc.data(...)` | Fetch raw OHLCV data as a DataFrame |
 | `tc.export(...)` | Export market data to CSV / JSON / XLSX |
-| `tc.clear_cache()` | Flush the in-memory data cache |
+| `tc.clear_cache(disk=False)` | Flush in-memory cache; optionally wipe disk store |
 | `tc.SECTOR_GROUPS` | Dict of 14 pre-defined ticker lists (sectors, indices, crypto, …) |
 
 ---
@@ -252,7 +341,7 @@ Tile sizes use a **squarified treemap** algorithm to minimise wasted space while
 
 ## `tc.SECTOR_GROUPS` — Pre-defined Ticker Lists
 
-A dictionary of curated ticker groups ready to pass into `tc.heatmap()`, `tc.compare()`, `tc.chart()`, or `tc.export()`.
+A dictionary of curated ticker groups ready to pass into `tc.heatmap()`, `tc.compare()`, `tc.chart()`, `tc.store()`, or `tc.export()`.
 
 ```python
 import tradechart as tc
@@ -417,10 +506,15 @@ The TRADELY logo is stamped in the bottom-left corner of every chart by default.
 ## `tc.clear_cache()` — Flush Data Cache
 
 ```python
-tc.clear_cache()
+tc.clear_cache()            # flush in-memory cache only
+tc.clear_cache(disk=True)   # also wipe all CSVs in tradechart_FetchData/
 ```
 
-Clears all in-memory cached market data, forcing the next fetch to go to the network. Useful after a TTL has not yet expired but you need fresh data (e.g. during live market hours).
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `disk` | `bool` | `False` | When `True`, deletes all CSV files in the disk store (the folder is kept). Has no effect if no store path has been set. |
+
+Clears in-memory cached market data, forcing the next fetch to check the disk store (or go to the network if no store is configured). Useful during live market hours when TTL has not yet expired but you need a fresh quote.
 
 ---
 
@@ -475,18 +569,22 @@ TradeChart tries providers in priority order and falls back automatically on fai
 
 | Priority | Provider | Requires | Notes |
 |---|---|---|---|
-| 1 | **yfinance** | Included by default | Primary source. Covers stocks, ETFs, indices, crypto, forex. |
+| 0 | **Disk store** | `tc.store(path)` called once | Served from local CSV when fresh. When stale, only the missing bars are fetched from a live provider and merged on top — historical rows are never re-requested. |
+| 1 | **yfinance** | Included by default | Primary live source. Covers stocks, ETFs, indices, crypto, forex. |
 | 2 | **TradingView** | `pip install TradeChart[tradingview]` | Tried if yfinance returns empty or fails. Attempts multiple exchanges automatically (`NASDAQ`, `NYSE`, `AMEX`, `CRYPTO`, `FX`). |
 | 3 | **Stooq** | Nothing — free CSV endpoint | Final fallback. No API key required. Duration mapped to a rolling date range. |
 
-If all three providers fail, a `DataFetchError` is raised with a list of each provider's error message.
+If all live providers fail and no disk data exists, a `DataFetchError` is raised with a list of each provider's error message.
 
 ---
 
 ## Notes
 
-**Caching**  
-Fetched data is cached in-memory for `cache_ttl` seconds (default 300 s / 5 minutes). All subsequent calls with the same ticker and duration within that window are served from cache. Call `tc.clear_cache()` to force a re-fetch, or set `tc.config(cache_ttl=0)` to disable caching entirely.
+**Persistent disk store**  
+When `tc.store()` is configured, every successful live fetch is written to `tradechart_FetchData/` as a CSV file. On subsequent requests the library checks whether the stored data is fresh enough (based on bar resolution — 24 hours for daily bars, 4 hours for intraday, etc.). If fresh, it is served directly with no network call. If stale, only the most recent bars are fetched from a live provider and merged on top of the stored history — historical rows are never discarded or re-fetched. Use `tc.clear_cache(disk=True)` to wipe stored files and force a full re-fetch.
+
+**In-memory caching**  
+Fetched data is also cached in-memory for `cache_ttl` seconds (default 300 s / 5 minutes). All subsequent calls with the same ticker and duration within that window are served from the memory cache. Call `tc.clear_cache()` to force re-evaluation (disk store is still checked before going to the network). Set `tc.config(cache_ttl=0)` to disable the memory cache entirely.
 
 **File collision handling**  
 By default (`overwrite=False`), TradeChart appends a counter to avoid overwriting existing files: `chart.png` → `chart_1.png` → `chart_2.png`. Set `tc.config(overwrite=True)` to overwrite silently.
@@ -518,7 +616,7 @@ All TradeChart exceptions inherit from `TradeChartError`.
 | `InvalidTickerError` | The ticker string fails validation (too long, invalid characters) |
 | `RenderError` | Chart rendering fails (e.g. empty dataset after cleaning) |
 | `OutputError` | The chart cannot be saved (e.g. permission denied) |
-| `ConfigError` | An unknown key is passed to `tc.config()` |
+| `ConfigError` | An unknown key is passed to `tc.config()`, or `tc.store()` is called with tickers before a path is set |
 
 ```python
 import tradechart as tc

{tradechart-2.1.2 → tradechart-2.2.1}/TradeChart.egg-info/SOURCES.txt

@@ -23,6 +23,7 @@ tradechart/data/fetcher.py
 tradechart/data/groups.py
 tradechart/data/models.py
 tradechart/data/provider_base.py
+tradechart/data/store.py
 tradechart/providers/__init__.py
 tradechart/providers/stooq_provider.py
 tradechart/providers/tradingview_provider.py

{tradechart-2.1.2 → tradechart-2.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "TradeChart"
-version = "2.1.2"
+version = "2.2.1"
 description = "Production-quality financial chart generator — candlestick, line, area, OHLC, Heikin-Ashi, performance heatmaps, and sector group charts."
 readme = "README.md"
 license = {text = "Apache-2.0"}