Api

api

Kotobase's Public API

Kotobase is a thin, stateless wrapper over the Unit Of Work which queries the databases

Each call opens one read-only session, runs the queries it needs through the repositories and returns plain Data Transfer Objects

The queries in a lookup run sequentially on a single session, which is both simple and correct for read-only SQLite

Kotobase

Stateless entry point for querying the kotobase database

__call__(query, *, wildcard=False, include_names=False, sentence_limit=50, entry_limit=None, with_labels=False)

Run a comprehensive lookup, an alias for lookup

Parameters:

Name	Type	Description	Default
query	str	The query, written in kana or kanji	required
wildcard	bool	When True, match forms as a LIKE pattern	False
include_names	bool	When True, also search JMnedict proper names	False
sentence_limit	int | None	Maximum number of example sentences to return	50
entry_limit	int | None	Maximum number of dictionary entries to return, or None for no limit	None
with_labels	bool	When True, resolve tag codes to descriptions	False

Returns:

Type	Description
LookupResult	A LookupResult for the query

audio(key, *, kind=None)

Return pronunciation audio metadata for a lookup key

Parameters:

Name	Type	Description	Default
key	str | KanjiDTO | JMDictEntryDTO	The lookup key, such as a kanji or word, as a string or a DTO to read it from	required
kind	str | None	Restrict to a clip kind when given	None

Returns:

Type	Description
list[AudioDTO]	The matching audio clips as metadata, without the raw bytes

Raises:

Type	Description
AudioDatabaseNotFoundError	If the optional audio pack is not installed

audio_bytes(key, *, reading=None, kind=None)

Return the file name and raw bytes of each matching audio clip

Parameters:

Name	Type	Description	Default
key	str | KanjiDTO | JMDictEntryDTO	The lookup key, such as a kanji or word, as a string or a DTO to read it from	required
reading	str | None	Select a specific clip by its reading, or None to return every matching clip	None
kind	str | None	Restrict to a clip kind when given	None

Returns:

Type	Description
list[tuple[str, bytes]]	A file name and bytes pair for every matching clip, empty when nothing matches

Raises:

Type	Description
AudioDatabaseNotFoundError	If the optional audio pack is not installed

by_radicals(radicals, *, match='all')

Return the kanji that contain the given radicals

Parameters:

Name	Type	Description	Default
radicals	list[str | RadicalDTO]	The radical components to match, given as characters or RadicalDTO objects	required
match	str	all to require every radical (intersection), or any to match kanji that contain at least one (union)	'all'

Returns:

Type	Description
list[KanjiDTO]	The full details of each matching kanji

Raises:

Type	Description
APIError	If match is not all or any

db_info()

Return the build metadata recorded in the database

Returns:

Type	Description
dict[str, str]	A mapping of metadata key to value, such as the build date, schema version and database size

Raises:

Type	Description
DatabaseNotFoundError	If the database does not exist

expand_tags(codes)

Expand tag codes to their human readable descriptions

Parameters:

Name	Type	Description	Default
codes	list[str]	The tag codes to expand	required

Returns:

Type	Description
dict[str, str]	A mapping of code to description for those that are known

furigana(word, reading=None)

Return furigana segmentation for a written form

Parameters:

Name	Type	Description	Default
word	str | JMDictEntryDTO | KanjiFormDTO | KanaFormDTO	The written spelling, as text or a DTO to read it from	required
reading	str | None	A specific reading to narrow the match	None

Returns:

Type	Description
list[FuriganaDTO]	The matching furigana segmentations

jlpt_level(word)

Return the JLPT vocabulary level of a word

Parameters:

Name	Type	Description	Default
word	str | JMDictEntryDTO | JLPTVocabDTO	The word, as text or a DTO to read it from	required

Returns:

Type	Description
int | None	The JLPT level from 1 to 5, or None when the word is not listed

jlpt_list(kind, level)

Return a full Tanos JLPT study list

Parameters:

Name	Type	Description	Default
kind	str	One of vocab, kanji or grammar	required
level	int	The JLPT level from 1 to 5	required

Returns:

Type	Description
list[JLPTVocabDTO] | list[JLPTKanjiDTO] | list[JLPTGrammarDTO]	Every item of the requested kind at the level

Raises:

Type	Description
APIError	If kind is not a known JLPT list kind or level is not between 1 and 5

kanji(literal)

Return the full profile of a single kanji

Parameters:

Name	Type	Description	Default
literal	str | KanjiDTO | KanjiFormDTO	The kanji, as a character or a DTO to read it from	required

Returns:

Type	Description
KanjiDTO | None	The kanji details, or None when it is not in the database

kanji_by_skip(code, *, limit=100)

Find kanji with a given SKIP query code

Parameters:

Name	Type	Description	Default
code	str	The SKIP code such as 1-4-3	required
limit	int | None	Maximum number of kanji to return	100

Returns:

Type	Description
list[KanjiDTO]	The matching kanji as data transfer objects

