conlang package

Submodules

conlang.language module

class conlang.language.Language(name: str, config: LanguageConfig, vocabulary: Vocabulary | None = None)

Bases: object

Represents a language, including its configuration and vocabulary.

name

The name of the language.

Type:

str

config

The configuration for phonemes, word patterns, and stress.

Type:

LanguageConfig

vocabulary

The generated vocabulary for the language.

Type:

Vocabulary

static from_vocabulary(name: str, vocabulary: Vocabulary) → Language

Create a new Language instance from an existing vocabulary.

Parameters:

• name (str) – The name of the language.

• vocabulary (Vocabulary) – The vocabulary for the language.

Returns:

A new Language instance with a configuration derived from the vocabulary.

Return type:

Language

generate_vocabulary(glosses: List[str] | None = None)

Generates a vocabulary for the language based on glosses.

Parameters:

glosses (List[str], optional) – A list of glosses to use for the vocabulary. Defaults to the SWADESH list.

generate_word(rank: int = -1) → str

Generates a word based on the language’s configuration and word frequency rank.

Parameters:

rank (int) – The rank of the word for frequency purposes. Common words (rank < 25) use simpler patterns. Defaults to -1.

Returns:

The generated word.

Return type:

str

conlang.language_config module

class conlang.language_config.LanguageConfig(phonemes: Dict[str, List[str]], patterns: List[str], stress: List[int])

Bases: object

Represents the configuration of a language, including its phonemes, word patterns, and stress rules.

phonemes

A dictionary mapping phoneme categories to lists of phonemes.

Type:

Dict[str, List[str]]

patterns

A list of word patterns, where each pattern is a sequence of phoneme categories.

Type:

List[str]

stress

A list of stressed syllable positions (as negative indices).

Type:

List[int]

static from_dict(config_dict: Dict) → LanguageConfig

Creates a LanguageConfig instance from a dictionary.

Parameters:

config_dict (Dict) – A dictionary containing the configuration with keys ‘phonemes’, ‘patterns’, and ‘stress’.

Returns:

The parsed language configuration.

Return type:

LanguageConfig

static from_json(file_path: str) → LanguageConfig

Reads a configuration from a JSON file to create a LanguageConfig instance.

Parameters:

file_path (str) – The path to the configuration file.

Returns:

The parsed language configuration.

Return type:

LanguageConfig

static from_str(config_str: str) → LanguageConfig

Parses a configuration string to create a LanguageConfig instance.

Parameters:

config_str (str) – The configuration as a multi-line string.

Returns:

The parsed language configuration.

Return type:

LanguageConfig

static from_txt(file_path: str) → LanguageConfig

Reads a configuration from a text file to create a LanguageConfig instance.

Parameters:

file_path (str) – The path to the configuration file.

Returns:

The parsed language configuration.

Return type:

LanguageConfig

static from_vocabulary(vocabulary: Vocabulary) → LanguageConfig

Generates a language configuration from a vocabulary.

Parameters:

vocabulary (Vocabulary) – The vocabulary to generate the configuration from.

Returns:

The generated language configuration.

Return type:

LanguageConfig

static load_preset(name: str) → LanguageConfig

Loads a language configuration preset by name.

Parameters:

name (str) – The name of the preset to load.

Returns:

The language configuration preset.

Return type:

LanguageConfig

static random() → LanguageConfig

Generates a random LanguageConfig instance using predefined presets.

Returns:

A randomly selected language configuration.

Return type:

LanguageConfig

conlang.phonemes module

conlang.presets module

conlang.rules module

conlang.sound_change module

class conlang.sound_change.SoundChange(rules: Dict[Tuple[str], List[Tuple[str]]], wildcards: Dict[str, List[str]] | None = None)

Bases: object

A class to handle phonological sound changes using defined rules.

rules

A dictionary mapping phonemes or phoneme sequences to lists of tuples, where each tuple contains the new phoneme(s) and the environment.

Type:

Dict[Tuple[str], List[Tuple[str]]]

