pythainlp.khavee

The pythainlp.khavee module is a powerful toolkit designed for working with Thai poetry. The term “khavee” corresponds to “กวี” in the Thai language, which translates to “Poetry” in English. This toolkit equips users with the tools and utilities necessary for the creation, analysis, and verification of Thai poetry.

Modules

KhaveeVerifier

class pythainlp.khavee.KhaveeVerifier[source]

Verifier for Thai poetry (ฉันทลักษณ์) principles.

Provides methods to analyze Thai words and validate poetic structures according to traditional Thai prosody rules. This class checks vowel sounds (สระ), spelling sections (มาตราตัวสะกด), rhymes (สัมผัส), syllable weight (ครุ/ลหุ), and full Thai klon 4/8 poem structure (กลอน).

This class is designed to be deterministic according to the Royal Society of Thailand’s orthographic standards. The only exception is the use of “ssg” for syllable segmentation in the check_klon() method.

Key capabilities: - check_sara() -> Identify the phonetic vowel sound of a Thai word, handling complex vowels (สระประสม), transformed vowels (สระเปลี่ยนรูป), and reduced vowels (สระลดรูป). - check_marttra() -> Determine the orthographic spelling section (relative to the final consonant) per Royal Society standards. - is_sumpus() -> Evaluate whether two words rhyme by comparing both vowel sound and spelling section, with phonetic normalisation for สระเกิน (e.g., อำ, ไอ). - check_karu_lahu() -> Classify a syllable as heavy (ครุ) or light (ลหุ) for meter analysis. - check_klon() -> Validate an entire poem against traditional กลอนสี่ (4-syllable) or กลอนแปด (8-syllable) rhyme rules. - check_aek_too() -> Identify tonal marks (เอก/โท) on Thai words. - handle_karun_sound_silence() -> Strip characters silenced by the การันย์ marker (e.g., “โอห์ม” → “โอ”). - _has_true_final_yl() and _is_true_final() -> Determine whether a word-ending “ย” or “ล” is a genuine final consonant rather than part of an initial cluster or vowel digraph.

Example:

Basic usage:

>>> from pythainlp.khavee import KhaveeVerifier
>>> kv = KhaveeVerifier()
>>> kv.check_sara("เริง")
'เออ'
>>> kv.is_sumpus("สรร", "อัน")
True
>>> kv.check_klon(
...     'ฉันชื่อหมูกรอบ ฉันชอบกินไก่ แล้ววิ่งตามไป ไล่หมาน้ำทอง',
...     k_type=4
... )
'The poem is correct according to the principle.'

Note:

The method check_klon() requires the external ssg library.

VALID_CONSONANTS = frozenset({'ก', 'ข', 'ฃ', 'ค', 'ฅ', 'ฆ', 'ง', 'จ', 'ฉ', 'ช', 'ซ', 'ฌ', 'ญ', 'ฎ', 'ฏ', 'ฐ', 'ฑ', 'ฒ', 'ณ', 'ด', 'ต', 'ถ', 'ท', 'ธ', 'น', 'บ', 'ป', 'ผ', 'ฝ', 'พ', 'ฟ', 'ภ', 'ม', 'ย', 'ร', 'ฤ', 'ล', 'ฦ', 'ว', 'ศ', 'ษ', 'ส', 'ห', 'ฬ', 'อ', 'ฮ'})

__init__() → None[source]: Initialize the KhaveeVerifier class.

check_sara(word: str) → str[source]

Check the phonetic vowel sound (สระ) of a Thai word.

Extracts the core vowel representation used for rhyme matching, handling complex vowel combinations, transformed vowels (สระเปลี่ยนรูป), and reductions (สระลดรูป).

Parameters:

word (str) – Thai word

Returns:

The name of the vowel sound of the word (e.g., ‘เออ’, ‘อะ’, ‘เอาะ’)

Return type:

str

Example:

>>> from pythainlp.khavee import KhaveeVerifier
>>> kv = KhaveeVerifier()
>>> print(kv.check_sara("เริง"))
'เออ'

check_marttra(word: str) → str[source]

