Dtos

dtos

Defines Kotobase's Data-Transfer-Objects

The DTOs are the boundary between the database and the public API. Repositories return them rather than ORM rows so that callers get plain, immutable, serializable values that don't depend on an open session

Serialization

Every DTO is a Pydantic model, serialize it with Pydantic's own model_dump / model_dump_json, which keep Japanese text verbatim

ORM Mapping

• ORM-backed DTOs inherit from SafeORMModel and are built with model_validate, reading attributes straight from a loaded ORM row

• A model validator replaces any relationship that wasn't eagerly loaded with None, so validation never triggers a lazy load, and overlays values passed through the validation context for fields that aren't plain ORM attributes, such as a kanji's radicals

• The Repositories eagerly load the relationships each DTO reads

KotobaseDTO = GlossDTO | SenseDTO | KanjiFormDTO | KanaFormDTO | JMDictEntryDTO | NameTranslationDTO | JMNeDictEntryDTO | KanjiDTO | FuriganaDTO | SentenceDTO | JLPTVocabDTO | JLPTKanjiDTO | JLPTGrammarDTO | RadicalDTO | AudioDTO | LookupResult module-attribute

Represents any one of Kotobase's data transfer objects

AudioDTO

Bases: SafeORMModel

Metadata for a pronunciation audio clip

Attributes:

Name	Type	Description
kind	str	What the clip pronounces, such as kanji_word
key	str	Lookup key for the clip
reading	str | None	The reading the clip pronounces when relevant
fmt	str | None	Audio container or codec such as mp3
source	str	Name of the upstream source
license	str | None	License identifier for the clip
attribution	str | None	Required attribution text or link

FuriganaDTO

Bases: SafeORMModel

Furigana segmentation for a spelling and reading pair

Attributes:

Name	Type	Description
text	str	The written spelling
reading	str	The full kana reading
segments	list[dict]	Alignment of spelling spans to their readings

GlossDTO

Bases: SafeORMModel

A single translation of a JMdict sense

Attributes:

Name	Type	Description
text	str	The translated text
lang	str	ISO 639 language code of the gloss
gender	str | None	Grammatical gender when given
gtype	str | None	Gloss type such as lit, fig, expl or tm

JLPTGrammarDTO

Bases: SafeORMModel

A Tanos JLPT grammar point

Attributes:

Name	Type	Description
level	int	JLPT level from 1 to 5
grammar	str	The grammar point
formation	str | None	How the grammar point is formed
examples	list[str]	Example sentences

JLPTKanjiDTO

Bases: SafeORMModel

A Tanos JLPT kanji item

Attributes:

Name	Type	Description
level	int	JLPT level from 1 to 5
kanji	str	The kanji character
on_yomi	str | None	On readings
kun_yomi	str | None	Kun readings
meaning	str | None	The English meaning

key property

Return the lookup key for this JLPT kanji item

Returns:

Type	Description
str	The kanji character

JLPTVocabDTO

Bases: SafeORMModel

A Tanos JLPT vocabulary item

Attributes:

Name	Type	Description
level	int	JLPT level from 1 to 5
word	str | None	The headword
reading	str | None	The kana reading
meaning	str | None	The English meaning

key property

Return the lookup key for this JLPT vocabulary item

Returns:

Type	Description
str	The headword, falling back to the reading, or an empty string

JMDictEntryDTO

Bases: SafeORMModel

One JMdict dictionary entry

Attributes:

Name	Type	Description
id	int	The JMdict sequence number
is_common	bool	True when the entry is marked common
freq_rank	int | None	Frequency band where a lower value is more frequent
kanji	list[KanjiFormDTO]	Written forms of the entry
kana	list[KanaFormDTO]	Reading forms of the entry
senses	list[SenseDTO]	Meanings of the entry

headword property

Returns the primary written form of the entry

Returns:

Type	Description
str	The first kanji form when present, otherwise the first reading

key property

Return the lookup key for this entry

Returns:

Type	Description
str	The entry's headword

all_pos()

Return the unique part-of-speech codes used across every sense

Returns:

Type	Description
list[str]	The part-of-speech codes in first-seen order, without duplicates

common_kana()

Return only the reading forms flagged common

