Repos

repos

Read-access repositories for the kotobase database

Each repository wraps a single session and turns queries into data transfer objects. Headword lookups use the normalized form tables, meaning searches use the gloss_fts full text index, and Japanese substring searches over sentences use LIKE containment, which is reliable for kanji and kana text

Session Management

• Repositories never open their own session
• The Unit Of Work owns one session and hands the same one to every repository it exposes

AudioRepo

Bases: Repository

Queries pronunciation audio metadata and clips

for_key(key, *, kind=None)

Fetch audio metadata for a lookup key

Parameters:

Name	Type	Description	Default
key	str	The lookup key, such as a kanji or word	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

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

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

Parameters:

Name	Type	Description	Default
key	str	The lookup key, such as a kanji or word	required
reading	str | None	Restrict to a single clip reading when given	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 bundled clip that matches

Raises:

Type	Description
AudioDatabaseNotFoundError	If the optional audio pack is not installed

FuriganaRepo

Bases: Repository

Queries furigana segmentation

for_text(text_value, reading=None)

Fetch furigana for a written form

Parameters:

Name	Type	Description	Default
text_value	str	The written spelling to look up	required
reading	str | None	A specific reading to narrow the match	None

Returns:

Type	Description
list[FuriganaDTO]	The matching furigana segmentations

JLPTRepo

Bases: Repository

Queries the Tanos JLPT lists

grammar_like(query, *, limit=20)

Find JLPT grammar points whose text contains the query

Parameters:

Name	Type	Description	Default
query	str	The substring to search for in grammar points	required
limit	int	Maximum number of grammar points to return	20

Returns:

Type	Description
list[JLPTGrammarDTO]	The matching grammar points as data transfer objects

kanji_by_literal(literal)

Fetch the JLPT kanji entry for a literal

Parameters:

Name	Type	Description	Default
literal	str	The kanji character	required

Returns:

Type	Description
JLPTKanjiDTO | None	The JLPT kanji entry, or None when it is not listed

kanji_levels(literals)

Map each given kanji to its JLPT level

Parameters:

Name	Type	Description	Default
literals	Sequence[str]	The kanji to look up	required

Returns:

Type	Description
dict[str, int]	A mapping of kanji to JLPT level for those that are listed

list_grammar(level)

Return the full grammar study list for a level

Parameters:

Name	Type	Description	Default
level	int	The JLPT level from 1 to 5	required

Returns:

Type	Description
list[JLPTGrammarDTO]	Every grammar point at the level

list_kanji(level)

Return the full kanji study list for a level

Parameters:

Name	Type	Description	Default
level	int	The JLPT level from 1 to 5	required

Returns:

Type	Description
list[JLPTKanjiDTO]	Every kanji item at the level

list_vocab(level)

Return the full vocabulary study list for a level

Parameters:

Name	Type	Description	Default
level	int	The JLPT level from 1 to 5	required

Returns:

Type	Description
list[JLPTVocabDTO]	Every vocabulary item at the level

vocab_by_word(word)

Find the JLPT vocabulary entry for a word

Parameters:

Name	Type	Description	Default
word	str	The headword or reading to look up	required

Returns:

Type	Description
JLPTVocabDTO | None	The vocabulary entry, or None when the word is not listed

JMDictRepo

Bases: Repository

Repository that abstract queries for the JMdict tables

by_id(entry_id)

Fetches a single entry by its sequence number

Parameters:

Name	Type	Description	Default
entry_id	int	The JMdict sequence number	required

Returns:

Type	Description
JMDictEntryDTO | None	The entry, or None when no entry has that id

search_form(form, *, wildcard=False, limit=50)

Searches entries by a written or reading form

Parameters:

Name	Type	Description	Default
form	str	The query form, where * and % act as wildcards when wildcard is True	required
wildcard	bool	When True, treat the query as a LIKE pattern, otherwise match it exactly	False
limit	int | None	Maximum entries to return, or None for no limit	50

