Source code

Documentation for the source code of the main script.

Module vocabuilder.add_window

class vocabuilder.add_window.AddWindow(parent, config, database)

Bases: QWidget, ResizeWindowMixin, StringMixin, TimeMixin, WarningsMixin

Add a new term (and its translation) to the database, then ask for a another term to add. Continue the above procedure of adding terms until the user clicks the cancel button

__init__(parent, config, database)
add_buttons(layout, vpos)

Adds the button widgets. :type layout: QGridLayout :param layout:

Return type:

int

add_button_pressed()
Return type:

bool

add_data()
Return type:

bool

add_line_edits(layout, vpos)
Return type:

int

add_scroll_area(layout, vpos)
Return type:

None

cancel_button()
Return type:

None

closeEvent(event)

Overrides the closeEvent() method in QWidget. We use this to notify the parent when we are closed

Return type:

None

get_db()
Return type:

Database

keyPressEvent(event)
Return type:

None

maybe_update_view_window_later()
Return type:

None

ok_button()
Return type:

None

simulate_add_button_pressed()
Return type:

None

update_scroll_area_items(text)
Return type:

None

Module vocabuilder.commandline

class vocabuilder.commandline.CommandLineOptions(app)

Bases: object

__init__(app)
get_database_name()
Return type:

Optional[str]

Module vocabuilder.config

class vocabuilder.config.Config

Bases: object

dirlock_fn = '.dirlock'
config_fn = 'config.ini'
__init__()
check_config_dir()
Return type:

Path

check_correct_config_dir(lock_file)

The config dir might be owned by another app with the same name

Return type:

None

check_correct_data_dir(lock_file)

The data dir might be owned by another app with the same name

Return type:

None

get_config_dir()
Return type:

Path

get_data_dir()
Return type:

Path

get_data_dir_path()
Return type:

Path

get_config_path()
Return type:

Path

get_section(section)
Return type:

SectionProxy

read_config()
Return type:

None

read_defaults(config)
Return type:

None

Module vocabuilder.constants

class vocabuilder.constants.TermStatus

Bases: object

Has this term been deleted from the database?

DELETED = 0
NOT_DELETED = 1
class vocabuilder.constants.TestDirection

Bases: object

When running a practice/test session, should you practice translating words from language 1 to language 2, or practice translating words from language 2 to language 1?

class vocabuilder.constants.TestMethod

Bases: object

When running a practice/test session, should the words to be practiced be picked at random, or should the user select the words from a list?

Random = 1
List = 2

Module vocabuilder.csv_helpers

class vocabuilder.csv_helpers.CsvDatabaseHeader

Bases: object

  • status : 0 = The item has been deleted, 1, 2, 3,.. the item is not deleted

  • term1 : “From” term

  • term2 : “To” term (translation of Term1)

  • test_delay : Number of days to next possible test, 0 or negative means no delay

  • last_test : timestamp (epoch) of last time this term was practiced

  • last_modified : timestamp (epoch) of last time any of the previous was modified

status = 'Status'
term1 = 'Term1'
term2 = 'Term2'
test_delay = 'TestDelay'
last_test = 'LastTest'
last_modified = 'LastModified'
header = ['Status', 'Term1', 'Term2', 'TestDelay', 'LastTest', 'LastModified']
types = {'LastModified': <class 'int'>, 'LastTest': <class 'int'>, 'Status': <class 'int'>, 'Term1': <class 'str'>, 'Term2': <class 'str'>, 'TestDelay': <class 'int'>}
class vocabuilder.csv_helpers.CSVwrapper(dbname)

Bases: object

__init__(dbname)
append_line(row_dict)
Return type:

None

append_row(row)
Return type:

None

dict_to_row(row_dict)
Return type:

list[UnionType[str, int, None]]

open_for_read(header)
Return type:

CSVwrapperReader

open_for_write()
Return type:

CSVwrapperWriter

class vocabuilder.csv_helpers.CSVwrapperReader(parent, filename, header)

Bases: object

Context manager for reading lines from the database csv file

__init__(parent, filename, header)
fixup_datatypes(row)

NOTE: this method modifies the input argument ‘row’

Return type:

None

class vocabuilder.csv_helpers.CSVwrapperWriter(parent, filename)

Bases: object

Context manager for writing lines to the database csv file

__init__(parent, filename)
writerow(row)
Return type:

None

writeline(row_dict)
Return type:

None

Module vocabuilder.database