Returns:

Type	Description
list[KanaFormDTO]	The kana forms whose is_common is True

common_kanji()

Return only the written forms flagged common

Returns:

Type	Description
list[KanjiFormDTO]	The kanji forms whose is_common is True

senses_with_pos(code)

Return the senses that carry a given part-of-speech code

Parameters:

Name	Type	Description	Default
code	str	The part-of-speech tag code to match	required

Returns:

Type	Description
list[SenseDTO]	The senses whose pos contains the code

JMNeDictEntryDTO

Bases: SafeORMModel

One JMnedict proper name entry

Attributes:

Name	Type	Description
id	int	The JMnedict sequence number
kanji	list[str]	Written forms of the name
kana	list[str]	Reading forms of the name
translations	list[NameTranslationDTO]	Translation blocks

headword property

Returns the primary written form of the name

Returns:

Type	Description
str	The first kanji form when present, otherwise the first reading

key property

Return the lookup key for this name entry

Returns:

Type	Description
str	The name entry's headword

KanaFormDTO

Bases: SafeORMModel

A reading form of a JMdict entry

Attributes:

Name	Type	Description
text	str	The kana reading
is_common	bool	True when the reading carries a common priority marker
no_kanji	bool	True when the reading applies to no kanji form
restrictions	list[str]	Kanji forms the reading is limited to
info	list[str]	Reading information tag codes
priority	list[str]	Priority code list

key property

Return the lookup key for this kana form

Returns:

Type	Description
str	The kana reading text

KanjiDTO

Bases: SafeORMModel

A kanji with its full KanjiDic2 and KanjiVG profile

Attributes:

Name	Type	Description
literal	str	The kanji character
grade	int | None	School grade in which it is taught
stroke_count	int | None	Accepted stroke count
freq	int | None	Newspaper frequency rank
jlpt_old	int | None	Pre 2010 JLPT class from KanjiDic2
jlpt_tanos	int | None	JLPT level from the Tanos lists
onyomi	list[str]	On readings
kunyomi	list[str]	Kun readings
nanori	list[str]	Name only readings
pinyin	list[str]	Mandarin pinyin readings
korean	list[str]	Korean readings
meanings	list[str]	English meanings
radicals	list[str]	Radical components of the kanji
dic_refs	dict[str, str]	Dictionary references keyed by type, such as nelson_c or heisig
query_codes	dict[str, list[str]]	Lookup codes keyed by type, such as skip and four_corner
codepoints	dict[str, str]	Encoding codepoints keyed by type
variants	list[dict[str, Any]]	Variant form references with their type and value
has_stroke_order	bool	True when KanjiVG stroke data is available

key property

Return the lookup key for this kanji

Returns:

Type	Description
str	The kanji literal character

four_corner_codes()

Return the Four Corner query codes for the kanji

Returns:

Type	Description
list[str]	The Four Corner codes, or an empty list when none are recorded

is_joyo()

Report whether the kanji is in the Joyo set

Returns:

Type	Description
bool	True when the KanjiDic grade is 1 through 8

primary_kunyomi()

Return the first kun reading

Returns:

Type	Description
str | None	The first kun reading, or None when there are none

primary_onyomi()

Return the first on reading

Returns:

Type	Description
str | None	The first on reading, or None when there are none

skip_codes()

Return the SKIP query codes for the kanji

Returns:

Type	Description
list[str]	The SKIP codes, or an empty list when none are recorded

KanjiFormDTO

Bases: SafeORMModel

A written form of a JMdict entry

Attributes:

Name	Type	Description
text	str	The kanji spelling
is_common	bool	True when the form carries a common priority marker
info	list[str]	Spelling information tag codes
priority	list[str]	Priority code list

key property

Return the lookup key for this kanji form

Returns:

Type	Description
str	The kanji spelling text

Keyed

Bases: Protocol

Interface for a DTO that carries its own lookup key

The public API accepts these DTOs anywhere a string key is expected and reads the key straight off the object, so a result from one call can be passed into another without unpacking a field by hand

key property

Return the DTO's natural lookup key

Returns:

Type	Description
str	The key string, such as a kanji literal or an entry's headword

LookupResult

Bases: BaseModel