lookup(query, *, wildcard=False, include_names=False, sentence_limit=50, entry_limit=None, with_labels=False)

Run a comprehensive lookup across every data source

Parameters:

Name	Type	Description	Default
query	str	The query, written in kana or kanji, where * and % act as wildcards when wildcard is True	required
wildcard	bool	When True, match forms as a LIKE pattern	False
include_names	bool	When True, also search JMnedict proper names	False
sentence_limit	int | None	Maximum number of example sentences to return	50
entry_limit	int | None	Maximum number of dictionary entries to return, or None for no limit	None
with_labels	bool	When True, resolve every tag code in the result to its human-readable description and store them on the result	False

Returns:

Type	Description
LookupResult	A LookupResult aggregating entries, names, kanji, furigana, JLPT data and example sentences

names(form=None, *, name_type=None, wildcard=False, limit=50)

Look up or browse JMnedict proper names

Parameters:

Name	Type	Description	Default
form	str | JMNeDictEntryDTO | None	A written or reading form to search for, as text or a name DTO to read it from	None
name_type	str | None	A name type to browse, such as place	None
wildcard	bool	When True, match the form as a LIKE pattern	False
limit	int | None	Maximum number of names to return	50

Returns:

Type	Description
list[JMNeDictEntryDTO]	The matching names, empty when neither a form nor a type is given

radicals()

Return every search radical with its stroke count

Returns:

Type	Description
list[RadicalDTO]	The radicals ordered by stroke count

resolve_references(source)

Resolve the cross-references and antonyms of a sense or entry

Parameters:

Name	Type	Description	Default
source	JMDictEntryDTO | SenseDTO | str	The entry or sense whose xref and antonym codes to resolve, or a single reference code	required

Returns:

Type	Description
list[JMDictEntryDTO]	The referenced entries, de-duplicated by sequence number

save_audio(key, dest, *, reading=None, kind=None)

Save the matching pronunciation audio clips into a directory

Parameters:

Name	Type	Description	Default
key	str | KanjiDTO | JMDictEntryDTO	The lookup key, such as a kanji or word, as a string or a DTO to read it from	required
dest	str | Path	The directory to write the clips into, created when it does not exist	required
reading	str | None	Save only the clip with this reading when given	None
kind	str | None	Restrict to a clip kind when given	None

Returns:

Type	Description
list[Path]	The paths of the written audio files

Raises:

Type	Description
AudioDatabaseNotFoundError	If the optional audio pack is not installed

search_kanji(*, stroke_count=None, grade=None, freq_max=None, jlpt=None, limit=100)

Search kanji by its scalar attributes

Parameters:

Name	Type	Description	Default
stroke_count	int | None	Required stroke count	None
grade	int | None	Required school grade	None
freq_max	int | None	Maximum newspaper frequency rank	None
jlpt	int | None	Required Tanos JLPT level	None
limit	int | None	Maximum number of kanji to return	100

Returns:

Type	Description
list[KanjiDTO]	The matching kanji ordered by frequency then character

search_meaning(query, *, limit=50)

Return entries whose English meaning matches the query

Parameters:

Name	Type	Description	Default
query	str	The full text search expression to run against glosses	required
limit	int | None	Maximum number of entries to return	50

Returns:

Type	Description
list[JMDictEntryDTO]	The matching dictionary entries

sentences(text_value, *, limit=20)

Return Tatoeba Japanese example sentences containing the given text

Parameters:

Name	Type	Description	Default
text_value	str | JMDictEntryDTO	The text to search for, as a string or a dictionary entry to read its headword from	required
limit	int | None	Maximum number of sentences to return	20

Returns:

Type	Description
list[SentenceDTO]	The matching example sentences

sentences_with_kanji(kanji, *, limit=20)

Return example sentences that contain a kanji

Parameters:

Name	Type	Description	Default
kanji	str | KanjiDTO	The kanji character, or a KanjiDTO to read the character from	required
limit	int | None	Maximum number of sentences to return	20

Returns:

Type	Description
list[SentenceDTO]	The matching example sentences with their translations

stroke_svg(literal, *, raw=False)

Return a kanji's stroke order as SVG

By default this returns a self-contained, browser renderable SVG document. Pass raw to get the original KanjiVG <kanji> fragment instead, which has no <svg> root or styling

Parameters:

Name	Type	Description	Default
literal	str | KanjiDTO	The kanji string or a KanjiDTO object	required
raw	bool	When True, return the raw KanjiVG fragment unwrapped	False

Returns:

Type	Description
str | None	The stroke order SVG, or None when not available

words_with_kanji(kanji, *, limit=50)

Return dictionary entries whose written form uses a kanji

Parameters:

Name	Type	Description	Default
kanji	str | KanjiDTO	The kanji character, or a KanjiDTO to read the character from	required
limit	int | None	Maximum entries to return, or None for no limit	50

Returns:

Type	Description
list[JMDictEntryDTO]	The entries that use the kanji in a written form