compytroller 0.1.0__tar.gz

compytroller-0.1.0/CHANGELOG.md

@@ -0,0 +1,79 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-04-03
+
+Initial public release.
+
+### Added
+- ComptrollerClient for accessing Texas Comptroller data
+- Sales tax data resources:
+  - Active permits
+  - Tax rates
+  - Allocation history
+  - Payment details
+  - Single local allocations
+  - Marketplace provider data
+  - Permitted locations
+  - Direct pay taxpayers
+  - Quarterly sales history
+  - Single local tax rates
+  - City/county comparison summaries
+  - County/SPD/MTA allocations
+- Franchise tax resources:
+  - Active permit holders
+- Mixed beverage tax resources:
+  - Gross receipts
+  - Allocation history
+- Fluent query builder API with method chaining
+- Type-safe response models using dataclasses
+- Type-safe field enums for all dataset resources (`ActivePermitField`, `SalesTaxRateField`, `FranchiseTaxPermitHolderField`, `MixedBeverageGrossReceiptsField`, etc.)
+- Categorical enums for filter values (`AuthorityType`, `RightToTransactCode`, `SalesTaxRateType`)
+- Union type hints (`str | FieldEnum`) on `sort_by()` and categorical filter methods for IDE discoverability
+- Custom exception hierarchy (HttpError, InvalidRequest)
+- Multiple data source support (Socrata API, web scraping, CSV downloads)
+- Comprehensive documentation
+- Full test coverage (99%)
+- CONTRIBUTING.md with import path conventions
+
+---
+
+## Release Notes
+
+### Version 0.1.0
+
+This is the first public release of Compytroller, a comprehensive Python library for accessing Texas Comptroller of Public Accounts data. The library provides:
+
+**Key Features:**
+- **16 sales tax data resources** covering rates, permits, allocations, and historical data
+- **Franchise and mixed beverage tax support** with dedicated resource classes
+- **Fluent API** with method chaining for intuitive query construction
+- **Type-safe responses** using Python dataclasses with full type hints
+- **Type-safe field enums** for IDE discoverability on `sort_by()` and categorical filters
+- **Multiple data sources** including Socrata API, web scraping, and CSV downloads
+- **Comprehensive error handling** with custom exception types
+- **99% test coverage** ensuring reliability and stability
+
+**Python Support:**
+- Python 3.10+
+- Type hints throughout the codebase
+- Fully tested on Python 3.10-3.12
+
+**Dependencies:**
+- httpx (HTTP client)
+- pandas (data processing)
+- selectolax (HTML parsing)
+
+For detailed API documentation, see the [API reference](docs/API.md).
+
+<<<<<<< Updated upstream
+[0.1.0]: https://github.com/TeamZac/compytroller/releases/tag/v0.1.0
+=======
+[Unreleased]: https://github.com/zactax/compytroller/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/zactax/compytroller/releases/tag/v0.1.0
+[0.0.1]: https://github.com/zactax/compytroller/releases/tag/v0.0.1
+>>>>>>> Stashed changes

compytroller-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ZacTax
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

compytroller-0.1.0/MANIFEST.in

@@ -0,0 +1,26 @@
+# Include documentation
+include README.md
+include LICENSE
+include CHANGELOG.md
+
+# Include configuration files
+include pyproject.toml
+include requirements.txt
+
+# Include type hints
+recursive-include src/compytroller py.typed *.pyi
+
+# Exclude development files
+exclude .gitignore
+exclude .pre-commit-config.yaml
+recursive-exclude tests *
+recursive-exclude docs *
+recursive-exclude htmlcov *
+recursive-exclude .pytest_cache *
+recursive-exclude __pycache__ *
+recursive-exclude * *.py[cod]
+recursive-exclude * *.so
+recursive-exclude * *.dylib
+recursive-exclude * .DS_Store
+exclude .coverage
+exclude example_usage.ipynb

