kessan 0.0.1

Python SDK for Kessan — Japan financial disclosure intelligence via DuckDB

kessan — Python SDK

Local DuckDB SDK for Kessan (coming soon) — Japan financial disclosure intelligence.

Which Kessan package do I need?

• kessan (this package) — Query a local DuckDB file directly. For on-prem deployments and data teams running their own pipeline. No API key required.
• kessan-client (sdk-python-http / pip install kessan-client) — HTTP client for api.kessan.io. For typical SaaS API users with an API key.

Install

pip install "kessan>=0.0.1"  # coming soon — not yet on PyPI; install from source for now
# From source: pip install duckdb>=1.0 and use the repo directly

Quickstart

Set the DB path once:

export KESSAN_DB_PATH=~/.kessan/db.duckdb

import kessan

# EDINET-only (audited annual/quarterly XBRL data — default)
rows = kessan.get_financials("E02144")
print(rows[0]["revenue"], rows[0]["src_type"])  # 48036704000000  edinet

# IR PDF only (best-effort Q1/Q3 earnings short reports — unaudited)
ir_rows = kessan.get_financials("E02144", source_types=("ir_pdf",))
print(ir_rows[0]["period_type"], ir_rows[0]["src_type"])  # Q3  ir_pdf

# UNION: both EDINET XBRL and IR PDF sources
all_rows = kessan.get_financials("E02144", source_types=("edinet", "ir_pdf"))
for r in all_rows:
    print(r["fiscal_year"], r["period_type"], r["src_type"], r["revenue"])

# Disclosure filings
filings = kessan.get_filings("E02144", doc_type=120)  # 120 = 有価証券報告書
print(filings[0]["filed_date"], filings[0]["doc_id"])

# Company search (name JP/EN, EDINET code, ticker)
hits = kessan.search_companies("トヨタ", limit=5)
print(hits[0]["name_en"], hits[0]["edinet_code"])

get_financials — source_types

source_types controls which tables are queried:

source_types	Tables queried	Notes
("edinet",)	financials	Default. EDINET XBRL, audited
("ir_pdf",)	ir_financials	Best-effort IR PDF Q1/Q3 short reports
("edinet", "ir_pdf")	Both (UNION)	Full coverage incl. post-2024 Q1/Q3

Returned columns (unified across both tables): edinet_code, ticker, fiscal_year, period_type, period_end, revenue, operating_income, ordinary_income, net_income, eps, currency, src_type, src_publisher, src_audited, src_fetched_at, src_source_url

Note: EDINET rows have period_end=None (the financials table stores only fiscal_year + period). IR PDF rows have period_end as an ISO date string.

Background: EDINET abolished Q1/Q3 quarterly filings from April 2024. IR PDF parsing fills this gap for the 10 Nikkei225 companies in the alpha cohort.

Path resolution

1. Explicit db_path= argument
2. KESSAN_DB_PATH env var
3. ~/.kessan/db.duckdb (raises FileNotFoundError if missing)

Links

• kessan.io — coming soon