wildcards

A dictionary mapping wildcard symbols to lists of phonemes.

Type:

Optional[Dict[str, List[str]]]

apply_to_vocabulary(vocabulary: Vocabulary) → Vocabulary

Apply sound changes to an entire vocabulary.

Parameters:

vocabulary (Vocabulary) – The input vocabulary.

Returns:

A new vocabulary with mutated words.

Return type:

Vocabulary

apply_to_word(word: Word) → Word

Apply sound changes to a single word based on defined rules.

Parameters:

word (Word) – The input word.

Returns:

The transformed word.

Return type:

Word

static from_str(string: str) → SoundChange

Create a SoundChange instance from a string of rules.

Parameters:

string (str) – The string containing rules and wildcards.

Returns:

A new instance with parsed rules and wildcards.

Return type:

SoundChange

static from_txt(file_path: str) → SoundChange

Create a SoundChange instance from a text file of rules.

Parameters:

file_path (str) – The path to the file.

Returns:

A new instance with parsed rules and wildcards.

Return type:

SoundChange

static load_preset(name: str) → SoundChange

Load a SoundChange instance from a predefined preset.

Parameters:

name (str) – The name of the preset.

Returns:

A new instance with rules and wildcards from the preset.

Return type:

SoundChange

static random() → SoundChange

Generate a random SoundChange instance from predefined rules.

Returns:

A new instance with random rules and wildcards.

Return type:

SoundChange

class conlang.sound_change.SoundChangePipeline(changes: List[SoundChange])

Bases: object

A class to chain multiple sound changes together.

changes

A list of SoundChange instances.

Type:

List[SoundChange]

apply_to_vocabulary(vocabulary: Vocabulary) → Vocabulary

Apply all sound changes in the pipeline to an entire vocabulary.

Parameters:

vocabulary (Vocabulary) – The input vocabulary.

Returns:

A new vocabulary with mutated words.

Return type:

Vocabulary

apply_to_word(word: Word) → Word

Apply all sound changes in the pipeline to a single word.

Parameters:

word (Word) – The input word.

Returns:

The mutated word.

Return type:

Word

static from_txt(file_path: str) → SoundChangePipeline

Create a SoundChangePipeline instance from a text file of rules.

Parameters:

file_path (str) – The path to the file.

Returns:

A new instance with parsed sound changes.

Return type:

SoundChangePipeline

static random(num_changes: int | None = None) → SoundChangePipeline

Generate a random SoundChangePipeline instance with random sound changes.

Parameters:

num_changes (Optional[int]) – The number of sound changes to include. Defaults to a random number between 1 and 5.

Returns:

A new instance with random sound changes.

Return type:

SoundChangePipeline

conlang.swadesh module

conlang.utils module

conlang.utils.parse_phonemes(word: str) → List[str]

Splits a word string into phonemes using the predefined PHONEME_SET list.

Parameters:

word (str) – The word to split into phonemes as a string.

Returns:

A list of phonemes.

Return type:

List[str]

conlang.utils.process_patterns(patterns: List[str], phonemes: Dict[str, List[str]]) → List[str]

Processes patterns to prioritize simpler ones (short and without clusters).

Parameters:

• patterns (List[str]) – A list of patterns to process.

• phonemes (Dict[str, List[str]]) – A dictionary of phoneme categories and their respective phonemes.

Returns:

A modified list of patterns where simpler patterns are more likely.

Return type:

List[str]

conlang.utils.process_phonemes(phonemes: Dict[str, List[str]]) → Dict[str, List[str]]

Processes phoneme sets to make common phonemes more likely to be chosen.

Parameters:

phonemes (Dict[str, List[str]]) – A dictionary of phoneme categories and their respective phonemes.

Returns:

A modified dictionary where common phonemes are more likely.

Return type:

Dict[str, List[str]]

conlang.vocabulary module

class conlang.vocabulary.Vocabulary

Bases: object

A class to manage a collection of words and their glosses.