Returns:

Type	Description
list[JMDictEntryDTO]	The matching entries as data transfer objects

search_gloss(query, *, limit=50)

Search entries by English meaning using full text search

Parameters:

Name	Type	Description	Default
query	str	The FTS5 match expression to run against glosses	required
limit	int	Maximum number of entries to return	50

Returns:

Type	Description
list[JMDictEntryDTO]	The matching entries as data transfer objects

JMNeDictRepo

Bases: Repository

Queries the JMnedict tables

browse_by_type(name_type, *, limit=50)

Browse names that carry a given name type

Parameters:

Name	Type	Description	Default
name_type	str	The name type code such as place or surname	required
limit	int	Maximum number of entries to return	50

Returns:

Type	Description
list[JMNeDictEntryDTO]	The matching names as data transfer objects

by_id(entry_id)

Fetch a single name entry by its sequence number

Parameters:

Name	Type	Description	Default
entry_id	int	The JMnedict sequence number	required

Returns:

Type	Description
JMNeDictEntryDTO | None	The entry, or None when no entry has that id

search(form, *, wildcard=False, limit=50)

Search names by a written or reading form

Parameters:

Name	Type	Description	Default
form	str	The query form, where * and % act as wildcards when wildcard is True	required
wildcard	bool	When True, treat the query as a LIKE pattern, otherwise match it exactly	False
limit	int | None	Maximum entries to return, or None for no limit	50

Returns:

Type	Description
list[JMNeDictEntryDTO]	The matching names as data transfer objects

KanjiRepo

Bases: Repository

Queries KanjiDic2 together with radical and JLPT data

bulk_fetch(literals)

Fetch several kanji at once preserving input order

Parameters:

Name	Type	Description	Default
literals	Sequence[str]	The kanji characters to fetch	required

Returns:

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

by_literal(literal)

Fetch a single kanji with its full profile

Parameters:

Name	Type	Description	Default
literal	str	The kanji character	required

Returns:

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

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	Maximum number of kanji to return	100

Returns:

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

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

Search kanji by 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	Maximum number of kanji to return	100

Returns:

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

stroke_svg(literal, *, raw=False)

Fetch 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	The kanji character	required
raw	bool	When True, return the raw KanjiVG fragment unwrapped	False

Returns:

Type	Description
str | None	The stroke order SVG, or None when no stroke data exists

RadicalRepo

Bases: Repository

Queries radical data and performs radical search

kanji_by_radicals(radicals)

Find kanji that contain every one of the given radicals

Parameters:

Name	Type	Description	Default
radicals	Sequence[str]	The radical components to require	required

Returns:

Type	Description
list[str]	The kanji that contain all of the radicals

list_radicals()

List every search radical with its stroke count

Returns:

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

radicals_of(literal)

List the radical components of a kanji

Parameters:

Name	Type	Description	Default
literal	str	The kanji character	required

Returns:

Type	Description
list[str]	The radical components contained in the kanji

Repository

Base class for a repository bound to a database session

Attributes:

Name	Type	Description
session	Session	The session used for every query

__init__(session)

Binds the repository to a session

Parameters:

Name	Type	Description	Default
session	Session	The active session to query through	required

SentenceRepo

Bases: Repository

Queries Tatoeba example sentences and their translations

search_containing(query, *, limit=20, wildcard=False)

Find Japanese sentences containing the query text

Parameters:

Name	Type	Description	Default
query	str	The text to search for, where * and % act as wildcards when wildcard is True	required
limit	int	Maximum number of sentences to return	20
wildcard	bool	When True, treat the query as a LIKE pattern, otherwise match it as a substring	False

Returns:

Type	Description
list[SentenceDTO]	The matching sentences with any aligned translations

TagRepo

Bases: Repository

Queries the tag dictionary that expands codes to descriptions

labels(codes)

Map tag codes to their human readable descriptions

Parameters:

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

Returns:

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