compytroller-0.1.0/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: compytroller
+Version: 0.1.0
+Summary: A Python library for accessing Texas Comptroller of Public Accounts tax and financial data
+Author-email: ZacTax <gavin@zactax.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/zactax/compytroller
+Project-URL: Documentation, https://github.com/zactax/compytroller/blob/main/README.md
+Project-URL: Repository, https://github.com/zactax/compytroller
+Project-URL: Bug Tracker, https://github.com/zactax/compytroller/issues
+Project-URL: Changelog, https://github.com/zactax/compytroller/blob/main/CHANGELOG.md
+Keywords: texas,comptroller,tax,sales-tax,franchise-tax,mixed-beverage-tax,socrata,open-data,government-data
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pandas>=1.5.0
+Requires-Dist: selectolax>=0.3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.4.0; extra == "docs"
+Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.20.0; extra == "docs"
+Dynamic: license-file
+
+# Compytroller
+
+A Python library for accessing Texas Comptroller of Public Accounts tax and financial data.
+
+## Overview
+
+Compytroller provides a clean, type-safe interface to Texas Comptroller data from multiple sources:
+- Socrata Open Data API (data.texas.gov)
+- Texas Comptroller web forms
+- CSV data exports
+
+The library supports:
+- Sales tax data (rates, permits, allocations, quarterly sales)
+- Franchise tax data (permit holders)
+- Mixed beverage tax data (receipts, allocations)
+
+## Installation
+
+### From PyPI (Recommended)
+
+```bash
+pip install compytroller
+```
+
+### From Source
+
+```bash
+git clone https://github.com/zactax/compytroller.git
+cd compytroller
+pip install -e .
+```
+
+### Development Installation
+
+To install with development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+from compytroller import ComptrollerClient
+
+# Initialize the client with your Socrata app token
+client = ComptrollerClient(app_token="your-app-token-here")
+
+# Get sales tax rates for a specific city
+rates = (client.sales_tax()
+    .rates()
+    .for_city("Austin")
+    .get())
+
+# Get active permits for a taxpayer
+permits = (client.sales_tax()
+    .active_permits()
+    .for_taxpayer("12345678")
+    .get())
+
+# Get franchise tax permit holders
+franchise = (client.franchise_tax()
+    .active_permit_holders()
+    .for_taxpayer("12345678")
+    .get())
+
+# Get mixed beverage gross receipts
+receipts = (client.mixed_beverage_tax()
+    .gross_receipts()
+    .for_year(2024)
+    .get())
+```
+
+## Features
+
+### Fluent Query Builder API
+All data sources support method chaining for intuitive query construction:
+
+```python
+results = (client.sales_tax()
+    .active_permits()
+    .for_city("Houston")
+    .in_county("Harris")
+    .issued_after("2024-01-01")
+    .sort_by("outlet_city", desc=True)
+    .limit(100)
+    .get())
+```
+
+### Field Enums
+Optional enums for `sort_by()` fields and categorical filters provide IDE autocompletion and eliminate magic strings:
+
+```python
+from compytroller.fields import ActivePermitField, AuthorityType
+
+# Sort by field enum instead of a raw string
+permits = (client.sales_tax()
+    .active_permits()
+    .sort_by(ActivePermitField.OUTLET_CITY)
+    .limit(100)
+    .get())
+
+# Categorical enum for filter values
+allocations = (client.sales_tax()
+    .county_spd_mta_allocations()
+    .for_type(AuthorityType.COUNTY)
+    .get())
+```
+
+All enums inherit from `str`, so raw strings continue to work everywhere.
+
+### Type-Safe Responses
+All responses are returned as Python dataclasses with full type hints:
+
+```python
+from compytroller.responses.sales_tax import ActivePermitData
+
+permits: list[ActivePermitData] = client.sales_tax().active_permits().get()
+for permit in permits:
+    print(f"{permit.taxpayer_name} - {permit.outlet_city}")
+```
+
+### Multiple Data Sources
+- **Socrata API**: Primary source for most datasets
+- **Web Scraping**: Historical allocation data via state forms
+- **CSV Downloads**: Marketplace provider lists
+
+### Comprehensive Error Handling
+Custom exceptions for clear error messages:
+
+```python
+from compytroller.exceptions import HttpError, InvalidRequest
+
+try:
+    results = client.sales_tax().rates().get()
+except HttpError as e:
+    print(f"HTTP Error {e.status_code}: {e.url}")
+except InvalidRequest as e:
+    print(f"Invalid request: {e}")
+```
+
+## Available Data Sources
+
+### Sales Tax
+- `active_permits()` - Active sales tax permits
+- `rates()` - Sales tax rate changes
+- `allocation_history()` - Historical allocation data
+- `allocation_payment_details()` - Detailed payment breakdowns
+- `single_local_allocations()` - Single local jurisdiction allocations
+- `marketplace_provider_allocations()` - Marketplace provider allocations
+- `marketplace_provider()` - Marketplace provider registry
+- `permitted_locations()` - Permitted location details
+- `direct_pay_taxpayers()` - Direct pay taxpayer list
+- `quarterly_sales_history()` - Quarterly sales by jurisdiction/industry
+- `single_local_tax_rates()` - Single local tax rates
+- `city_county_comparison_summary()` - City/county payment comparisons
+- `county_spd_mta_allocations()` - County/SPD/MTA allocations
+
+### Franchise Tax
+- `active_permit_holders()` - Active franchise tax permit holders
+
+### Mixed Beverage Tax
+- `gross_receipts()` - Gross receipts by beverage type
+- `history()` - Historical allocation data
+
+## Documentation
+
+- [API Reference](docs/API.md) - Complete API documentation
+- [Usage Examples](docs/EXAMPLES.md) - Common usage patterns
+- [Data Sources](docs/DATA_SOURCES.md) - Detailed data source reference
+- [Development Guide](docs/DEVELOPMENT.md) - Contributing and development setup
+
+## Authentication
+
+Most data sources require a Socrata app token. Get yours by creating an account on https://data.texas.gov and then navigating to https://data.texas.gov/profile/edit/developer_settings.
+
+## Requirements
+
+- Python 3.10+
+- httpx
+- pandas
+- selectolax
+
+## License
+
+See LICENSE file for details.
+
+## Contributing
+
+Contributions are welcome! See [DEVELOPMENT.md](docs/DEVELOPMENT.md) for development setup and guidelines.
+
+## Support
+
+For issues and feature requests, please use the GitHub issue tracker.

compytroller-0.1.0/README.md

@@ -0,0 +1,194 @@
+# Compytroller
+
+A Python library for accessing Texas Comptroller of Public Accounts tax and financial data.
+
+## Overview
+
+Compytroller provides a clean, type-safe interface to Texas Comptroller data from multiple sources:
+- Socrata Open Data API (data.texas.gov)
+- Texas Comptroller web forms
+- CSV data exports
+
+The library supports:
+- Sales tax data (rates, permits, allocations, quarterly sales)
+- Franchise tax data (permit holders)
+- Mixed beverage tax data (receipts, allocations)
+
+## Installation
+
+### From PyPI (Recommended)
+
+```bash
+pip install compytroller
+```
+
+### From Source
+
+```bash
+git clone https://github.com/zactax/compytroller.git
+cd compytroller
+pip install -e .
+```
+
+### Development Installation
+
+To install with development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+from compytroller import ComptrollerClient
+
+# Initialize the client with your Socrata app token
+client = ComptrollerClient(app_token="your-app-token-here")
+
+# Get sales tax rates for a specific city
+rates = (client.sales_tax()
+    .rates()
+    .for_city("Austin")
+    .get())
+
+# Get active permits for a taxpayer
+permits = (client.sales_tax()
+    .active_permits()
+    .for_taxpayer("12345678")
+    .get())
+
+# Get franchise tax permit holders
+franchise = (client.franchise_tax()
+    .active_permit_holders()
+    .for_taxpayer("12345678")
+    .get())
+
+# Get mixed beverage gross receipts
+receipts = (client.mixed_beverage_tax()
+    .gross_receipts()
+    .for_year(2024)
+    .get())
+```
+
+## Features
+
+### Fluent Query Builder API
+All data sources support method chaining for intuitive query construction:
+
+```python
+results = (client.sales_tax()
+    .active_permits()
+    .for_city("Houston")
+    .in_county("Harris")
+    .issued_after("2024-01-01")
+    .sort_by("outlet_city", desc=True)
+    .limit(100)
+    .get())
+```
+
+### Field Enums
+Optional enums for `sort_by()` fields and categorical filters provide IDE autocompletion and eliminate magic strings:
+
+```python
+from compytroller.fields import ActivePermitField, AuthorityType
+
+# Sort by field enum instead of a raw string
+permits = (client.sales_tax()
+    .active_permits()
+    .sort_by(ActivePermitField.OUTLET_CITY)
+    .limit(100)
+    .get())
+
+# Categorical enum for filter values
+allocations = (client.sales_tax()
+    .county_spd_mta_allocations()
+    .for_type(AuthorityType.COUNTY)
+    .get())
+```
+
+All enums inherit from `str`, so raw strings continue to work everywhere.
+
+### Type-Safe Responses
+All responses are returned as Python dataclasses with full type hints:
+
+```python
+from compytroller.responses.sales_tax import ActivePermitData
+
+permits: list[ActivePermitData] = client.sales_tax().active_permits().get()
+for permit in permits:
+    print(f"{permit.taxpayer_name} - {permit.outlet_city}")
+```
+
+### Multiple Data Sources
+- **Socrata API**: Primary source for most datasets
+- **Web Scraping**: Historical allocation data via state forms
+- **CSV Downloads**: Marketplace provider lists
+
+### Comprehensive Error Handling
+Custom exceptions for clear error messages:
+
+```python
+from compytroller.exceptions import HttpError, InvalidRequest
+
+try:
+    results = client.sales_tax().rates().get()
+except HttpError as e:
+    print(f"HTTP Error {e.status_code}: {e.url}")
+except InvalidRequest as e:
+    print(f"Invalid request: {e}")
+```
+
+## Available Data Sources
+
+### Sales Tax
+- `active_permits()` - Active sales tax permits
+- `rates()` - Sales tax rate changes
+- `allocation_history()` - Historical allocation data
+- `allocation_payment_details()` - Detailed payment breakdowns
+- `single_local_allocations()` - Single local jurisdiction allocations
+- `marketplace_provider_allocations()` - Marketplace provider allocations
+- `marketplace_provider()` - Marketplace provider registry
+- `permitted_locations()` - Permitted location details
+- `direct_pay_taxpayers()` - Direct pay taxpayer list
+- `quarterly_sales_history()` - Quarterly sales by jurisdiction/industry
+- `single_local_tax_rates()` - Single local tax rates
+- `city_county_comparison_summary()` - City/county payment comparisons
+- `county_spd_mta_allocations()` - County/SPD/MTA allocations
+
+### Franchise Tax
+- `active_permit_holders()` - Active franchise tax permit holders
+
+### Mixed Beverage Tax
+- `gross_receipts()` - Gross receipts by beverage type
+- `history()` - Historical allocation data
+
+## Documentation
+
+- [API Reference](docs/API.md) - Complete API documentation
+- [Usage Examples](docs/EXAMPLES.md) - Common usage patterns
+- [Data Sources](docs/DATA_SOURCES.md) - Detailed data source reference
+- [Development Guide](docs/DEVELOPMENT.md) - Contributing and development setup
+
+## Authentication
+
+Most data sources require a Socrata app token. Get yours by creating an account on https://data.texas.gov and then navigating to https://data.texas.gov/profile/edit/developer_settings.
+
+## Requirements
+
+- Python 3.10+
+- httpx
+- pandas
+- selectolax
+
+## License
+
+See LICENSE file for details.
+
+## Contributing
+
+Contributions are welcome! See [DEVELOPMENT.md](docs/DEVELOPMENT.md) for development setup and guidelines.
+
+## Support
+
+For issues and feature requests, please use the GitHub issue tracker.