items

A list of dictionaries with ‘word’ and ‘gloss’ keys. Where ‘word’ is a Word object and ‘gloss’ is a string.

Type:

List[Dict[str, Any]]

add_item(word: Word, gloss: str) → None

Add a word and its gloss to the vocabulary.

Parameters:

• word (Word) – The word to add.

• gloss (str) – The gloss or meaning of the word.

static from_csv(filename: str) → Vocabulary

Create a Vocabulary object from a CSV file.

Parameters:

filename (str) – Path to the input CSV file.

Returns:

A new Vocabulary object.

Return type:

Vocabulary

static from_json(file_path: str) → Vocabulary

Create a Vocabulary object from a JSON file.

Parameters:

file_path (str) – Path to the input JSON file.

Returns:

A new Vocabulary object.

Return type:

Vocabulary

static from_list(items: List[Dict[str, Any]]) → Vocabulary

Create a Vocabulary object from a list of word-gloss dictionaries.

Parameters:

items (List[Dict[str, str]]) – A list of word-gloss dictionaries.

Returns:

A new Vocabulary object.

Return type:

Vocabulary

static from_str(string: str) → Vocabulary

Create a Vocabulary object from a string.

Parameters:

string (str) – The input string with word-gloss pairs.

Returns:

A new Vocabulary object.

Return type:

Vocabulary

static from_txt(file_path: str) → Vocabulary

Create a Vocabulary object from a text file.

Parameters:

file_path (str) – Path to the input text file.

Returns:

A new Vocabulary object.

Return type:

Vocabulary

has_word(word: Word) → bool

Check if the vocabulary contains a specific word.

Parameters:

word (Word) – The word to check.

Returns:

True if the word exists, False otherwise.

Return type:

bool

to_csv(filename: str) → None

Save the vocabulary to a CSV file.

Parameters:

filename (str) – Path to the output CSV file.

to_txt(filename: str) → None

Save the vocabulary to a text file.

Parameters:

filename (str) – Path to the output text file.

Module contents

class conlang.Language(name: str, config: LanguageConfig, vocabulary: Vocabulary | None = None)

Bases: object

Represents a language, including its configuration and vocabulary.

name

The name of the language.

Type:

str

config

The configuration for phonemes, word patterns, and stress.

Type:

LanguageConfig

vocabulary

The generated vocabulary for the language.

Type:

Vocabulary

static from_vocabulary(name: str, vocabulary: Vocabulary) → Language

Create a new Language instance from an existing vocabulary.

Parameters:

• name (str) – The name of the language.

• vocabulary (Vocabulary) – The vocabulary for the language.

Returns:

A new Language instance with a configuration derived from the vocabulary.

Return type:

Language

generate_vocabulary(glosses: List[str] | None = None)

Generates a vocabulary for the language based on glosses.

Parameters:

glosses (List[str], optional) – A list of glosses to use for the vocabulary. Defaults to the SWADESH list.

generate_word(rank: int = -1) → str

Generates a word based on the language’s configuration and word frequency rank.

Parameters:

rank (int) – The rank of the word for frequency purposes. Common words (rank < 25) use simpler patterns. Defaults to -1.

Returns:

The generated word.

Return type:

str

class conlang.LanguageConfig(phonemes: Dict[str, List[str]], patterns: List[str], stress: List[int])

Bases: object

Represents the configuration of a language, including its phonemes, word patterns, and stress rules.

phonemes

A dictionary mapping phoneme categories to lists of phonemes.

Type:

Dict[str, List[str]]

patterns

A list of word patterns, where each pattern is a sequence of phoneme categories.

Type:

List[str]

stress

A list of stressed syllable positions (as negative indices).

Type:

List[int]

static from_dict(config_dict: Dict) → LanguageConfig

Creates a LanguageConfig instance from a dictionary.

Parameters:

config_dict (Dict) – A dictionary containing the configuration with keys ‘phonemes’, ‘patterns’, and ‘stress’.

Returns:

