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.
