itd-aisparser 0.1.1

Decrypt and parse Indian ITD Annual Information Statement (AIS) JSON locally

aisparser

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

pip install itd-aisparser

With the optional pandas DataFrame adapter:

pip install "itd-aisparser[pandas]"

Quickstart

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

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

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 for the auditable proof.
• In-memory only: decryption never touches disk; no temp files are ever written — see 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 for how this is asserted.

License

MIT — see LICENSE.