class vocabuilder.database.Database(config, voca_name)

Bases: TimeMixin

__init__(config, voca_name)
add_item(item)
Return type:

None

check_term1_exists(term1)
Return type:

bool

create_backup()
Return type:

None

delete_item(term1)
Return type:

None

push_updated_items_to_firebase()
Return type:

None

push_updated_items_to_local_database()
Return type:

None

get_local_database()
Return type:

LocalDatabase

get_pairs_exceeding_test_delay()
Return type:

list[tuple[str, str]]

get_random_pair()
Return type:

Optional[tuple[str, str]]

get_term1_data(term1)
Return type:

dict[str, UnionType[str, int, None]]

get_term1_list()
Return type:

list[str]

get_term2(term1)
Return type:

str

get_term2_list()
Return type:

list[str]

get_voca_name()
Return type:

str

modify_item(old_term1, item)
Return type:

None

reset_firebase()
Return type:

None

update_item(term1, item)
Return type:

None

update_retest_value(term1, delay)
Return type:

None

Module vocabuilder.firebase_database

class vocabuilder.firebase_database.FirebaseStatus

Bases: object

NOT_INITIALIZED = 0
INITIALIZED = 1
class vocabuilder.firebase_database.FirebaseDatabase(config, voca_name)

Bases: TimeMixin

appname = 'vocabuilder'
__init__(config, voca_name)
delete_item(key)
Return type:

None

get_firebase_key(key)
Return type:

str

get_items()
Return type:

dict[str, dict[str, UnionType[str, int, None]]]

is_initialized()
Return type:

bool

push_item(key, value)
Return type:

None

read_database()
Return type:

bool

run_reset()
Return type:

None

update_item_same_key(key, value)
Return type:

None

update_item_different_key(old_key, new_key, value)
Return type:

None

Module vocabuilder.local_database

class vocabuilder.local_database.LocalDatabase(config, voca_name)

Bases: TimeMixin

database_fn = 'database.csv'
database_dir = 'databases'
backup_dirname = 'backup'
git_dirname = '.git'
active_voca_info_fn = 'active_db.txt'
__init__(config, voca_name)
add_item(item)

Add a new item to the database.

Parameters:

item (dict[str, UnionType[str, int, None]]) – a dict with the following keys: header.term1, header.term2, header.test_delay, and header.last_test. Here header refers to the CsvDatabaseHeader object.

Return type:

None

The header.status and header.last_modified keys are added automatically, then the dict is pushed to the database

assign_item(term1, item)

Replace, add, or delete a new item to the database. The item is implicitly deleted if the header.status key is set to TermStatus.DELETED.

Parameters:

item (dict[str, UnionType[str, int, None]]) – a dict with the following keys: header.status, header.term2, header.test_delay, header.last_test, and header.last_modified. Here header refers to the CsvDatabaseHeader object.

Return type:

None

check_term1_exists(term1)
Return type:

bool

create_backup()
Return type:

None

delete_item(term1)
Return type:

None

get_items()
Return type:

dict[str, dict[str, UnionType[str, int, None]]]

get_header()
Return type:

CsvDatabaseHeader

get_pairs_exceeding_test_delay()

Get all candidates for a practice session.

Return type:

list[tuple[str, str]]

get_random_pair()
Return type:

Optional[tuple[str, str]]

get_term1_data(term1)
Return type:

dict[str, UnionType[str, int, None]]

get_term1_list()
Return type:

list[str]

get_term2(term1)
Return type:

str

get_term2_list()
Return type:

list[str]

get_voca_name()
Return type:

str

update_item(term1, item)
Return type:

None

update_retest_value(term1, delay)

Set a delay (in days) until next time this term should be practiced

Return type:

None

Module vocabuilder.exceptions

exception vocabuilder.exceptions.CommandLineException(value)

Bases: Exception

__init__(value)
exception vocabuilder.exceptions.ConfigException(value)

Bases: Exception

__init__(value)
exception vocabuilder.exceptions.CsvFileException(value)

Bases: Exception

__init__(value)
exception vocabuilder.exceptions.FirebaseDatabaseException(value)

Bases: Exception

__init__(value)
exception vocabuilder.exceptions.LocalDatabaseException(value)

Bases: Exception

__init__(value)
exception vocabuilder.exceptions.SelectVocabularyException(value)

Bases: Exception

__init__(value)
exception vocabuilder.exceptions.TimeException(value)

Bases: Exception

