Metadata-Version: 2.4
Name: portugal-vehicle-tax
Version: 1.0.0
Summary: ISV + IUC Portuguese vehicle-tax calculators (import tax + annual road tax) — a maintained estimate, cross-checked against the official AT simulator.
Author-email: Clara Cars <info@claracars.pt>
License: MIT
Project-URL: Homepage, https://claracars.pt
Project-URL: Repository, https://github.com/claracarspt/calcs
Project-URL: API, https://claracars.pt/en/api
Project-URL: Bug Tracker, https://github.com/claracarspt/calcs/issues
Keywords: ISV,IUC,Portugal,vehicle tax,car import,imposto,AT,matricula,car-tax,road-tax
Classifier: License :: OSI Approved :: MIT License
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: Intended Audience :: Developers
Classifier: Natural Language :: Portuguese
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# portugal-vehicle-tax

Portuguese vehicle-tax calculators — **ISV** (*Imposto Sobre Veículos*, the one-off
import/registration tax) and **IUC** (*Imposto Único de Circulação*, the annual road tax) —
as a zero-dependency, pure-Python library.

Maintained by **[Clara Cars](https://claracars.pt)** and used in production behind the public
API at `https://claracars.pt/api/public`. Source: [claracarspt/calcs](https://github.com/claracarspt/calcs).

> **A maintained estimate, cross-checked against the official AT simulator; not the official
> AT figure.** These calculators are periodically verified against the Autoridade Tributária
> (AT) simulator and public tax tables — they are **not** the official AT number and not a
> substitute for the AT simulator or a licensed despachante. Tax tables change every year;
> verify before you rely on a euro amount.

## Install

```bash
pip install portugal-vehicle-tax
```

Requires Python 3.10+. No runtime dependencies.

## Usage

```python
from portugal_vehicle_tax import isv, iuc

# ISV — 2016 diesel, 1950 cc, 130 g/km CO2, 10.2 years old, used EU import
r = isv.compute_isv("passenger", cc=1950, co2=130, fuel="diesel",
                    age_years=10.2, year=2016, from_eu=True, used=True)
print(r["isv"])          # 1832.92
print(r["breakdown"])    # itemised like the official AT "Demonstração"

# IUC — annual road tax for the same car
print(iuc.compute(cc=1950, co2=130, fuel="diesel", year=2016)["iuc"])   # 278.85

# Electric → exempt from both
isv.compute_isv("passenger", fuel="electric")   # {'isv': 0.0, 'exempt': True, ...}
```

### ISV — `isv.compute_isv(category, cc, co2, fuel, age_years, year, ...)`

| Arg | Notes |
|---|---|
| `category` | `passenger` \| `autocaravana` \| `motorcycle` \| `van_10` \| `commercial_15/50/100` \| `pesados_mercadorias` \| `pesados_passageiros` |
| `cc` | Engine displacement (cm³) |
| `co2` | CO₂ g/km (WLTP/NEDC auto-selected by `year`) |
| `fuel` | `petrol` \| `diesel` \| `electric` \| `phev` \| `hybrid` \| `lpg` |
| `age_years` | Years since first registration (drives the Tabela D reduction) |
| `year` | First-registration year (NEDC/WLTP + PHEV cap + classic flags) |
| `from_eu`, `used` | EU import + used → age reduction eligible |
| `phev_range_km` | PHEV needs ≥50 km (+ low CO₂) for the 75% reduction |

Returns a dict with `isv`, `exempt`, `table`, `breakdown` (line-by-line AT demonstração),
`age_reduction_pct`, and a `note` where a caveat applies.

### IUC — `iuc.compute(cc, co2, fuel, year, vehicle_type="passenger")`

Categoria B (cars ≥2007, cc+CO₂), Categoria A (<2007, cc × year-band), Categoria E
(motorcycles). For goods vehicles use `iuc.compute_iuc(vehicle_type, cc, co2, fuel, year,
peso_bruto=...)` (Categorias C/D, by gross weight).

## Correctness self-check

```bash
python -m pytest -q          # or: python tests/test_calc.py
```

Ships a golden case table (petrol, diesel with age reduction, electric-exempt, the €100
minimum, PHEV reduction) frozen against the canonical Clara Cars logic. Any drift fails.

## Related

- **Live API (key-free):** `https://claracars.pt/api/public/isv?cc=1950&co2=130&fuel=diesel&year=2016` — returns both ISV and IUC.
- **JS/TS SDK:** [`portugal-vehicle-tax` on npm](https://www.npmjs.com/package/portugal-vehicle-tax)
- **PHP SDK:** [`claracars/portugal-vehicle-tax` on Packagist](https://packagist.org/packages/claracars/portugal-vehicle-tax)
- **MCP server:** [claracarspt/mcp](https://github.com/claracarspt/mcp)

MIT © Clara Cars
