Metadata-Version: 2.4
Name: itd-aisparser
Version: 0.1.1
Summary: Decrypt and parse Indian ITD Annual Information Statement (AIS) JSON locally
Project-URL: Repository, https://github.com/niladridasroy/itd-aisparser
Project-URL: Issues, https://github.com/niladridasroy/itd-aisparser/issues
Project-URL: Changelog, https://github.com/niladridasroy/itd-aisparser/blob/main/CHANGELOG.md
License-Expression: MIT
License-File: LICENSE
Keywords: ais,annual-information-statement,income-tax,india,itd,parser,tax
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.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: click<10,>=8.1
Requires-Dist: cryptography<50,>=42
Requires-Dist: pydantic<3,>=2.7
Provides-Extra: pandas
Requires-Dist: pandas>=2.0; extra == 'pandas'
Description-Content-Type: text/markdown

# aisparser

![CI](https://github.com/niladridasroy/itd-aisparser/actions/workflows/ci.yml/badge.svg)
[![PyPI](https://img.shields.io/pypi/v/itd-aisparser)](https://pypi.org/project/itd-aisparser/)
[![Python versions](https://img.shields.io/pypi/pyversions/itd-aisparser)](https://pypi.org/project/itd-aisparser/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

Parse the Indian Income Tax Department's Annual Information Statement (AIS) JSON locally
into typed, structured data. Zero network calls, in-memory decryption, and no silently
dropped data — every leaf of the decrypted file is either typed, kept verbatim in a
generic record, or reported in a redaction-safe warning.

> **Package name vs import name:** the distribution is **`itd-aisparser`**, but the
> import and the CLI are both **`aisparser`** — `pip install itd-aisparser`, then
> `import aisparser` / `aisparser summary`. The PyPI name `aisparser` is occupied by an
> abandoned maritime-AIS (ship-tracking) package, so this project ships under the
> `itd-` prefix.

## Install

```bash
pip install itd-aisparser
```

With the optional pandas DataFrame adapter:

```bash
pip install "itd-aisparser[pandas]"
```

## Quickstart

```python
from aisparser import read_ais

statement = read_ais(
    path="ABCDE1234A_2025-26_AIS_03072026.json",
    password="ABCDE1234A21011991",
)

statement.assessment_year   # "2026-27" — detected from the portal filename
statement.parse_warnings    # redaction-safe structural warnings (labels only, never values)
statement.to_dict()         # plain-dict dump of the full typed statement

# With the [pandas] extra installed:
frames = statement.to_df()  # dict of category-keyed DataFrames
```

The password is your PAN (any case) followed by your date of birth as DDMMYYYY. The
library resolves casing and the internal ITD key-derivation details automatically.

## What parses typed vs generic

| Category | AIS part | Typed model | What you get |
| --- | --- | --- | --- |
| TDS entries (salary, dividend) | Part B1 (TDS/TCS) | `TdsEntryRecord` | Per-quarter amount paid/credited plus TDS deducted and deposited as exact Decimals |
| TCS / outward foreign remittance | Part B1 (TDS/TCS) | `TcsEntryRecord` | Amount received/debited, tax collected, and TCS deposited per quarter as exact Decimals |
| Interest from savings bank | Part B2 (SFT) | `SavingsInterestRecord` | Account number and type, reporting date, and the interest amount as an exact Decimal |
| Dividend (SFT) | Part B2 (SFT) | `SftDividendRecord` | Reporting date and dividend amount as an exact Decimal, per reporting entity |
| Sale of securities and mutual fund units | Part B2 (SFT) | `SecuritiesSaleRecord` | Sale date, security identity and class, quantity, sale consideration, cost of acquisition, and FMV as Decimals |
| Purchase of securities and mutual fund units | Part B2 (SFT) | `SecuritiesPurchaseRecord` | Quarterly market purchase and sale totals per client/holder as exact Decimals |
| Payment of taxes | Part B3 | `TaxPaymentRecord` | Challan identity (BSR code, serial, CIN) with the tax/surcharge/cess breakup as Decimals |
| Refund | Part B4 | `RefundRecord` | Refund amount, mode, nature, and payment date keyed by financial year |
| Salary (Annexure II) | Part B7 (other information) | `SalaryAnnexureRecord` | Employment period and the gross-salary breakup u/s 17(1)/(2)/(3) as exact Decimals |
| Interest on income tax refund | Part B7 (other information) | `RefundInterestRecord` | Assessment-year-keyed refund-interest amounts as exact Decimals |

All other categories (57+ in the CBDT list) parse generically with verbatim field names
and redaction-safe warnings — no data is silently dropped — and reporter-level rollups
arrive typed as `CategorySummaryRecord`.

## Downloading your AIS from the portal

<!-- Portal menu labels owner-verified against the live portal: 2026-07-18 -->

1. Log in at the e-Filing portal: https://www.incometax.gov.in/
2. Open "Annual Information Statement (AIS)" from the e-File menu — the portal hands
   off to the AIS/compliance portal.
3. On the AIS tile, pick the financial year and download the **JSON** format.
4. The file arrives named `{PAN}_{FY}_AIS_{DDMMYYYY}.json` — keep this name so
   aisparser can detect the assessment year from it. The filename token is the
   *financial* year; aisparser converts FY to AY internally. A renamed file still
   works: pass `assessment_year=` in Python or `--assessment-year` on the CLI.
5. The password is your PAN followed by your date of birth as DDMMYYYY.

## CLI

```bash
aisparser summary ABCDE1234A_2025-26_AIS_03072026.json
aisparser export ABCDE1234A_2025-26_AIS_03072026.json -o out.csv
aisparser fingerprint ABCDE1234A_2025-26_AIS_03072026.json
```

- The password is read from a **hidden prompt** by default; for scripting, set the
  `AISPARSER_PASSWORD` environment variable or use `--password-file`. There is no
  `--password` argv option by design.
- `--assessment-year` overrides filename detection when the file has been renamed.
- `aisparser fingerprint` prints a redaction-safe schema fingerprint per category —
  category names and column labels only, never values — safe to paste into a GitHub
  issue.

## Privacy guarantees

- **No network:** zero network calls at runtime and no HTTP client anywhere in the
  dependency tree — see [SECURITY.md](SECURITY.md) for the auditable proof.
- **In-memory only:** decryption never touches disk; no temp files are ever written —
  see [SECURITY.md](SECURITY.md) for the enforcing test.
- **Value-free errors and warnings:** no password, PAN, or financial value ever appears
  in an error, warning, or log — see [SECURITY.md](SECURITY.md) for how this is
  asserted.

## License

MIT — see [LICENSE](LICENSE).
