compytroller 0.2.1

A Python library for accessing Texas Comptroller of Public Accounts tax and financial data

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)

pip install compytroller

From Source

git clone https://github.com/zactax/compytroller.git
cd compytroller
pip install -e .

Development Installation

To install with development dependencies:

pip install -e ".[dev]"

Quick Start

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:

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:

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:

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:

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 - Complete API documentation
• Usage Examples - Common usage patterns
• Data Sources - Detailed data source reference
• Development Guide - 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 for development setup and guidelines.

Support

For issues and feature requests, please use the GitHub issue tracker.