Check the spelling section (มาตราตัวสะกด) of a Thai word.

Note: This function strictly adheres to orthographic spelling (รูป) based on the Royal Society of Thailand (ราชบัณฑิตยสภา) standards, rather than phonetics (เสียง). Therefore, words ending in สระเกิน (อำ, ไอ, ใอ, เอา) as well as ฤ, ฤๅ, ฦ, ฦๅ are correctly classified grammatically as แม่ ก กา (“กา”). Phonetic rhyming for these vowels is handled dynamically in the is_sumpus function.

Parameters:

word (str) – Thai word

Returns:

name of the spelling section of the word (e.g., กา, กก, กด, กน, กบ, กม, เกย, เกอว)

Return type:

str

Example:

>>> from pythainlp.khavee import KhaveeVerifier
>>> kv = KhaveeVerifier()
>>> print(kv.check_marttra("สาว"))
'เกอว'
>>> print(kv.check_marttra("ทำ"))
'กา'

is_sumpus(word1: str, word2: str) → bool[source]

Check the rhyme (สัมผัส) between two Thai words.

This function evaluates both the vowel sound (สระ) and the spelling section (มาตราตัวสะกด). It incorporates phonetic normalization for สระเกิน (อำ, ไอ, ใอ) to ensure that words with matching sounds but differing orthographies (e.g., “จำ” and “กรรม”) are correctly evaluated as rhymes.

Parameters:

word1 (str) – First Thai word
word2 (str) – Second Thai word

Returns:

True if the words rhyme, False otherwise.

Return type:

bool

Example:

>>> from pythainlp.khavee import KhaveeVerifier
>>> kv = KhaveeVerifier()
>>> print(kv.is_sumpus("สรร", "อัน"))
True
>>> print(kv.is_sumpus("จำ", "กรรม"))
True

check_karu_lahu(text: str) → str | bool[source]

Classify a Thai syllable as heavy (ครุ karu) or light (ลหุ lahu).

Syllable weight is determined by Thai prosody rules for classical poetry:

A syllable is heavy (ครุ) if it contains a long vowel, ends with any final consonant (including sonorant finals / นมยวง), or contains one of the special inherently bound vowels (อำ, ไอ, ใอ, เอา).
A syllable is light (ลหุ) if it is an open syllable (แม่ ก กา) containing a short vowel with no final consonant.

Args:: text (str): A single Thai syllable or word to classify.
Returns:: Union[str, bool]: “karu” for heavy syllables or “lahu” for light syllables. or False if the input is an empty string.

check_klon(text: str, k_type: int = 8) → list[str] | str[source]

Check the suitability of the poem according to Thai principles.

Parameters:

text (str) – Thai poem
k_type (int) – type of Thai poem (4 or 8)

Returns:

the check results of the suitability of the poem according to Thai principles.

Return type:

Union[list[str], str]

════════════════════════════════════════════════════════════════════════

กลอนสี่ (Klon 4) Diagram: วรรคที่ ๑ (สดับ) วรรคที่ ๒ (รับ) วรรคที่ ๓ (รอง) วรรคที่ ๔ (ส่ง)

┏━━━━━━━━┯━┓ [สัมผัสคำที่ 1 หรือ 2]

O O O X X X O O: ┏━━━━━━━━┯━┳━━━┛
O O O X X X O X ━┓: ┏━━━━━━━━┯━┓ ┃ สัมผัสระหว่างบท (Inter-stanza rhyme)
O O O X X X O O ━┛: ┏━━━━━━━━┯━┳━━━┛

O O O X X X O X

════════════════════════════════════════════════════════════════════════

กลอนแปด (Klon 8) Diagram: วรรคที่ ๑ (สดับ) วรรคที่ ๒ (รับ) วรรคที่ ๓ (รอง) วรรคที่ ๔ (ส่ง)

┏━━━━━━━━┯━┯━┳━┯━┑ [สัมผัสคำที่ 3 หรือ 5 / อนุโลม 1,2,4]

