| Name | finlab-guard JSON |
| Version |
0.4.1
JSON |
| download |
| home_page | None |
| Summary | A lightweight package for managing local finlab data cache with versioning and time-context features |
| upload_time | 2025-10-07 17:32:16 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
backtesting
cache
data
finlab
versioning
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# finlab-guard
**This is an unofficial, third-party implementation**
A lightweight package for managing a local finlab data cache with versioning and time-context features.
[](LICENSE)
[](https://github.com/iapcal/finlab-guard/actions/workflows/build.yml)
[](https://github.com/iapcal/finlab-guard/actions/workflows/lint.yml)
[](https://codecov.io/gh/iapcal/finlab-guard)
## Installation
```bash
pip install finlab-guard
```
## Usage examples
Three short examples showing the most common flows.
### 1) Monkey-patch finlab.data.get (installing FinlabGuard)
This project can monkey-patch `finlab.data.get` so reads go through the guarded cache. Example:
```python
from finlab import data
from finlab_guard import FinlabGuard
# Create a FinlabGuard instance and install the monkey-patch
guard = FinlabGuard()
guard.install_patch()
# Use data.get as normal; FinlabGuard will intercept and use cache
result = data.get('price:收盤價')
# When done, remove the monkey-patch
guard.remove_patch()
```
### 2) Set a time context and get historical data
FinlabGuard supports a time context so you can query data "as-of" a past time.
```python
from finlab import data
from finlab_guard import FinlabGuard
from datetime import datetime, timedelta
guard = FinlabGuard()
guard.install_patch()
# Set time context to 7 days ago
query_time = datetime.now() - timedelta(days=7)
guard.set_time_context(query_time)
# Now call data.get normally; the guard will return historical data
result = data.get('price:收盤價')
# Clear the time context and remove the monkey-patch when done
guard.clear_time_context()
guard.remove_patch()
```
### 3) Parameter precedence for allow_historical_changes
FinlabGuard uses an `effective_allow_changes` logic with parameter precedence:
```python
from finlab import data
from finlab_guard import FinlabGuard
# Set global setting via install_patch
guard = FinlabGuard()
guard.install_patch(allow_historical_changes=False) # Global setting
# Method parameter overrides global setting
result1 = data.get('price:收盤價', allow_historical_changes=True) # Uses True (method override)
result2 = data.get('volume:成交量') # Uses False (global setting)
# Precedence order: method parameter > global setting > default (True)
```
**Parameter Precedence**:
1. **Method parameter** (highest priority): `get(dataset, allow_historical_changes=True/False)`
2. **Global setting**: Set via `install_patch(allow_historical_changes=True/False)`
3. **Default value** (lowest priority): `True` - allows historical changes by default
This allows fine-grained control where you can set a global policy but override it for specific datasets when needed.
## What's New in v0.4.0
### 🔧 Breaking Changes
- **Default `allow_historical_changes` changed to `True`**: Historical data modifications are now allowed by default. Set to `False` if you need strict change detection.
### 🐛 Critical Bug Fixes
- **Row/column lifecycle filtering**: Fixed stale `cell_changes` incorrectly affecting re-added rows/columns after deletion.
## Performance
finlab-guard delivers significant performance improvements through its DuckDB + Polars architecture:
🚀 **Cache Performance**: Up to **96% faster** with hash optimization
| Version | Reconstruction Time | Hash Match Time | Improvement |
|---------|-------------------|-----------------|-------------|
| v0.1.0 (pandas.stack) | 17.9s | N/A | baseline |
| v0.2.0 (DuckDB+Polars) | 12.4s | N/A | **-30.6%** ⚡ |
| v0.3.0 (Hash + orjson) | 11.2s | **0.74s** | **-37.5% / -96%** 🚀 |
*Benchmark: `etl:adj_close` cache retrieval (4,533 × 2,645 DataFrame) - average of 10 runs*
### Key Optimizations
- **DataFrame hash optimization** (v0.3.0): Fast data comparison using SHA256 hashes to avoid expensive reconstruction when data is unchanged
- **orjson acceleration** (v0.3.0): Faster JSON parsing with vectorized operations and reduced memory overhead for reconstruction scenarios
- **Eliminated pandas.stack() bottleneck**: Replaced with vectorized Polars operations
- **Cell-level change tracking**: Only stores actual differences, not full datasets
- **DuckDB storage engine**: High-performance indexed storage with time-based reconstruction
- **Intelligent thresholding**: Large row changes stored efficiently as JSON objects
These improvements make finlab-guard ideal for:
- Large datasets with frequent updates
- Historical data analysis and backtesting
- Production environments requiring consistent performance
## Disclaimer
This project is not affiliated with, endorsed by, or officially supported by finlab. It is an independent implementation designed to work alongside the finlab package for enhanced data caching and version control.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "finlab-guard",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "backtesting, cache, data, finlab, versioning",
"author": null,
"author_email": "iapcal <chiyimin2018@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/e6/04/29955349b3e994722800dac949f41e0b799d6ffd4adb248e4d13d144949d/finlab_guard-0.4.1.tar.gz",
"platform": null,
"description": "# finlab-guard\n\n**This is an unofficial, third-party implementation**\n\nA lightweight package for managing a local finlab data cache with versioning and time-context features.\n\n\n\n\n\n[](LICENSE)\n[](https://github.com/iapcal/finlab-guard/actions/workflows/build.yml)\n[](https://github.com/iapcal/finlab-guard/actions/workflows/lint.yml)\n[](https://codecov.io/gh/iapcal/finlab-guard)\n\n## Installation\n\n```bash\npip install finlab-guard\n```\n\n## Usage examples\n\nThree short examples showing the most common flows.\n\n### 1) Monkey-patch finlab.data.get (installing FinlabGuard)\n\nThis project can monkey-patch `finlab.data.get` so reads go through the guarded cache. Example:\n\n```python\nfrom finlab import data\nfrom finlab_guard import FinlabGuard\n\n# Create a FinlabGuard instance and install the monkey-patch\nguard = FinlabGuard()\nguard.install_patch()\n\n# Use data.get as normal; FinlabGuard will intercept and use cache\nresult = data.get('price:\u6536\u76e4\u50f9')\n\n# When done, remove the monkey-patch\nguard.remove_patch()\n```\n\n### 2) Set a time context and get historical data\n\nFinlabGuard supports a time context so you can query data \"as-of\" a past time.\n\n```python\nfrom finlab import data\nfrom finlab_guard import FinlabGuard\nfrom datetime import datetime, timedelta\n\nguard = FinlabGuard()\nguard.install_patch()\n\n# Set time context to 7 days ago\nquery_time = datetime.now() - timedelta(days=7)\nguard.set_time_context(query_time)\n\n# Now call data.get normally; the guard will return historical data\nresult = data.get('price:\u6536\u76e4\u50f9')\n\n# Clear the time context and remove the monkey-patch when done\nguard.clear_time_context()\nguard.remove_patch()\n```\n\n### 3) Parameter precedence for allow_historical_changes\n\nFinlabGuard uses an `effective_allow_changes` logic with parameter precedence:\n\n```python\nfrom finlab import data\nfrom finlab_guard import FinlabGuard\n\n# Set global setting via install_patch\nguard = FinlabGuard()\nguard.install_patch(allow_historical_changes=False) # Global setting\n\n# Method parameter overrides global setting\nresult1 = data.get('price:\u6536\u76e4\u50f9', allow_historical_changes=True) # Uses True (method override)\nresult2 = data.get('volume:\u6210\u4ea4\u91cf') # Uses False (global setting)\n\n# Precedence order: method parameter > global setting > default (True)\n```\n\n**Parameter Precedence**:\n1. **Method parameter** (highest priority): `get(dataset, allow_historical_changes=True/False)`\n2. **Global setting**: Set via `install_patch(allow_historical_changes=True/False)`\n3. **Default value** (lowest priority): `True` - allows historical changes by default\n\nThis allows fine-grained control where you can set a global policy but override it for specific datasets when needed.\n\n## What's New in v0.4.0\n\n### \ud83d\udd27 Breaking Changes\n- **Default `allow_historical_changes` changed to `True`**: Historical data modifications are now allowed by default. Set to `False` if you need strict change detection.\n\n### \ud83d\udc1b Critical Bug Fixes\n- **Row/column lifecycle filtering**: Fixed stale `cell_changes` incorrectly affecting re-added rows/columns after deletion.\n\n## Performance\n\nfinlab-guard delivers significant performance improvements through its DuckDB + Polars architecture:\n\n\ud83d\ude80 **Cache Performance**: Up to **96% faster** with hash optimization\n\n| Version | Reconstruction Time | Hash Match Time | Improvement |\n|---------|-------------------|-----------------|-------------|\n| v0.1.0 (pandas.stack) | 17.9s | N/A | baseline |\n| v0.2.0 (DuckDB+Polars) | 12.4s | N/A | **-30.6%** \u26a1 |\n| v0.3.0 (Hash + orjson) | 11.2s | **0.74s** | **-37.5% / -96%** \ud83d\ude80 |\n\n*Benchmark: `etl:adj_close` cache retrieval (4,533 \u00d7 2,645 DataFrame) - average of 10 runs*\n\n### Key Optimizations\n\n- **DataFrame hash optimization** (v0.3.0): Fast data comparison using SHA256 hashes to avoid expensive reconstruction when data is unchanged\n- **orjson acceleration** (v0.3.0): Faster JSON parsing with vectorized operations and reduced memory overhead for reconstruction scenarios\n- **Eliminated pandas.stack() bottleneck**: Replaced with vectorized Polars operations\n- **Cell-level change tracking**: Only stores actual differences, not full datasets\n- **DuckDB storage engine**: High-performance indexed storage with time-based reconstruction\n- **Intelligent thresholding**: Large row changes stored efficiently as JSON objects\n\nThese improvements make finlab-guard ideal for:\n- Large datasets with frequent updates\n- Historical data analysis and backtesting\n- Production environments requiring consistent performance\n\n## Disclaimer\n\nThis project is not affiliated with, endorsed by, or officially supported by finlab. It is an independent implementation designed to work alongside the finlab package for enhanced data caching and version control.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.",
"bugtrack_url": null,
"license": null,
"summary": "A lightweight package for managing local finlab data cache with versioning and time-context features",
"version": "0.4.1",
"project_urls": null,
"split_keywords": [
"backtesting",
" cache",
" data",
" finlab",
" versioning"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b39ba6a184e028ff7413d2b5fc653fc0d5f94d8bb8eee133977e329988a05365",
"md5": "bceb501b40962d07cb061a138e941214",
"sha256": "2f44499c46824fbec5e81ec3eb9e448c9732cadc53718eb5fc0b7cea987c5a6c"
},
"downloads": -1,
"filename": "finlab_guard-0.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bceb501b40962d07cb061a138e941214",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 33467,
"upload_time": "2025-10-07T17:32:15",
"upload_time_iso_8601": "2025-10-07T17:32:15.282967Z",
"url": "https://files.pythonhosted.org/packages/b3/9b/a6a184e028ff7413d2b5fc653fc0d5f94d8bb8eee133977e329988a05365/finlab_guard-0.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e60429955349b3e994722800dac949f41e0b799d6ffd4adb248e4d13d144949d",
"md5": "71dd05b5e963c08aab3c3fd1f331425a",
"sha256": "8637fea887ea41b06f02991c9539db5be0e53121cecff559fe5d224015365531"
},
"downloads": -1,
"filename": "finlab_guard-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "71dd05b5e963c08aab3c3fd1f331425a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 229480,
"upload_time": "2025-10-07T17:32:16",
"upload_time_iso_8601": "2025-10-07T17:32:16.348160Z",
"url": "https://files.pythonhosted.org/packages/e6/04/29955349b3e994722800dac949f41e0b799d6ffd4adb248e4d13d144949d/finlab_guard-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-07 17:32:16",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "finlab-guard"
}