__init__(value)

Module vocabuilder.main_window

class vocabuilder.main_window.MainWindow(app, db, config)

Bases: QMainWindow, WarningsMixin

__init__(app, db, config)
add_buttons(layout, vpos)
Return type:

int

add_database_info_label(layout, vpos)
Return type:

int

add_new_entry()
Return type:

None

add_window_closed()
Return type:

None

backup()
Return type:

None

closeEvent(event)

Overrides the closeEvent() method in QWidget to ensure that all windows are closed when the main window is closed

Return type:

None

create_file_menu()
Return type:

None

create_database_menu()
Return type:

None

create_menus()
Return type:

None

delete_entry()
Return type:

QMessageBox

edit_config()
Return type:

None

keyPressEvent(event)
Return type:

None

modify_entry()

Modify/edit the translation of an existing term1 (and/or its translation) and update the database. Then, ask for a another term to modify. Continue the above procedure of modifying terms until the user clicks the cancel button

Return type:

SelectWordFromList

quit()
Return type:

None

reset_firebase()
Return type:

None

run_test()
Return type:

None

test_window_closed()
Return type:

None

update_view_window()
Return type:

None

view_entries()
Return type:

None

view_window_closed()
Return type:

None

view_window_is_open()
Return type:

bool

Module vocabuilder.mixins

class vocabuilder.mixins.ConfigWindow

Bases: object

window_config: dict[str, str]
move(x, y)
Return type:

None

resize(w, h)
Return type:

None

class vocabuilder.mixins.ResizeWindowMixin

Bases: ConfigWindow

resize_window_from_config()
Return type:

None

class vocabuilder.mixins.StringMixin

Bases: object

String methods

static check_space_or_empty_str(str_)

Is string empty or only space characters?

Parameters:

str (str) – Input string

Return type:

bool

Returns:

True if string is empty or only space

class vocabuilder.mixins.TimeMixin

Bases: object

static epoch_in_seconds()
Return type:

int

static get_epoch_diff_in_days(t1, t2)

t1, t2: epoch times. In general these times could be negative, but in this application they should always be positive (corresponding to dates after year 2022)

Return type:

int

class vocabuilder.mixins.WarningsMixin

Bases: object

static display_warning(parent, msg, callback=None)
Return type:

QMessageBox

static display_warning_no_terms(parent, callback=None)
Return type:

QMessageBox

static display_warning_callback(mbox, msg)

This method is here such that it can be mocked from pytest

Return type:

None

Module vocabuilder.modify_window

class vocabuilder.modify_window.ModifyWindow(parent, term1, config, database)

Bases: QDialog, WarningsMixin, StringMixin

Modify/edit the translation of an existing term1 (and/or its translation) and update the database.

__init__(parent, term1, config, database)
add_buttons(layout, vpos)
Return type:

int

add_labels(layout, vpos)
Return type:

int

add_line_edits(layout, vpos)
Return type:

int

cancel_button()
Return type:

None

keyPressEvent(event)
Return type:

None

modify_item()
Return type:

bool

ok_button()
Return type:

None

Module vocabuilder.select_voca

class vocabuilder.select_voca.SelectVocabulary(opts, cfg, app)

Bases: object

__init__(opts, cfg, app)
choose_most_recent()
Return type:

bool

find_existing_vocabularies()
Return type:

None

get_name()
Return type:

Optional[str]

open_select_voca_window(app)
Return type:

Optional[str]

read_active_name()
Return type:

bool

class vocabuilder.select_voca.SelectNewVocabularyName(cfg, app)

Bases: QMainWindow, StringMixin, WarningsMixin

__init__(cfg, app)
add_info_label(layout, vpos)
Return type:

int

add_line_edit(layout, vpos)
Return type:

int

add_buttons(layout, vpos)
Return type:

int

ok_button()
Return type:

None

cancel_button()
Return type:

None

validate_name(name)
Return type:

bool

Module vocabuilder.test_window

class vocabuilder.test_window.TestWindow(parent, config, database)

Bases: QWidget, ResizeWindowMixin, WarningsMixin

__init__(parent, config, database)
add_current_term_to_practice(layout, vpos)
Return type:

int

add_next_done_buttons(layout, vpos)
Return type:

int

add_param_info_labels(layout, vpos)
Return type:

int

add_retest_options(layout, vpos)
Return type:

int

add_retest_radio_button(grid, i, delay, checked, edit)
Return type:

None

