<div align="center">
<img src="docs/logo_large.svg" alt="PyTemporal" height="400" style="vertical-align: middle;">
</div>
**High-performance bitemporal data processing for Python**
PyTemporal is a Rust-powered library for processing bitemporal timeseries data with world-class performance (157,000+ rows/second). Perfect for financial services, audit systems, and applications requiring immutable data trails with both business and system time dimensions.
## Quick Start
```bash
# Install from source
git clone <your-repo>
cd pytemporal
uv run maturin develop --release
```
```python
import pandas as pd
from pytemporal import BitemporalTimeseriesProcessor
# Initialize processor
processor = BitemporalTimeseriesProcessor(
id_columns=['id'],
value_columns=['price']
)
# Process temporal updates
result = processor.process_updates(
current_state=current_df,
updates=updates_df,
system_date='2025-01-27'
)
print(f"Updated {len(result.to_insert)} records")
```
## Key Features
- **🚀 World-Class Performance**: 157,000+ rows/second throughput
- **🔄 Bitemporal Processing**: Track both business time and system time
- **🐍 Python-First**: High-level DataFrame API with pandas integration
- **⚡ Zero-Copy**: Apache Arrow columnar format for memory efficiency
- **🔧 Flexible Schema**: Configure ID and value columns dynamically
- **🎯 Two Update Modes**: Delta updates or full state replacement
- **🏗️ Production Ready**: Comprehensive test coverage and clean architecture
## Documentation
- **[📚 API Reference](docs/API_REFERENCE.md)** - Complete API documentation
- **[🎯 Usage Examples](docs/EXAMPLES.md)** - Practical code examples
- **[⚡ Performance Guide](docs/PERFORMANCE.md)** - Benchmarks and optimization tips
## What is Bitemporal Data?
Bitemporal data tracks two time dimensions:
- **Effective Time**: When events occurred in the real world
- **As-Of Time**: When information was recorded in the system
This enables powerful queries like "What did we think the price was on Jan 15th, as of Jan 20th?"
## Use Cases
- **Financial Services**: Price histories, portfolio valuations, risk calculations
- **Audit Systems**: Immutable change tracking with full reconstruction capability
- **Regulatory Compliance**: Time-accurate reporting for compliance requirements
- **Data Warehousing**: Slowly changing dimensions with full history preservation
## Performance
| Dataset Size | Processing Time | Throughput | Memory |
|--------------|-----------------|------------|---------|
| 800k × 80 cols | 5.4 seconds | 157k rows/sec | ~14GB |
| 100k × 20 cols | 0.6 seconds | 167k rows/sec | ~2GB |
*Benchmarked on modern hardware with optimized settings*
## Architecture
```
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Python DataFrame│───▶│ PyTemporal (Rust)│───▶│ Processed Results│
│ (Pandas) │ │ • Arrow Columnar │ │ (DataFrame) │
│ │ │ • Parallel Proc │ │ │
└─────────────────┘ │ • Timeline Logic │ └─────────────────┘
└──────────────────┘
```
**Built With:**
- **Rust**: Core processing engine for maximum performance
- **Apache Arrow**: Columnar data format for zero-copy operations
- **PyO3**: Seamless Rust-Python integration
- **Rayon**: Data parallelism for multi-core performance
## Development
```bash
# Run tests
cargo test # Rust tests
uv run python -m pytest tests/ -v # Python tests
# Performance benchmarks
cargo bench # Detailed benchmarks
uv run python validate_refactoring.py # End-to-end validation
# Build release
uv run maturin develop --release
```
## Contributing
1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make changes and add tests
4. Run the test suite: `cargo test && uv run pytest`
5. Submit a pull request
## License
This project is licensed under either of
* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
* MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
at your option.
### Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in PyTemporal by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.
## Acknowledgments
Built with modern Rust performance engineering and extensive profiling to achieve world-class bitemporal processing speeds while maintaining clean, maintainable code.
Raw data
{
"_id": null,
"home_page": "https://github.com/gingermike/pytemporal",
"name": "pytemporal",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "bitemporal, timeseries, data-processing, temporal, analytics",
"author": "PyTemporal Contributors",
"author_email": null,
"download_url": null,
"platform": null,
"description": "<div align=\"center\">\r\n<img src=\"docs/logo_large.svg\" alt=\"PyTemporal\" height=\"400\" style=\"vertical-align: middle;\">\r\n</div>\r\n\r\n**High-performance bitemporal data processing for Python**\r\n\r\nPyTemporal is a Rust-powered library for processing bitemporal timeseries data with world-class performance (157,000+ rows/second). Perfect for financial services, audit systems, and applications requiring immutable data trails with both business and system time dimensions.\r\n\r\n## Quick Start\r\n\r\n```bash\r\n# Install from source\r\ngit clone <your-repo>\r\ncd pytemporal\r\nuv run maturin develop --release\r\n```\r\n\r\n```python\r\nimport pandas as pd\r\nfrom pytemporal import BitemporalTimeseriesProcessor\r\n\r\n# Initialize processor\r\nprocessor = BitemporalTimeseriesProcessor(\r\n id_columns=['id'],\r\n value_columns=['price']\r\n)\r\n\r\n# Process temporal updates\r\nresult = processor.process_updates(\r\n current_state=current_df,\r\n updates=updates_df, \r\n system_date='2025-01-27'\r\n)\r\n\r\nprint(f\"Updated {len(result.to_insert)} records\")\r\n```\r\n\r\n## Key Features\r\n\r\n- **\ud83d\ude80 World-Class Performance**: 157,000+ rows/second throughput\r\n- **\ud83d\udd04 Bitemporal Processing**: Track both business time and system time\r\n- **\ud83d\udc0d Python-First**: High-level DataFrame API with pandas integration\r\n- **\u26a1 Zero-Copy**: Apache Arrow columnar format for memory efficiency\r\n- **\ud83d\udd27 Flexible Schema**: Configure ID and value columns dynamically\r\n- **\ud83c\udfaf Two Update Modes**: Delta updates or full state replacement\r\n- **\ud83c\udfd7\ufe0f Production Ready**: Comprehensive test coverage and clean architecture\r\n\r\n## Documentation\r\n\r\n- **[\ud83d\udcda API Reference](docs/API_REFERENCE.md)** - Complete API documentation\r\n- **[\ud83c\udfaf Usage Examples](docs/EXAMPLES.md)** - Practical code examples \r\n- **[\u26a1 Performance Guide](docs/PERFORMANCE.md)** - Benchmarks and optimization tips\r\n\r\n## What is Bitemporal Data?\r\n\r\nBitemporal data tracks two time dimensions:\r\n- **Effective Time**: When events occurred in the real world\r\n- **As-Of Time**: When information was recorded in the system\r\n\r\nThis enables powerful queries like \"What did we think the price was on Jan 15th, as of Jan 20th?\"\r\n\r\n## Use Cases\r\n\r\n- **Financial Services**: Price histories, portfolio valuations, risk calculations\r\n- **Audit Systems**: Immutable change tracking with full reconstruction capability \r\n- **Regulatory Compliance**: Time-accurate reporting for compliance requirements\r\n- **Data Warehousing**: Slowly changing dimensions with full history preservation\r\n\r\n## Performance\r\n\r\n| Dataset Size | Processing Time | Throughput | Memory |\r\n|--------------|-----------------|------------|---------|\r\n| 800k \u00d7 80 cols | 5.4 seconds | 157k rows/sec | ~14GB |\r\n| 100k \u00d7 20 cols | 0.6 seconds | 167k rows/sec | ~2GB |\r\n\r\n*Benchmarked on modern hardware with optimized settings*\r\n\r\n## Architecture\r\n\r\n```\r\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\r\n\u2502 Python DataFrame\u2502\u2500\u2500\u2500\u25b6\u2502 PyTemporal (Rust)\u2502\u2500\u2500\u2500\u25b6\u2502 Processed Results\u2502\r\n\u2502 (Pandas) \u2502 \u2502 \u2022 Arrow Columnar \u2502 \u2502 (DataFrame) \u2502 \r\n\u2502 \u2502 \u2502 \u2022 Parallel Proc \u2502 \u2502 \u2502\r\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502 \u2022 Timeline Logic \u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\r\n \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\r\n```\r\n\r\n**Built With:**\r\n- **Rust**: Core processing engine for maximum performance\r\n- **Apache Arrow**: Columnar data format for zero-copy operations \r\n- **PyO3**: Seamless Rust-Python integration\r\n- **Rayon**: Data parallelism for multi-core performance\r\n\r\n## Development\r\n\r\n```bash\r\n# Run tests\r\ncargo test # Rust tests\r\nuv run python -m pytest tests/ -v # Python tests\r\n\r\n# Performance benchmarks \r\ncargo bench # Detailed benchmarks\r\nuv run python validate_refactoring.py # End-to-end validation\r\n\r\n# Build release\r\nuv run maturin develop --release\r\n```\r\n\r\n## Contributing\r\n\r\n1. Fork the repository\r\n2. Create a feature branch: `git checkout -b feature-name`\r\n3. Make changes and add tests\r\n4. Run the test suite: `cargo test && uv run pytest`\r\n5. Submit a pull request\r\n\r\n## License\r\n\r\nThis project is licensed under either of\r\n\r\n * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)\r\n * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)\r\n\r\nat your option.\r\n\r\n### Contribution\r\n\r\nUnless you explicitly state otherwise, any contribution intentionally submitted\r\nfor inclusion in PyTemporal by you, as defined in the Apache-2.0 license, shall be\r\ndual licensed as above, without any additional terms or conditions.\r\n\r\n## Acknowledgments\r\n\r\nBuilt with modern Rust performance engineering and extensive profiling to achieve world-class bitemporal processing speeds while maintaining clean, maintainable code.\n",
"bugtrack_url": null,
"license": "MIT OR Apache-2.0",
"summary": "High-performance bitemporal data processing for Python",
"version": "1.3.15",
"project_urls": {
"Changelog": "https://github.com/gingermike/pytemporal/blob/main/CHANGELOG.md",
"Documentation": "https://gingermike.github.io/pytemporal/",
"Homepage": "https://github.com/gingermike/pytemporal",
"Issue Tracker": "https://github.com/gingermike/pytemporal/issues",
"Performance Benchmarks": "https://gingermike.github.io/pytemporal/",
"Repository": "https://github.com/gingermike/pytemporal"
},
"split_keywords": [
"bitemporal",
" timeseries",
" data-processing",
" temporal",
" analytics"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "51471ac3aeeeb364e071289b2647377333eb4ab437e8a399e0f0dcbdbad5bde7",
"md5": "2fddc872924ebb9ecfb9eaf2b00f9572",
"sha256": "52db6f979883096127379d19ae5c5b8f47bb38f5a6b810f24bbc1afbc1ef2917"
},
"downloads": -1,
"filename": "pytemporal-1.3.15-cp310-cp310-manylinux_2_34_x86_64.whl",
"has_sig": false,
"md5_digest": "2fddc872924ebb9ecfb9eaf2b00f9572",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.9",
"size": 2470222,
"upload_time": "2025-09-07T17:25:45",
"upload_time_iso_8601": "2025-09-07T17:25:45.906301Z",
"url": "https://files.pythonhosted.org/packages/51/47/1ac3aeeeb364e071289b2647377333eb4ab437e8a399e0f0dcbdbad5bde7/pytemporal-1.3.15-cp310-cp310-manylinux_2_34_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2873507d24257187c085e7be0504db5987b3da5b27ed56b717a245bac8e2f153",
"md5": "e96f85b847b53f795aca0253fb06c4d0",
"sha256": "dafeaaabb12c70b389d87d9a83dc5df1f927a6a2b6cd7a93ab38f5373392790e"
},
"downloads": -1,
"filename": "pytemporal-1.3.15-cp311-cp311-manylinux_2_34_x86_64.whl",
"has_sig": false,
"md5_digest": "e96f85b847b53f795aca0253fb06c4d0",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.9",
"size": 2470193,
"upload_time": "2025-09-07T17:25:47",
"upload_time_iso_8601": "2025-09-07T17:25:47.810959Z",
"url": "https://files.pythonhosted.org/packages/28/73/507d24257187c085e7be0504db5987b3da5b27ed56b717a245bac8e2f153/pytemporal-1.3.15-cp311-cp311-manylinux_2_34_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cc41c45423e221d1f97e8871b44752073057a773482126d9a93cc3976bfc8024",
"md5": "b9ceaef79ba279cd7bc74355ec7db82d",
"sha256": "0d104b919c33c9e7ccbbdd49bc5034666a4aa4053d78a941ee4f361824040d03"
},
"downloads": -1,
"filename": "pytemporal-1.3.15-cp312-cp312-manylinux_2_34_x86_64.whl",
"has_sig": false,
"md5_digest": "b9ceaef79ba279cd7bc74355ec7db82d",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.9",
"size": 2466401,
"upload_time": "2025-09-07T17:25:49",
"upload_time_iso_8601": "2025-09-07T17:25:49.638627Z",
"url": "https://files.pythonhosted.org/packages/cc/41/c45423e221d1f97e8871b44752073057a773482126d9a93cc3976bfc8024/pytemporal-1.3.15-cp312-cp312-manylinux_2_34_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "377a071f22975cf3aa51a583023d3b8cb5e6f631a00a2d93aae1d0276861052c",
"md5": "94e0d8d1a26a342e317c35e4e43d0796",
"sha256": "bac2700f430336c73571d1c66b0ec0c8de5b92e33b7286cc8e86135e651228ea"
},
"downloads": -1,
"filename": "pytemporal-1.3.15-cp39-cp39-manylinux_2_34_x86_64.whl",
"has_sig": false,
"md5_digest": "94e0d8d1a26a342e317c35e4e43d0796",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.9",
"size": 2471151,
"upload_time": "2025-09-07T17:25:51",
"upload_time_iso_8601": "2025-09-07T17:25:51.046886Z",
"url": "https://files.pythonhosted.org/packages/37/7a/071f22975cf3aa51a583023d3b8cb5e6f631a00a2d93aae1d0276861052c/pytemporal-1.3.15-cp39-cp39-manylinux_2_34_x86_64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-07 17:25:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gingermike",
"github_project": "pytemporal",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pytemporal"
}
JSON
