Dtos

dtos

Defines Kotobase's Data-Transfer-Objects

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

Serialization

Every object inherits from Serializable, which adds to_dict, to_json and iteration to every DTO

ORM Mapping

• Each object exposes a from_orm classmethod that builds it from a loaded ORM row

• Nested objects delegate to each other, so JMDictEntryDTO.from_orm builds its senses through SenseDTO.from_orm and so on

• The classmethods expect the relationships they read to be eagerly-loaded , which is done by the Repositories

AudioDTO dataclass

Bases: Serializable

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

from_orm(row) classmethod

Build audio metadata from an ORM audio row

Parameters:

Name	Type	Description	Default
row	Audio	The ORM audio row	required

Returns:

Type	Description
AudioDTO	The row as a data transfer object, without the raw bytes

FuriganaDTO dataclass

Bases: Serializable

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

from_orm(row) classmethod

Build a furigana object from an ORM furigana row

Parameters:

Name	Type	Description	Default
row	Furigana	The ORM furigana row	required

Returns:

Type	Description
FuriganaDTO	The row as a data transfer object

GlossDTO dataclass

Bases: Serializable

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

from_orm(gloss) classmethod

Build a gloss from an ORM gloss row

Parameters:

Name	Type	Description	Default
gloss	JMDictGloss	The ORM gloss row	required

Returns:

Type	Description
GlossDTO	The gloss as a data transfer object

JLPTGrammarDTO dataclass

Bases: Serializable

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

from_orm(row) classmethod

Build a JLPT grammar point from an ORM row

Parameters:

Name	Type	Description	Default
row	JlptGrammar	The ORM JLPT grammar row	required

Returns:

Type	Description
JLPTGrammarDTO	The row as a data transfer object

JLPTKanjiDTO dataclass

Bases: Serializable

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

from_orm(row) classmethod

Build a JLPT kanji item from an ORM row

Parameters:

Name	Type	Description	Default
row	JlptKanji	The ORM JLPT kanji row	required

Returns:

Type	Description
JLPTKanjiDTO	The row as a data transfer object

JLPTVocabDTO dataclass

Bases: Serializable

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

from_orm(row) classmethod

Build a JLPT vocabulary item from an ORM row

Parameters:

Name	Type	Description	Default
row	JlptVocab	The ORM JLPT vocabulary row	required

Returns:

Type	Description
JLPTVocabDTO	The row as a data transfer object

JMDictEntryDTO dataclass

Bases: Serializable

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

from_orm(entry) classmethod

Build an entry from an ORM entry row

Parameters:

Name	Type	Description	Default
entry	JMDictEntry	The ORM entry with its forms and senses eagerly-loaded	required

Returns:

Type	Description
JMDictEntryDTO	The entry as a data transfer object

JMNeDictEntryDTO dataclass

Bases: Serializable

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

from_orm(entry) classmethod

Build a name entry from an ORM entry row

Parameters:

Name	Type	Description	Default
entry	JMnedictEntry	The ORM entry with its forms and translations eagerly-loaded	required

Returns:

Type	Description
JMNeDictEntryDTO	The entry as a data transfer object

KanaFormDTO dataclass

Bases: Serializable

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

from_orm(form) classmethod

Build a kana form from an ORM kana form row

Parameters:

Name	Type	Description	Default
form	JMDictKana	The ORM kana form row	required

Returns:

Type	Description
KanaFormDTO	The form as a data transfer object

KanjiDTO dataclass

Bases: Serializable

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

from_orm(kanji, *, radicals=(), jlpt_tanos=None) classmethod

Build a kanji profile from an ORM kanji row

Parameters:

Name	Type	Description	Default
kanji	Kanji	The ORM kanji with its readings, meanings, nanori, dic refs, query codes, variants, codepoints and stroke data eagerly-loaded	required
radicals	Sequence[str]	Radical components for the kanji, which are not a direct relationship and so are passed in	()
jlpt_tanos	int | None	The Tanos JLPT level when known	None

Returns:

Type	Description
KanjiDTO	The kanji as a data transfer object

KanjiFormDTO dataclass

Bases: Serializable

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

from_orm(form) classmethod

Build a kanji form from an ORM kanji form row

Parameters:

Name	Type	Description	Default
form	JMDictKanji	The ORM kanji form row	required

Returns:

Type	Description
KanjiFormDTO	The form as a data transfer object

LookupResult dataclass

Bases: Serializable

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_jlpt()

Report whether the result carries any JLPT information

Returns:

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

NameTranslationDTO dataclass

Bases: Serializable

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

from_orm(block) classmethod

Build a translation block from an ORM translation row

Parameters:

Name	Type	Description	Default
block	JMnedictTranslation	The ORM translation block with its glosses loaded	required

Returns:

Type	Description
NameTranslationDTO	The translation block as a data transfer object

RadicalDTO dataclass

Bases: Serializable

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

from_orm(row) classmethod

Build a radical from an ORM radical row

Parameters:

Name	Type	Description	Default
row	Radical	The ORM radical row	required

Returns:

Type	Description
RadicalDTO	The row as a data transfer object

SenseDTO dataclass

Bases: Serializable

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

from_orm(sense) classmethod

Build a sense from an ORM sense row

Parameters:

Name	Type	Description	Default
sense	JMDictSense	The ORM sense row with its glosses loaded	required

Returns:

Type	Description
SenseDTO	The sense as a data transfer object

SentenceDTO dataclass

Bases: Serializable

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

from_orm(row, *, translations=()) classmethod

Build a sentence from an ORM sentence row

Parameters:

Name	Type	Description	Default
row	Sentence	The ORM sentence row	required
translations	Sequence[str]	Aligned translation texts when known	()

Returns:

Type	Description
SentenceDTO	The row as a data transfer object

Serializable

Mixin that adds dict + JSON serialization to a python dataclass

__iter__()

Iterates over the object's fields as key and value pairs

Yields:

Type	Description
tuple[str, Any]	Each field name paired with its value

to_dict()

Converts the object to a plain dictionary

Returns:

Type	Description
dict[str, Any]	A nested dictionary of the dataclass fields

to_json(**json_kwargs)

Converts the object to a JSON string

Parameters:

Name	Type	Description	Default
**json_kwargs	Any	Extra keyword arguments forwarded to json.dumps	{}

Returns:

Type	Description
str	The object encoded as compact JSON with non-ASCII characters kept verbatim