O O O O O O O X O O X O O O O X: ┏━━━━━━━━┯━┯━┳━┯━━━━━━━┛
O O O O O O O X O O X O O O O X ━┓: ┏━━━━━━━━┯━┯━┳━┯━┑ ┃ สัมผัสระหว่างบท (Inter-stanza rhyme)
O O O O O O O X O O X O O O O X ━┛: ┏━━━━━━━━┯━┯━┳━┯━━━━━━━┛

O O O O O O O X O O X O O O O X

════════════════════════════════════════════════════════════════════════

Example:

>>> from pythainlp.khavee import KhaveeVerifier
>>> kv = KhaveeVerifier()
>>> print(kv.check_klon(
...     'ฉันชื่อหมูกรอบ ฉันชอบกินไก่ แล้ววิ่งตามไป ไล่หมาน้ำทอง             ...     ฉันมันคนเก่ง เอ๋งเอ๋งคะนอง มีคนจับจอง เป็นของน้องเธียร',             ...     k_type=4
... ))
The poem is correct according to the principle.

check_aek_too(text: list[str] | str, dead_syllable_as_aek: bool = False) → list[bool | str] | bool | str[source]

Checker of Thai tonal words

Parameters:

text (Union[list[str], str]) – Thai word or list of Thai words
dead_syllable_as_aek (bool) – if True, dead syllable will be considered as aek

Returns:

the check result if the word is aek or too or False (not both) or list of check results if input is list

Return type:

Union[list[bool], List[str], bool, str]

Example:

>>> from pythainlp.khavee import KhaveeVerifier

>>> kv = KhaveeVerifier()

>>> # การเช็คคำเอกโท
>>> print(
...     kv.check_aek_too("เอง"),
...     kv.check_aek_too("เอ่ง"),
...     kv.check_aek_too("เอ้ง"),
... )
>>> # -> False, aek, too
>>> print(kv.check_aek_too(["เอง", "เอ่ง", "เอ้ง"]))
>>> # -> [False, 'aek', 'too']  ^^^^^^^^^^ # ใช้ List ได้เหมือนกัน

handle_karun_sound_silence(word: str) → str[source]

Handle silent sounds in Thai words using ‘-์’ character (Karun) by stripping all characters before the ‘Karun’ character that should be silenced

Parameters:: word (str) – Thai word
Returns:: Thai word with silent consonant stripped
Return type:: str

__annotations__ = {'_EXPLICIT_SARA_WORDS': 'frozenset[str]', '_KOB_CHARS': 'frozenset[str]', '_KOD_CHARS': 'frozenset[str]', '_KOK_CHARS': 'frozenset[str]', '_KON_CHARS': 'frozenset[str]', '_LAHU_SYLLABLE_OVERRIDES': 'frozenset[str]', '_LAM_CLUSTERS': 'frozenset[str]', '_LONG_VOWELS': 'frozenset[str]', '_MASKING_TERMINAL_VOWELS': 'tuple[str, ...]', '_OPEN_SYLLABLE_VOWELS': 'frozenset[str]', '_RUA_CLUSTERS': 'frozenset[str]', '_SINGLE_CHAR_WORDS': 'frozenset[str]', '_SPECIAL_VOWELS': 'frozenset[str]', '_WA_CLUSTERS': 'frozenset[str]', '_WA_WHITELIST': 'frozenset[str]'}