The parsed language configuration.

Return type:

LanguageConfig

static from_json(file_path: str) → LanguageConfig

Reads a configuration from a JSON file to create a LanguageConfig instance.

Parameters:

file_path (str) – The path to the configuration file.

Returns:

The parsed language configuration.

Return type:

LanguageConfig

static from_str(config_str: str) → LanguageConfig

Parses a configuration string to create a LanguageConfig instance.

Parameters:

config_str (str) – The configuration as a multi-line string.

Returns:

The parsed language configuration.

Return type:

LanguageConfig

static from_txt(file_path: str) → LanguageConfig

Reads a configuration from a text file to create a LanguageConfig instance.

Parameters:

file_path (str) – The path to the configuration file.

Returns:

The parsed language configuration.

Return type:

LanguageConfig

static from_vocabulary(vocabulary: Vocabulary) → LanguageConfig

Generates a language configuration from a vocabulary.

Parameters:

vocabulary (Vocabulary) – The vocabulary to generate the configuration from.

Returns:

The generated language configuration.

Return type:

LanguageConfig

static load_preset(name: str) → LanguageConfig

Loads a language configuration preset by name.

Parameters:

name (str) – The name of the preset to load.

Returns:

The language configuration preset.

Return type:

LanguageConfig

static random() → LanguageConfig

Generates a random LanguageConfig instance using predefined presets.

Returns:

A randomly selected language configuration.

Return type:

LanguageConfig

class conlang.SoundChange(rules: Dict[Tuple[str], List[Tuple[str]]], wildcards: Dict[str, List[str]] | None = None)

Bases: object

A class to handle phonological sound changes using defined rules.

rules

A dictionary mapping phonemes or phoneme sequences to lists of tuples, where each tuple contains the new phoneme(s) and the environment.

Type:

Dict[Tuple[str], List[Tuple[str]]]

wildcards

A dictionary mapping wildcard symbols to lists of phonemes.

Type:

Optional[Dict[str, List[str]]]

apply_to_vocabulary(vocabulary: Vocabulary) → Vocabulary

Apply sound changes to an entire vocabulary.

Parameters:

vocabulary (Vocabulary) – The input vocabulary.

Returns:

A new vocabulary with mutated words.

Return type:

Vocabulary

apply_to_word(word: Word) → Word

Apply sound changes to a single word based on defined rules.

Parameters:

word (Word) – The input word.

Returns:

The transformed word.

Return type:

Word

static from_str(string: str) → SoundChange

Create a SoundChange instance from a string of rules.

Parameters:

string (str) – The string containing rules and wildcards.

Returns:

A new instance with parsed rules and wildcards.

Return type:

SoundChange

static from_txt(file_path: str) → SoundChange

Create a SoundChange instance from a text file of rules.

Parameters:

file_path (str) – The path to the file.

Returns:

A new instance with parsed rules and wildcards.

Return type:

SoundChange

static load_preset(name: str) → SoundChange

Load a SoundChange instance from a predefined preset.

Parameters:

name (str) – The name of the preset.

Returns:

A new instance with rules and wildcards from the preset.

Return type:

SoundChange

static random() → SoundChange

Generate a random SoundChange instance from predefined rules.

Returns:

A new instance with random rules and wildcards.

Return type:

SoundChange

class conlang.SoundChangePipeline(changes: List[SoundChange])

Bases: object

A class to chain multiple sound changes together.

changes

A list of SoundChange instances.

Type:

List[SoundChange]

apply_to_vocabulary(vocabulary: Vocabulary) → Vocabulary

Apply all sound changes in the pipeline to an entire vocabulary.

Parameters:

vocabulary (Vocabulary) – The input vocabulary.

Returns:

A new vocabulary with mutated words.

Return type:

Vocabulary

apply_to_word(word: Word) → Word

Apply all sound changes in the pipeline to a single word.

Parameters:

word (Word) – The input word.

Returns:

The mutated word.

Return type:

Word

