Collaboration diagram for polyguard.src.sqlite_handler.SQLiteHandler:

Public Member Functions
"SQLiteHandler"	__new__ (cls, args, *kwargs)

None	__init__ (self, str db_path, bool readonly=True, *, bool log=True, bool debug=False)

None	connect (self)

None	close (self)

"SQLiteHandler"	__enter__ (self)

None	__exit__ (self, exc_type, exc, tb)

None	create_schema (self)

int	bulk_insert (self, Dict[POLY_CONST.Langs, Iterable[str]] mapping)

Set[str]	get_words (self, POLY_CONST.Langs lang)

Dict[str, int]	list_languages (self)

bool	has_word (self, POLY_CONST.Langs lang, str word)

Data Fields
	db_path = db_path

	readonly = readonly

	log = bool(log)

str	readonly = f"file:{os.path.abspath(self.db_path)}?mode=ro"

None	_conn = None

Optional[sqlite3.Connection]	log = self._conn.cursor()

Optional[sqlite3.Connection]	_lock = self._conn.cursor()

Static Public Attributes
Disp	disp = initialise_logger(__qualname__, False)

Protected Attributes
Optional[sqlite3.Connection]	_conn = None

Lock	_lock = Lock()

Static Protected Attributes
Optional	_instance = None

Lock	_class_lock = Lock()

Detailed Description

Manage a connection to an SQLite database storing language word-lists.

The expected schema is a table `words(lang TEXT, word TEXT, PRIMARY KEY(lang, word))`.

Definition at line 43 of file sqlite_handler.py.

Constructor & Destructor Documentation

◆ init()

None polyguard.src.sqlite_handler.SQLiteHandler.__init__	(		self,
		str	db_path,
		bool	readonly = True,
		*	,
		bool	log = True,
		bool	debug = False )

Initialize SQLite connection handler.

Sets up connection parameters but does not open the connection until
connect() is called. Supports both read-only and read-write modes.

Args:
    db_path: Path to SQLite database file.
    readonly: If True, opens database in read-only mode. Defaults to True.
    log: If True, enables logging of database operations. Defaults to True.
    debug: If True, enables debug-level logging. Defaults to False.

Definition at line 58 of file sqlite_handler.py.

Member Function Documentation

◆ enter()

"SQLiteHandler" polyguard.src.sqlite_handler.SQLiteHandler.__enter__ ( self )

Context manager entry: open database connection.

Returns:
    SQLiteHandler: This instance with connection open.

Definition at line 138 of file sqlite_handler.py.

◆ exit()

None polyguard.src.sqlite_handler.SQLiteHandler.__exit__	(	self,
		exc_type,
		exc,
		tb )

Context manager exit: close database connection.

Closes connection regardless of whether an exception occurred.

Definition at line 147 of file sqlite_handler.py.

◆ new()

"SQLiteHandler" polyguard.src.sqlite_handler.SQLiteHandler.__new__	(		cls,
		*	args,
		**	kwargs )

Definition at line 52 of file sqlite_handler.py.

◆ bulk_insert()

int polyguard.src.sqlite_handler.SQLiteHandler.bulk_insert	(		self,
		Dict[POLY_CONST.Langs, Iterable[str]]	mapping )

Bulk insert words from language to words mapping.

Normalizes and inserts words from each language. Uses INSERT OR IGNORE
to skip duplicate (lang, word) pairs. Returns cumulative row count
across all languages provided (sum of per-language totals, not insert count).

Args:
    mapping: Dictionary mapping Langs enums to iterables of words.

Returns:
    int: Sum of word counts across all languages in mapping after insert.

Raises:
    RuntimeError: When connection is not open.
    sqlite3.Error: When database operation fails (transaction is rolled back).

Definition at line 187 of file sqlite_handler.py.

◆ close()

None polyguard.src.sqlite_handler.SQLiteHandler.close ( self )

Close SQLite database connection.

If not connected, this method is a no-op. Safe to call multiple times.

Definition at line 120 of file sqlite_handler.py.

◆ connect()

None polyguard.src.sqlite_handler.SQLiteHandler.connect ( self )

Open SQLite database connection.

If readonly mode is enabled, uses SQLite URI syntax to open in read-only
mode. Enables check_same_thread=False to allow multithreaded access
(concurrency is controlled by instance lock). If already connected,
this method is a no-op.

Raises:
    sqlite3.DatabaseError: When connection fails (e.g., file not found in readonly mode).