The aggregated result of a comprehensive word lookup

Attributes:

Name	Type	Description
query	str	The query that produced the result
entries	list[JMDictEntryDTO]	Matching dictionary entries
names	list[JMNeDictEntryDTO]	Matching proper names
kanji	list[KanjiDTO]	Details for each kanji in the query
furigana	list[FuriganaDTO]	Furigana for the matched forms
jlpt_vocab	JLPTVocabDTO | None	JLPT vocabulary entry for the word
jlpt_kanji_levels	dict[str, int]	JLPT level per kanji in the query
jlpt_grammar	list[JLPTGrammarDTO]	JLPT grammar points matching the query
sentences	list[SentenceDTO]	Example sentences containing the query
labels	dict[str, str]	Tag code to human description map, populated only when labels are requested

has_entries()

Report whether the result carries any dictionary entries

Returns:

Type	Description
bool	True when at least one JMdict entry matched

has_jlpt()

Report whether the result carries any JLPT information

Returns:

Type	Description
bool	True when a JLPT vocabulary entry or kanji level is present

has_kanji()

Report whether the result carries any kanji details

Returns:

Type	Description
bool	True when at least one kanji profile is present

has_names()

Report whether the result carries any proper names

Returns:

Type	Description
bool	True when at least one JMnedict name matched

has_sentences()

Report whether the result carries any example sentences

Returns:

Type	Description
bool	True when at least one Tatoeba sentence matched

NameTranslationDTO

Bases: SafeORMModel

A translation block of a JMnedict name

Attributes:

Name	Type	Description
name_type	list[str]	Name type tag codes such as place or surname
translations	list[str]	The translated names
xref	list[str]	Cross references to related entries

RadicalDTO

Bases: SafeORMModel

A search radical and its stroke count

Attributes:

Name	Type	Description
radical	str	The radical character
stroke_count	int | None	Number of strokes in the radical

key property

Return the lookup key for this radical

Returns:

Type	Description
str	The radical character

SafeORMModel

Bases: BaseModel

Pydantic base model for ORM-backed DTOs that tolerates unloaded relationships

Validates directly from SQLAlchemy instances (from_attributes), but first replaces any relationship field that wasn't eagerly loaded with None instead of triggering a lazy load, and overlays any values supplied through the validation context

check_sqlalchemy_state(data, info) classmethod

Builds a validation-safe mapping from a SQLAlchemy instance

Reads each field from its ORM attribute (honoring a field's validation alias), maps unloaded relationships to None so that validation never triggers a lazy load, then overlays any matching keys from the validation context. Inputs that aren't SQLAlchemy instances are returned unchanged

Parameters:

Name	Type	Description	Default
data	Any	The value being validated (ORM instance or mapping)	required
info	ValidationInfo	Validation context carrying injected fields	required

Returns:

Type	Description
Any	A mapping safe for Pydantic validation, or data unchanged when it isn't a SQLAlchemy instance

SenseDTO

Bases: SafeORMModel

One meaning of a JMdict entry with its glosses and tags

Attributes:

Name	Type	Description
glosses	list[GlossDTO]	The translations of the sense
pos	list[str]	Part of speech tag codes
field	list[str]	Field of application tag codes
misc	list[str]	Register tag codes such as sl for slang
dialect	list[str]	Dialect tag codes
info	list[str]	Free text sense notes
xref	list[str]	Cross references to related entries
antonym	list[str]	Antonym references
lsource	list[dict]	Source language records for loanwords

all_tags()

Return every tag code attached to the sense

Returns:

Type	Description
list[str]	The pos, field, misc and dialect codes concatenated in that order

expand_tags(labels)

Resolve the sense's tag codes to human descriptions

Parameters:

Name	Type	Description	Default
labels	dict[str, str]	A code to description map, such as the one on LookupResult.labels	required

Returns:

Type	Description
list[str]	One description per tag code, falling back to the raw code when it isn't present in the map

SentenceDTO

Bases: SafeORMModel

A Tatoeba example sentence with its translations

Attributes:

Name	Type	Description
id	int	The Tatoeba sentence identifier
text	str	The sentence text
lang	str	ISO 639 language code of the sentence
translations	list[str]	Aligned translations in other languages