# splurge-tabular
[](https://pypi.org/project/splurge-tabular/)
[](https://pypi.org/project/splurge-tabular/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/jim-schilling/splurge-tabular/actions/workflows/ci-quick-test.yml)
[](https://github.com/jim-schilling/splurge-tabular)
[](https://github.com/astral-sh/ruff)
[](https://mypy-lang.org/)
A modern, high-performance Python library for tabular data processing with both in-memory and streaming capabilities.
> ⚠️ Release notice — Breaking changes in 2025.1.0
>
> The 2025.1.0 release introduces breaking changes to the exceptions and error codes raised by this library. Callers that depend on exact exception classes, message text, or literal error-code strings may need to update their code.
>
> Key changes:
>
> - Exceptions now carry structured metadata: an `error_code` (an `ErrorCode` enum) and an optional `context` dict.
> - Some error types were reorganized into more specific subclasses (for example, configuration-, column-, row-, and validation-related errors).
> - The textual formatting of some exception messages was stabilized to preserve backward compatibility where possible, but callers should prefer programmatic inspection of `error_code` and exception class.
>
> Migration:
>
> - Inspect raised exceptions for `error_code` (recommended) rather than parsing messages.
> - See `docs/API-REFERENCE.md` (ErrorCode section) and `CHANGELOG.md` for the full list of changed codes and examples.
>
> If you rely on the previous exception shapes or messages and need help migrating, open an issue or consult the API reference in `docs/` or the detailed migration guide: `docs/notes/MIGRATION-TO-2025.1.0.md`.
## ✨ Features
- **Dual Processing Modes**: Choose between memory-efficient streaming or full in-memory processing
- **Type Safety**: Full type annotations with modern Python typing
- **Robust Error Handling**: Comprehensive exception hierarchy with detailed error messages
- **Flexible Data Input**: Support for CSV, JSON, and custom data formats
- **High Performance**: Optimized for both small datasets and large-scale processing
- **Production Ready**: 96% test coverage with 219 comprehensive tests
- **Modern Packaging**: Built with modern Python standards and best practices
## 🚀 Quick Start
### Installation
```bash
pip install splurge-tabular
```
### Basic Usage
```python
from splurge_tabular import TabularDataModel, StreamingTabularDataModel
# In-memory processing
data = [
["name", "age", "city"],
["Alice", "25", "New York"],
["Bob", "30", "London"]
]
model = TabularDataModel(data)
print(f"Columns: {model.column_names}")
print(f"Row count: {model.row_count}")
# Access data
for row in model:
print(row)
# Streaming processing for large datasets
import io
csv_data = """name,age,city
Alice,25,New York
Bob,30,London"""
stream = io.StringIO(csv_data)
streaming_model = StreamingTabularDataModel(stream)
for row in streaming_model:
print(row)
```
## 📋 Requirements
- Python 3.10+
- Dependencies automatically managed via `pip`
## 🧪 Testing
The library includes comprehensive test suites:
```bash
# Run all tests
python -m pytest
# Run with coverage
python -m pytest --cov=splurge_tabular
# Run specific test categories
python -m pytest tests/unit/ # Unit tests
python -m pytest tests/integration/ # Integration tests
python -m pytest tests/e2e/ # End-to-end tests
```
## 📚 Documentation
- [Detailed Documentation](docs/README-details.md) - Comprehensive API reference and examples
- [Changelog](CHANGELOG.md) - Version history and release notes
## 🏗️ Architecture
### Core Components
- **`TabularDataModel`**: Full in-memory tabular data processing
- **`StreamingTabularDataModel`**: Memory-efficient streaming processing
- **Exception Hierarchy**: Comprehensive error handling with `SplurgeError` base class
- **Utility Functions**: Data validation, normalization, and processing helpers
### Design Principles
- **SOLID Principles**: Single responsibility, open-closed, etc.
- **DRY**: Don't Repeat Yourself
- **KISS**: Keep It Simple, Stupid
- **Type Safety**: Full type annotations throughout
- **Error Resilience**: Fail fast with clear error messages
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
### Development Setup
```bash
# Clone the repository
git clone https://github.com/jim-schilling/splurge-tabular.git
cd splurge-tabular
# Create virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install dependencies
pip install -e .[dev]
# Run tests
python -m pytest
```
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 👤 Author
**Jim Schilling**
- GitHub: [@jim-schilling](https://github.com/jim-schilling)
## 🙏 Acknowledgments
- Built with modern Python best practices
- Inspired by the need for robust, type-safe tabular data processing
- Thanks to the Python community for excellent tools and libraries
Raw data
{
"_id": null,
"home_page": null,
"name": "splurge-tabular",
"maintainer": "Jim Schilling",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "tabular, data, csv, dsv, delimited, processing, streaming",
"author": "Jim Schilling",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/47/a0/93fba89ee82700c92eec474567766e9f5fda84b8dd8f1f6bcbce7784742f/splurge_tabular-2025.1.0.tar.gz",
"platform": null,
"description": "# splurge-tabular\r\n[](https://pypi.org/project/splurge-tabular/)\r\n[](https://pypi.org/project/splurge-tabular/)\r\n[](https://opensource.org/licenses/MIT)\r\n\r\n[](https://github.com/jim-schilling/splurge-tabular/actions/workflows/ci-quick-test.yml)\r\n[](https://github.com/jim-schilling/splurge-tabular)\r\n[](https://github.com/astral-sh/ruff)\r\n[](https://mypy-lang.org/)\r\n\r\nA modern, high-performance Python library for tabular data processing with both in-memory and streaming capabilities.\r\n\r\n> \u26a0\ufe0f Release notice \u2014 Breaking changes in 2025.1.0\r\n>\r\n> The 2025.1.0 release introduces breaking changes to the exceptions and error codes raised by this library. Callers that depend on exact exception classes, message text, or literal error-code strings may need to update their code.\r\n>\r\n> Key changes:\r\n>\r\n> - Exceptions now carry structured metadata: an `error_code` (an `ErrorCode` enum) and an optional `context` dict.\r\n> - Some error types were reorganized into more specific subclasses (for example, configuration-, column-, row-, and validation-related errors).\r\n> - The textual formatting of some exception messages was stabilized to preserve backward compatibility where possible, but callers should prefer programmatic inspection of `error_code` and exception class.\r\n>\r\n> Migration:\r\n>\r\n> - Inspect raised exceptions for `error_code` (recommended) rather than parsing messages.\r\n> - See `docs/API-REFERENCE.md` (ErrorCode section) and `CHANGELOG.md` for the full list of changed codes and examples.\r\n>\r\n> If you rely on the previous exception shapes or messages and need help migrating, open an issue or consult the API reference in `docs/` or the detailed migration guide: `docs/notes/MIGRATION-TO-2025.1.0.md`.\r\n\r\n## \u2728 Features\r\n\r\n- **Dual Processing Modes**: Choose between memory-efficient streaming or full in-memory processing\r\n- **Type Safety**: Full type annotations with modern Python typing\r\n- **Robust Error Handling**: Comprehensive exception hierarchy with detailed error messages\r\n- **Flexible Data Input**: Support for CSV, JSON, and custom data formats\r\n- **High Performance**: Optimized for both small datasets and large-scale processing\r\n- **Production Ready**: 96% test coverage with 219 comprehensive tests\r\n- **Modern Packaging**: Built with modern Python standards and best practices\r\n\r\n## \ud83d\ude80 Quick Start\r\n\r\n### Installation\r\n\r\n```bash\r\npip install splurge-tabular\r\n```\r\n\r\n### Basic Usage\r\n\r\n```python\r\nfrom splurge_tabular import TabularDataModel, StreamingTabularDataModel\r\n\r\n# In-memory processing\r\ndata = [\r\n [\"name\", \"age\", \"city\"],\r\n [\"Alice\", \"25\", \"New York\"],\r\n [\"Bob\", \"30\", \"London\"]\r\n]\r\n\r\nmodel = TabularDataModel(data)\r\nprint(f\"Columns: {model.column_names}\")\r\nprint(f\"Row count: {model.row_count}\")\r\n\r\n# Access data\r\nfor row in model:\r\n print(row)\r\n\r\n# Streaming processing for large datasets\r\nimport io\r\ncsv_data = \"\"\"name,age,city\r\nAlice,25,New York\r\nBob,30,London\"\"\"\r\n\r\nstream = io.StringIO(csv_data)\r\nstreaming_model = StreamingTabularDataModel(stream)\r\nfor row in streaming_model:\r\n print(row)\r\n```\r\n\r\n## \ud83d\udccb Requirements\r\n\r\n- Python 3.10+\r\n- Dependencies automatically managed via `pip`\r\n\r\n## \ud83e\uddea Testing\r\n\r\nThe library includes comprehensive test suites:\r\n\r\n```bash\r\n# Run all tests\r\npython -m pytest\r\n\r\n# Run with coverage\r\npython -m pytest --cov=splurge_tabular\r\n\r\n# Run specific test categories\r\npython -m pytest tests/unit/ # Unit tests\r\npython -m pytest tests/integration/ # Integration tests\r\npython -m pytest tests/e2e/ # End-to-end tests\r\n```\r\n\r\n## \ud83d\udcda Documentation\r\n\r\n- [Detailed Documentation](docs/README-details.md) - Comprehensive API reference and examples\r\n- [Changelog](CHANGELOG.md) - Version history and release notes\r\n\r\n## \ud83c\udfd7\ufe0f Architecture\r\n\r\n### Core Components\r\n\r\n- **`TabularDataModel`**: Full in-memory tabular data processing\r\n- **`StreamingTabularDataModel`**: Memory-efficient streaming processing\r\n- **Exception Hierarchy**: Comprehensive error handling with `SplurgeError` base class\r\n- **Utility Functions**: Data validation, normalization, and processing helpers\r\n\r\n### Design Principles\r\n\r\n- **SOLID Principles**: Single responsibility, open-closed, etc.\r\n- **DRY**: Don't Repeat Yourself\r\n- **KISS**: Keep It Simple, Stupid\r\n- **Type Safety**: Full type annotations throughout\r\n- **Error Resilience**: Fail fast with clear error messages\r\n\r\n## \ud83e\udd1d Contributing\r\n\r\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\r\n\r\n### Development Setup\r\n\r\n```bash\r\n# Clone the repository\r\ngit clone https://github.com/jim-schilling/splurge-tabular.git\r\ncd splurge-tabular\r\n\r\n# Create virtual environment\r\npython -m venv .venv\r\nsource .venv/bin/activate # On Windows: .venv\\Scripts\\activate\r\n\r\n# Install dependencies\r\npip install -e .[dev]\r\n\r\n# Run tests\r\npython -m pytest\r\n```\r\n\r\n## \ud83d\udcc4 License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## \ud83d\udc64 Author\r\n\r\n**Jim Schilling**\r\n- GitHub: [@jim-schilling](https://github.com/jim-schilling)\r\n\r\n## \ud83d\ude4f Acknowledgments\r\n\r\n- Built with modern Python best practices\r\n- Inspired by the need for robust, type-safe tabular data processing\r\n- Thanks to the Python community for excellent tools and libraries\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python library for tabular data processing with in-memory and streaming support",
"version": "2025.1.0",
"project_urls": {
"Changelog": "https://github.com/jim-schilling/splurge-tabular/blob/main/CHANGELOG.md",
"Homepage": "https://github.com/jim-schilling/splurge-tabular",
"Issues": "https://github.com/jim-schilling/splurge-tabular/issues",
"Repository": "https://github.com/jim-schilling/splurge-tabular"
},
"split_keywords": [
"tabular",
" data",
" csv",
" dsv",
" delimited",
" processing",
" streaming"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "05b806c617ad4439486687f05ad1ff8558b3b240f6170215d919fafe75f784c1",
"md5": "f62ecb0d39b7e9bce416ab40ba46adea",
"sha256": "a690528506cda8cc37d84c1b936c3807d5a34428482ef43eee9d037a55d270d1"
},
"downloads": -1,
"filename": "splurge_tabular-2025.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f62ecb0d39b7e9bce416ab40ba46adea",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 22265,
"upload_time": "2025-10-07T01:14:29",
"upload_time_iso_8601": "2025-10-07T01:14:29.413418Z",
"url": "https://files.pythonhosted.org/packages/05/b8/06c617ad4439486687f05ad1ff8558b3b240f6170215d919fafe75f784c1/splurge_tabular-2025.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "47a093fba89ee82700c92eec474567766e9f5fda84b8dd8f1f6bcbce7784742f",
"md5": "50e9befd352a5f8fdefefb17c3257887",
"sha256": "1c897f8d2d93de80227a1564e63f5e94fcafe57ac4ef9ff471b0a7f8974797b5"
},
"downloads": -1,
"filename": "splurge_tabular-2025.1.0.tar.gz",
"has_sig": false,
"md5_digest": "50e9befd352a5f8fdefefb17c3257887",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 21441,
"upload_time": "2025-10-07T01:14:30",
"upload_time_iso_8601": "2025-10-07T01:14:30.496955Z",
"url": "https://files.pythonhosted.org/packages/47/a0/93fba89ee82700c92eec474567766e9f5fda84b8dd8f1f6bcbce7784742f/splurge_tabular-2025.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-07 01:14:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jim-schilling",
"github_project": "splurge-tabular",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "splurge-tabular"
}
JSON