Definition at line 79 of file sqlite_handler.py.

◆ create_schema()

None polyguard.src.sqlite_handler.SQLiteHandler.create_schema ( self )

Create words table if not already present.

Creates a table with columns (lang TEXT, word TEXT) and a composite
primary key on (lang, word). Idempotent — safe to call on existing tables.
Requires a writable database connection.

Raises:
    RuntimeError: When connection is not open.
    sqlite3.Error: When table creation fails.

Definition at line 154 of file sqlite_handler.py.

◆ get_words()

Set[str] polyguard.src.sqlite_handler.SQLiteHandler.get_words	(		self,
		POLY_CONST.Langs	lang )

Retrieve all words for a specific language from database.

Returns an empty set if the database is empty or the language has no entries.

Args:
    lang: Langs enum member specifying which language to retrieve.

Returns:
    Set[str]: Set of all words for the language.

Raises:
    RuntimeError: When connection is not open.

Definition at line 273 of file sqlite_handler.py.

◆ has_word()

bool polyguard.src.sqlite_handler.SQLiteHandler.has_word	(		self,
		POLY_CONST.Langs	lang,
		str	word )

Check if a word exists in a specific language.

Normalizes the input word (lowercase, strip whitespace) before checking.
Returns False for empty or whitespace-only inputs.

Args:
    lang: Langs enum member specifying which language to search.
    word: Word string to check.

Returns:
    bool: True if word is present for the language, False otherwise.

Raises:
    RuntimeError: When connection is not open.

Definition at line 360 of file sqlite_handler.py.

◆ list_languages()

Dict[str, int] polyguard.src.sqlite_handler.SQLiteHandler.list_languages ( self )

List all languages and their word counts in database.

Queries all distinct language codes and returns a mapping of code to word count.
Returns an empty dict if the database is empty or the words table is missing.

Returns:
    Dict[str, int]: Mapping of language code strings to word counts.

Raises:
    RuntimeError: When connection is not open.

Definition at line 318 of file sqlite_handler.py.

Field Documentation

◆ _class_lock

Lock polyguard.src.sqlite_handler.SQLiteHandler._class_lock = Lock()

staticprotected

Definition at line 49 of file sqlite_handler.py.

◆ _conn [1/2]

Optional[sqlite3.Connection] polyguard.src.sqlite_handler.SQLiteHandler._conn = None

protected

Definition at line 74 of file sqlite_handler.py.

◆ _conn [2/2]

None polyguard.src.sqlite_handler.SQLiteHandler._conn = None

Definition at line 110 of file sqlite_handler.py.

◆ _instance

Optional polyguard.src.sqlite_handler.SQLiteHandler._instance = None

staticprotected

Definition at line 48 of file sqlite_handler.py.

◆ _lock [1/2]

Lock polyguard.src.sqlite_handler.SQLiteHandler._lock = Lock()

protected

Definition at line 76 of file sqlite_handler.py.

◆ _lock [2/2]

Optional[sqlite3.Connection] polyguard.src.sqlite_handler.SQLiteHandler._lock = self._conn.cursor()

Definition at line 204 of file sqlite_handler.py.

◆ db_path

polyguard.src.sqlite_handler.SQLiteHandler.db_path = db_path

Definition at line 70 of file sqlite_handler.py.

◆ disp

Disp polyguard.src.sqlite_handler.SQLiteHandler.disp = initialise_logger(__qualname__, False)

static

Definition at line 50 of file sqlite_handler.py.

◆ log [1/2]

polyguard.src.sqlite_handler.SQLiteHandler.log = bool(log)

Definition at line 73 of file sqlite_handler.py.

◆ log [2/2]

Optional[sqlite3.Connection] polyguard.src.sqlite_handler.SQLiteHandler.log = self._conn.cursor()

Definition at line 169 of file sqlite_handler.py.

◆ readonly [1/2]

polyguard.src.sqlite_handler.SQLiteHandler.readonly = readonly

Definition at line 71 of file sqlite_handler.py.

◆ readonly [2/2]

str polyguard.src.sqlite_handler.SQLiteHandler.readonly = f"file:{os.path.abspath(self.db_path)}?mode=ro"

Definition at line 99 of file sqlite_handler.py.

The documentation for this class was generated from the following file:

polyguard/src/sqlite_handler.py

Public Member Functions

Data Fields

Static Public Attributes

Protected Attributes

Static Protected Attributes