Changelog

All notable changes to this project are documented here

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning

0.4.1 - 2026-07-03

A query performance patch, no API or database changes

Fixed

• Form-Search Performance → Searching entries and proper names by a written or reading form previously compiled to correlated EXISTS subqueries that scanned every row (743k for names). The predicates are rewritten as a non-correlated id IN (... UNION ...) subquery that runs on the existing text indexes. kotobase.Kotobase.names drops from ~1.4s to ~2ms (~780x), kotobase.Kotobase.lookup from ~310ms to ~17ms, and kotobase.Kotobase.words_with_kanji from ~460ms to ~50ms. Result sets are unchanged and already-downloaded databases don't need a rebuild

0.4.0 - 2026-07-01

Richer data objects, a typed exception hierarchy, and a fix for the audio pull

Breaking Changes

• JSON Output Shape → The CLI --json output now follows Pydantic's model_dump_json. Field names are unchanged and Japanese text stays verbatim, but the exact shape may differ from 0.3.0, which 0.x SemVer allows

• DTO Serialization → The Serializable mixin and its to_dict / to_json helpers are removed, serialize the Pydantic DTOs with model_dump / model_dump_json instead

• Bad-Argument Errors → The API now raises APIError from the new hierarchy on invalid arguments instead of ValueError

Added

• Data-Facing DTO Methods → The data objects gained pure helpers such as JMDictEntryDTO.all_pos / common_kanji, SenseDTO.all_tags / expand_tags, KanjiDTO.skip_codes / is_joyo, and LookupResult.has_*

• Exception Hierarchy → A new kotobase.exceptions module rooted at KotobaseError (DatabaseError, SourceExtractionError, DownloadError, APIError and their leaves), re-exported from the top-level package

• New API Methods → words_with_kanji, sentences_with_kanji and resolve_references (each accepting a DTO or a string), plus a match argument on by_radicals to find kanji containing any of a set of radicals as well as all of them

• DTO Arguments → The key-taking methods now accept a DTO as well as a string, reading the lookup key off the object, so a result from one call can be passed straight into another (e.g. sentences(entry), stroke_svg(kanji))

• Test Suite → A pytest suite run against a tiny fixture database, with coverage reported to Codecov across Python 3.10 to 3.13

Changed

• Pydantic DTOs → The data objects are now Pydantic models that carry data-facing behaviour and are built with model_validate straight from the ORM rows

• Typed Errors → Repositories wrap unexpected database failures as DatabaseError, and the build pipeline raises DownloadError / SourceExtractionError. The CLI renders any KotobaseError as a friendly message instead of a traceback

Fixed

• Audio Pull → kotobase db pull previously rebuilt the audio database locally from the Kanji Alive sources instead of pulling the pre-built kotobase-audio.db.zst release asset

0.3.0 - 2026-06-26

A full rewrite of the package, its data and its tooling

0.2.7 shipped a flatter database covering JMdict, JMnedict, KanjiDic2, Japanese-Only Tatoeba sentences and the Tanos JLPT lists, distributed through Google Drive

Added

• New Data Sources → KRADFILE / RADKFILE for kanji to radical decomposition and radical search, JmdictFurigana for per-form furigana, KanjiVG for stroke-order SVG, and an optional Kanji Alive pronunciation audio pack

• Tatoeba → Now imports the links and English exports as well, aligning Japanese sentences with their English translations

• Full JMdict + JMnedict Tag Extraction → part of speech, register (slang, colloquial, ...), field, dialect and priority tags that the previous subset discarded

• New API Methods On Kotobase → search_kanji, kanji_by_skip, stroke_svg, radicals, by_radicals, jlpt_list, names, furigana, audio, audio_bytes, save_audio, search_meaning and expand_tags

• New CLI Commands Grouped Into lookup, db and cache → lookup all, kanji-find, radicals, jlpt-list, names, meaning, sentences, furigana, kanji-svg, audio, cache path / size / clear

• dev + docs Optional-Dependency Extras → ruff / mypy / pre-commit tooling, and a shipped py.typed marker

Changed

• The CLI is rebuilt on Typer and Rich, with panelled output and --json on query commands. The entry point moved from kotobase.cli:main to kotobase.cli:app

• The database is distributed through GitHub Releases as zstandard-compressed assets, rebuilt weekly, replacing the Google Drive distribution

• The schema is normalized (child tables and a JSON column for read-only tag blobs) instead of the previous flat tables with delimited-string columns, and the build streams the raw EDRDG and Tatoeba sources straight into SQLite

• Reads go through a thread-safe, read-only engine and return immutable, serializable data objects built with from_orm classmethods

• The package is consolidated under db/ (connection, dtos, repos, uow, models, builder). The old core/, repos/ and db_builder/ packages and db/database.py were restructured into it

• The minimum Python version is raised to 3.10, with a modernized pyproject.toml (full metadata and classifiers, including Typing :: Typed)

Removed

• The Google Drive distribution and the gdown dependency

• The alembic dependency. The compiled database now records its format in a db_meta schema version instead of migrations

• The click dependency, replaced by Typer

• MANIFEST.in, replaced by declarative package data

0.2.7 - 2025-06-27

The final release of the original line

Had a flatter SQLite database distributed through Google Drive and queried with a Click CLI

The changelog for this and piror releases is documented only in the GitHub Releases section