__dict__ = mappingproxy({'__module__': 'pythainlp.khavee.core', '__annotations__': {'_MASKING_TERMINAL_VOWELS': 'tuple[str, ...]', '_LAHU_SYLLABLE_OVERRIDES': 'frozenset[str]', '_SINGLE_CHAR_WORDS': 'frozenset[str]', '_LAM_CLUSTERS': 'frozenset[str]', '_RUA_CLUSTERS': 'frozenset[str]', '_WA_CLUSTERS': 'frozenset[str]', '_WA_WHITELIST': 'frozenset[str]', '_OPEN_SYLLABLE_VOWELS': 'frozenset[str]', '_KOK_CHARS': 'frozenset[str]', '_KOD_CHARS': 'frozenset[str]', '_KON_CHARS': 'frozenset[str]', '_KOB_CHARS': 'frozenset[str]', '_LONG_VOWELS': 'frozenset[str]', '_SPECIAL_VOWELS': 'frozenset[str]', '_EXPLICIT_SARA_WORDS': 'frozenset[str]'}, '__doc__': '\n Verifier for Thai poetry (ฉันทลักษณ์) principles.\n\n Provides methods to analyze Thai words and validate poetic structures\n according to traditional Thai prosody rules. This class checks vowel\n sounds (สระ), spelling sections (มาตราตัวสะกด), rhymes (สัมผัส),\n syllable weight (ครุ/ลหุ), and full Thai klon 4/8 poem structure (กลอน).\n\n This class is designed to be deterministic according to the Royal Society of\n Thailand\'s orthographic standards. The only exception is the use of "ssg" for\n syllable segmentation in the :meth:`check_klon` method.\n\n Key capabilities:\n - :meth:`check_sara` -> Identify the phonetic vowel sound of a Thai word,\n handling complex vowels (สระประสม), transformed vowels (สระเปลี่ยนรูป),\n and reduced vowels (สระลดรูป).\n - :meth:`check_marttra` -> Determine the orthographic spelling section\n (relative to the final consonant) per Royal Society standards.\n - :meth:`is_sumpus` -> Evaluate whether two words rhyme by comparing\n both vowel sound and spelling section, with phonetic normalisation\n for สระเกิน (e.g., อำ, ไอ).\n - :meth:`check_karu_lahu` -> Classify a syllable as heavy (ครุ) or\n light (ลหุ) for meter analysis.\n - :meth:`check_klon` -> Validate an entire poem against traditional\n กลอนสี่ (4-syllable) or กลอนแปด (8-syllable) rhyme rules.\n - :meth:`check_aek_too` -> Identify tonal marks (เอก/โท) on Thai words.\n - :meth:`handle_karun_sound_silence` -> Strip characters silenced by\n the การันย์ marker (e.g., "โอห์ม" → "โอ").\n - :meth:`_has_true_final_yl` and :meth:`_is_true_final` -> Determine\n whether a word-ending "ย" or "ล" is a genuine final consonant\n rather than part of an initial cluster or vowel digraph.\n\n :Example:\n Basic usage::\n\n >>> from pythainlp.khavee import KhaveeVerifier\n >>> kv = KhaveeVerifier()\n >>> kv.check_sara("เริง")\n \'เออ\'\n >>> kv.is_sumpus("สรร", "อัน")\n True\n >>> kv.check_klon(\n ... \'ฉันชื่อหมูกรอบ ฉันชอบกินไก่ แล้ววิ่งตามไป ไล่หมาน้ำทอง\',\n ... k_type=4\n ... )\n \'The poem is correct according to the principle.\'\n\n :Note:\n The method :meth:`check_klon` requires the external ``ssg`` library.\n ', 'VALID_CONSONANTS': frozenset({'ง', 'ย', 'ม', 'ซ', 'ค', 'ธ', 'จ', 'ด', 'ภ', 'ว', 'ท', 'ข', 'อ', 'ช', 'ฤ', 'ฐ', 'พ', 'ฃ', 'ก', 'ฟ', 'ร', 'ล', 'ฮ', 'ป', 'ฆ', 'ศ', 'ฦ', 'ฝ', 'ผ', 'ญ', 'น', 'ฌ', 'ฬ', 'ถ', 'ฏ', 'ฅ', 'ณ', 'ส', 'บ', 'ห', 'ฉ', 'ฎ', 'ต', 'ฑ', 'ษ', 'ฒ'}), '_MASKING_TERMINAL_VOWELS': ('เกียรติ', 'ชาติ', 'ญาติ', 'มัติ', 'วัติ', 'บัติ', 'ญัติ', 'ยัติ', 'ภูมิ', 'พฤติ', 'พรรดิ', 'วรรดิ', 'พยาธิ', 'โพธิ', 'เกตุ', 'เมรุ', 'เหตุ', 'ธาตุ', 'วุฒิ', 'สมมุติ', 'วิมุติ'), '_LAHU_SYLLABLE_OVERRIDES': frozenset({'ก็', 'ธ', 'ณ', 'ฤ', 'บ่', 'ฦ', 'บ'}), '_SINGLE_CHAR_WORDS': frozenset({'ธ', 'ณ', 'ฤ', 'ฦ', 'บ', 'พณ'}), '_LAM_CLUSTERS': frozenset({'ศล', 'ผล', 'กล', 'ปล', 'หล', 'ถล', 'ฉล', 'คล', 'พล', 'สล', 'ตล', 'ขล'}), '_RUA_CLUSTERS': frozenset({'หร', 'ฟร', 'ศร', 'กร', 'ขร', 'คร', 'ปร', 'ตร', 'สร', 'พร', 'บร'}), '_WA_CLUSTERS': frozenset({'ถว', 'สว', 'ชว', 'คว', 'ขว', 'กว', 'ทว', 'หว', 'ศว'}), '_WA_WHITELIST': frozenset({'โคว', 'แคว', 'โหว', 'โหว่', 'แหว', 'เหว่', 'เขว'}), '_OPEN_SYLLABLE_VOWELS': frozenset({'ๅ', 'ึ', 'ุ', 'ี', 'ิ', 'ะ', 'า', 'ู', 'อ'}), '_KOK_CHARS': frozenset({'ค', 'ก', 'ฆ', 'ข'}), '_KOD_CHARS': frozenset({'ศ', 'ซ', 'ธ', 'จ', 'ด', 'ท', 'ถ', 'ฏ', 'ช', 'ส', 'ฐ', 'ฎ', 'ต', 'ฑ', 'ษ', 'ฒ'}), '_KON_CHARS': frozenset({'ฬ', 'ณ', 'ล', 'ญ', 'ร', 'น'}), '_KOB_CHARS': frozenset({'ป', 'ภ', 'พ', 'ฟ', 'บ'}), '_LONG_VOWELS': frozenset({'เออ', 'อี', 'อา', 'อู', 'อือ', 'เอีย', 'เอือ', 'เอ', 'ออ', 'แอ', 'อัว', 'โอ'}), '_SPECIAL_VOWELS': frozenset({'อำ', 'เอา', 'ไอ'}), '_EXPLICIT_SARA_WORDS': frozenset({'เอ', 'เออ', 'เอาะ', 'เอะ', 'เออะ', 'เอา'}), '__init__': <function KhaveeVerifier.__init__>, '_has_true_final_yl': <function KhaveeVerifier._has_true_final_yl>, '_is_true_final': <function KhaveeVerifier._is_true_final>, 'check_sara': <function KhaveeVerifier.check_sara>, 'check_marttra': <function KhaveeVerifier.check_marttra>, 'is_sumpus': <function KhaveeVerifier.is_sumpus>, 'check_karu_lahu': <function KhaveeVerifier.check_karu_lahu>, 'check_klon': <function KhaveeVerifier.check_klon>, 'check_aek_too': <function KhaveeVerifier.check_aek_too>, 'handle_karun_sound_silence': <function KhaveeVerifier.handle_karun_sound_silence>, '__dict__': <attribute '__dict__' of 'KhaveeVerifier' objects>, '__weakref__': <attribute '__weakref__' of 'KhaveeVerifier' objects>})

__module__ = 'pythainlp.khavee.core'

The KhaveeVerifier class is the primary component of the pythainlp.khavee module, dedicated to the verification of Thai poetry. It offers a range of functions and methods for analyzing and validating Thai poetry, ensuring its adherence to the rules and structure of classical Thai poetic forms.

Example

Here’s a basic example of how to use the KhaveeVerifier class to verify Thai poetry:

from pythainlp.khavee import KhaveeVerifier

# Initialize a KhaveeVerifier instance
verifier = KhaveeVerifier()

# Text to verify
poem_text = "ดอกไม้สวยงาม แสนสดใส"

# Verify if the text is Thai poetry
is_poetry = verifier.is_khavee(poem_text)

print(f"The provided text is Thai poetry: {is_poetry}")