static from_txt(file_path: str) → SoundChangePipeline

Create a SoundChangePipeline instance from a text file of rules.

Parameters:

file_path (str) – The path to the file.

Returns:

A new instance with parsed sound changes.

Return type:

SoundChangePipeline

static random(num_changes: int | None = None) → SoundChangePipeline

Generate a random SoundChangePipeline instance with random sound changes.

Parameters:

num_changes (Optional[int]) – The number of sound changes to include. Defaults to a random number between 1 and 5.

Returns:

A new instance with random sound changes.

Return type:

SoundChangePipeline

class conlang.Vocabulary

Bases: object

A class to manage a collection of words and their glosses.

items

A list of dictionaries with ‘word’ and ‘gloss’ keys. Where ‘word’ is a Word object and ‘gloss’ is a string.

Type:

List[Dict[str, Any]]

add_item(word: Word, gloss: str) → None

Add a word and its gloss to the vocabulary.

Parameters:

• word (Word) – The word to add.

• gloss (str) – The gloss or meaning of the word.

static from_csv(filename: str) → Vocabulary

Create a Vocabulary object from a CSV file.

Parameters:

filename (str) – Path to the input CSV file.

Returns:

A new Vocabulary object.

Return type:

Vocabulary

static from_json(file_path: str) → Vocabulary

Create a Vocabulary object from a JSON file.

Parameters:

file_path (str) – Path to the input JSON file.

Returns:

A new Vocabulary object.

Return type:

Vocabulary

static from_list(items: List[Dict[str, Any]]) → Vocabulary

Create a Vocabulary object from a list of word-gloss dictionaries.

Parameters:

items (List[Dict[str, str]]) – A list of word-gloss dictionaries.

Returns:

A new Vocabulary object.

Return type:

Vocabulary

static from_str(string: str) → Vocabulary

Create a Vocabulary object from a string.

Parameters:

string (str) – The input string with word-gloss pairs.

Returns:

A new Vocabulary object.

Return type:

Vocabulary

static from_txt(file_path: str) → Vocabulary

Create a Vocabulary object from a text file.

Parameters:

file_path (str) – Path to the input text file.

Returns:

A new Vocabulary object.

Return type:

Vocabulary

has_word(word: Word) → bool

Check if the vocabulary contains a specific word.

Parameters:

word (Word) – The word to check.

Returns:

True if the word exists, False otherwise.

Return type:

bool

to_csv(filename: str) → None

Save the vocabulary to a CSV file.

Parameters:

filename (str) – Path to the output CSV file.

to_txt(filename: str) → None

Save the vocabulary to a text file.

Parameters:

filename (str) – Path to the output text file.

class conlang.Word(word_str: str)

Bases: object

Represents a word with its phonemes, syllables, and stress information.

word_str

The original string representation of the word.

Type:

str

display

The formatted display string.

Type:

str

stress

The stressed syllable position (as a negative index).

Type:

Optional[int]

phonemes

The list of phonemes in the word.

Type:

List[str]

syllables

The list of syllables, each represented as a list of phonemes.

Type:

List[List[str]]

stress_bounds

The start and end indices of the stressed phonemes.

Type:

Tuple[int, int]

get_stress_bounds() → Tuple[int, int]

Determines the start and end indices of the stressed phonemes.

Returns:

The start and end indices of the stressed phonemes.

Returns None if no stress is set.

Return type:

Tuple[int, int]

is_acceptable() → bool

Determines whether a word is acceptable based on specific phonetic constraints.

Returns:

True if the word is acceptable, False otherwise.

Return type:

bool

set_stress(stress: int) → None

Sets the stress position for the word.

Parameters:

stress (int) – The stressed syllable position as a negative index.

split_syllables() → List[List[str]]

Splits the word into syllables based on phonemes.

Parameters:

phonemes (List[str]) – The list of phonemes in the word.

Returns:

A list of syllables, each represented as a list of phonemes.

Return type:

List[List[str]]

update_display() → None

Updates the display string.