assign_terms_to_practice(callback)

Determine the term to practice, either from a list of words, or select a word randomly.

Parameters:

callback (Union[Callable[[], None], Callable[[], TestWindow]]) – called to continue execution after the term to practice has been determined. Note that the callback is needed since a non-blocking dialog will be opened if the term is selected from a list.

Return type:

Optional[TestWindow]

choose_word_from_list(callback)

Choose a word to practice from a dialog showing a list of all words available for practice.

Parameters:

callback (Callable[[tuple[str, str]], None]) – Callback to be called to continue execution after the the user has selected a word from the non-blocking dialog

Return type:

Optional[SelectWordFromList]

closeEvent(event)

Overrides the closeEvent() method in QWidget. We use this to notify the parent when we are closed

Return type:

None

done_button_clicked()
Return type:

None

keyPressEvent(event)
Return type:

None

main_dialog()

This is a callback method which is called after the test parameters has been chosen from the TestWindowChooseParameters dialog

Return type:

None

main_dialog2()

This is a callback that is called after the current pair of words to practice has been assigned

Return type:

TestWindow

next_button_clicked()
Return type:

None

show_hidden_translation(label)
Return type:

Callable[[], None]

update_retest_lineedit(edit, delay)
Return type:

Callable[[], None]

class vocabuilder.test_window.TestWindowChooseParameters(main_window, parent, config, callback)

Bases: QDialog

__init__(main_window, parent, config, callback)
add_buttons(layout, vpos)
Return type:

int

add_check_box_group1(layout, vpos)
Return type:

int

add_check_box_group2(layout, vpos)
Return type:

int

cancel_button()
Return type:

None

call_parent_callback()
Return type:

None

keyPressEvent(event)
Return type:

None

modify_checkbox_group1(callback)
Return type:

None

modify_checkbox_group2(callback)
Return type:

None

ok_button()
Return type:

None

Module vocabuilder.type_aliases

Module vocabuilder.vocabuilder

vocabuilder.vocabuilder.select_vocabulary(opts, cfg, app)

The user can select between different databases with different vocabularies

Return type:

str

vocabuilder.vocabuilder.set_app_options(app, cfg)
Return type:

None

vocabuilder.vocabuilder.main()
Return type:

None

Module vocabuilder.widgets

class vocabuilder.widgets.QLabelClickable(text, parent=None)

Bases: QLabel

__init__(text, parent=None)
addCallback(callback)
Return type:

None

mousePressEvent(ev)
Return type:

None

class vocabuilder.widgets.QGridMinimalLabel(text, parent=None)

Bases: QLabel

__init__(text, parent=None)
sizeHint()
Return type:

QSize

class vocabuilder.widgets.QSelectItemScrollArea(items, select_callback)

Bases: QScrollArea

__init__(items, select_callback)
add_items(match_str=None)
Return type:

None

item_clicked(item)
Return type:

Callable[[], None]

update_items(text)
Return type:

None

update_items_list(items)
Return type:

None

class vocabuilder.widgets.SelectWordFromList(parent, config, win_title, words, callback, get_pair_callback, options=None)

Bases: QDialog, StringMixin, WarningsMixin

__init__(parent, config, win_title, words, callback, get_pair_callback, options=None)

Dialog that lets the user select a word from a list of words.

Parameters:

  • words (list[str]) – The list of candidate words

  • callback (Callable[[tuple[str, str]], None]) – If the user selects a word, the callback is called to continue execution. The callback is given as an argument a pair of words. The first item of the pair is the selected word, the seconds item of the pair is determined by calling the get_pair_callback() function

  • get_pair_callback (Callable[[str, int], tuple[str, str]]) – The callback is given the selected word and its index into the words array, and is expected to produce a pair of words as its return value

  • options (Optional[dict[str, Any]]) –

    A dictionary of options. The following options are available:

    • click_accept: If True, the dialog is accepted when the user clicks on a word in the list. Default: False

    • close_on_accept: If True, the dialog is closed when the user clicks the “Ok” button. Default: False

add_buttons(layout, vpos)
Return type:

int

add_line_edit(layout, vpos)
Return type:

int

add_scroll_area(layout, vpos)
Return type:

None

cancel_button()
Return type:

None

check_bool_option(option)
Return type:

bool

check_term_in_list(term)
Return type:

bool

keyPressEvent(event)
Return type:

None

ok_button()
Return type:

None

update_scroll_area_items(text)
Return type:

None