Collaboration diagram for polyguard.src.polyguard.PolyGuard:

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

None	__init__ (self, POLY_CONST.LangConfig langs, Optional[str] db_path=None, int success=0, int error=1, bool log=True, bool debug=False)

int	__call__ (self, Any args, *Any kwds)

Optional[str]	extract_swearword_if_present (self, str word, *, Optional[POLY_CONST.LangConfig] languages_to_check=None)

bool	is_a_swearword (self, str word, *, Optional[POLY_CONST.LangConfig] languages_to_check=None)

Dict[str, Set]	get_list_of_swearwords (self, *, Optional[POLY_CONST.LangConfig] languages=None)

int	main (self)

bool	ensure_connection (self)

Data Fields
	success = success

	error = error

	log = log

	debug = debug

POLY_CONST.LangConfig	default_choice = langs

	db_path = POLY_CONST.DEFAULT_DB_PATH

Optional[SQLiteHandler]	sqlite = None

dict	sqlite = {}

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

Protected Member Functions
Optional[str]	_sanify_word (self, str word)

bool	_ensure_initialized (self)

POLY_CONST.LangConfig	_determine_language_set (self, Optional[POLY_CONST.LangConfig] language)

List[str]	_tokenify (self, str text)

bool	_check_token (self, str text_low, POLY_CONST.LangConfig languages)

Protected Attributes
Lock	_function_lock = Lock()

bool	_db_ready = False

int	_cache_limit = int(POLY_CONST.DEFAULT_CACHE_MAX_LANGS)

	_lang_cache = OrderedDict()

Static Protected Attributes
Optional	_instance = None

Lock	_class_lock = Lock()

Detailed Description

Singleton profanity filter with multilingual support and LRU caching.

Manages a persistent connection to an SQLite database of language-specific
word lists. Provides thread-safe word detection with per-language caching
to optimize repeated lookups. Supports configurable language subsets and
can check single words or phrases.

Note:
    This class uses the singleton pattern. Multiple instantiations return
    the same instance.

Definition at line 45 of file polyguard.py.

Constructor & Destructor Documentation

◆ init()

None polyguard.src.polyguard.PolyGuard.__init__	(		self,
		POLY_CONST.LangConfig	langs,
		Optional[str]	db_path = None,
		int	success = 0,
		int	error = 1,
		bool	log = True,
		bool	debug = False )

Initialize the PolyGuard instance.

On first call, attempts to establish a persistent database connection.
If the connection fails, the instance will attempt to reconnect on demand.

Args:
    langs (LangConfig): LangConfig instance specifying which languages to check.
    db_path (Optional[str]): Path to the SQLite database. Default: None (package default).
    success (int): Exit code for successful initialization. Default: 0.
    error (int): Exit code for failures. Default: 1.
    log (bool): Enable logging output. Default: True.
    debug (bool): Enable debug-level logging. Default: False.

Definition at line 73 of file polyguard.py.

Member Function Documentation

◆ call()

int polyguard.src.polyguard.PolyGuard.__call__	(		self,
		*Any	args,
		**Any	kwds )

Callable interface. Delegates to main().

Returns:
    int: Result code from main() (0 for success, non-zero for error).

Definition at line 117 of file polyguard.py.

◆ new()

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

Create or return singleton instance.

Returns:
    PolyGuard: The singleton instance.

Definition at line 62 of file polyguard.py.

◆ _check_token()

bool polyguard.src.polyguard.PolyGuard._check_token	(		self,
		str	text_low,
		POLY_CONST.LangConfig	languages )

protected

Check if a single token exists in any enabled language's word list.

Internal method that performs the actual word lookup using cache and
database queries. Token must already be lowercased.

Args:
    text_low (str): Lowercased token to search for.
    languages (LangConfig): LangConfig specifying which languages to query.

Returns:
    bool: True if token found in any enabled language, False otherwise.

Raises:
    RuntimeError: If database connection becomes unavailable mid-check.

Definition at line 274 of file polyguard.py.

◆ _determine_language_set()

POLY_CONST.LangConfig polyguard.src.polyguard.PolyGuard._determine_language_set	(		self,
		Optional[POLY_CONST.LangConfig]	language )

protected

Resolve language configuration, falling back to default if needed.

Args:
    language (Optional[LangConfig]): Language config override. Default: None.

Returns:
    LangConfig: Provided language config or default instance config.

Definition at line 155 of file polyguard.py.

◆ _ensure_initialized()

bool polyguard.src.polyguard.PolyGuard._ensure_initialized ( self )

protected

Ensure database is initialized on first use.

Definition at line 149 of file polyguard.py.

◆ _sanify_word()

Optional[str] polyguard.src.polyguard.PolyGuard._sanify_word	(		self,
		str	word )

protected

Sanitize and normalize input word for processing.

Strips whitespace, converts to lowercase, and validates non-empty.

Args:
    word (str): Raw input word or phrase to sanitize.

Returns:
    Optional[str]: Lowercased, stripped word, or None if empty/invalid.

Definition at line 125 of file polyguard.py.

◆ _tokenify()

List[str] polyguard.src.polyguard.PolyGuard._tokenify	(		self,
		str	text )

protected

Tokenize text by splitting on whitespace after removing delimiters.

Uses pre-computed translation table for fast processing. Employs CPython's
optimized .split() fast-path (any-whitespace split with empty filtering).

Args:
    text (str): Text to tokenize (assumed already lowercased).

Returns:
    List[str]: List of non-empty token strings.

Definition at line 168 of file polyguard.py.

◆ ensure_connection()

bool polyguard.src.polyguard.PolyGuard.ensure_connection ( self )

Ensure a persistent SQLiteHandler is created and connected.

Creates a new handler if needed or reconnects an existing one.
Cleans up stale connections gracefully.

Returns:
    bool: True if connection is now open and usable, False otherwise.

Definition at line 427 of file polyguard.py.

◆ extract_swearword_if_present()

Optional[str] polyguard.src.polyguard.PolyGuard.extract_swearword_if_present	(		self,
		str	word,
		*	,
		Optional[POLY_CONST.LangConfig]	languages_to_check = None )

Extract first profanity match from word or phrase.

Tokenizes input and checks each token against enabled language word lists.
Returns immediately on first match for efficiency.

Args:
    word (str): The word or phrase to check.
    languages_to_check (Optional[LangConfig]): Language config override. Default: None.

Returns:
    Optional[str]: First matching swearword token found, or None if none detected.

Definition at line 183 of file polyguard.py.

◆ get_list_of_swearwords()

Dict[str, Set] polyguard.src.polyguard.PolyGuard.get_list_of_swearwords	(		self,
		*	,
		Optional[POLY_CONST.LangConfig]	languages = None )

Retrieve all swearwords for enabled languages.

Returns cached word sets if loaded, otherwise queries database.
Useful for inspection, testing, or bulk operations.

Args:
    languages (Optional[LangConfig]): Language config override. Default: None.

Returns:
    Dict[str, Set]: Dictionary mapping language names to sets of profanity words.
        Empty dict if database connection unavailable.

Definition at line 239 of file polyguard.py.

◆ is_a_swearword()

bool polyguard.src.polyguard.PolyGuard.is_a_swearword	(		self,
		str	word,
		*	,
		Optional[POLY_CONST.LangConfig]	languages_to_check = None )

Check if a word or phrase contains profanity.

Checks individual tokens in phrases and the full phrase itself.
Uses per-language LRU cache to optimize repeated lookups.

Args:
    word (str): The word or phrase to check (whitespace-stripped).
    languages_to_check (Optional[LangConfig]): Language config override. Default: None.

Returns:
    bool: True if any enabled language contains the word, False otherwise.

Definition at line 210 of file polyguard.py.

◆ main()

int polyguard.src.polyguard.PolyGuard.main ( self )

Probe the database and preload enabled languages into cache.

Attempts to verify database accessibility, then preloads up to
cache_limit languages into memory for faster lookup.

Returns:
    int: Success code (0) if DB ready, error code otherwise.

Definition at line 369 of file polyguard.py.

Field Documentation

◆ _cache_limit

polyguard.src.polyguard.PolyGuard._cache_limit = int(POLY_CONST.DEFAULT_CACHE_MAX_LANGS)

protected

Definition at line 107 of file polyguard.py.

◆ _class_lock

Lock polyguard.src.polyguard.PolyGuard._class_lock = Lock()

staticprotected

Definition at line 59 of file polyguard.py.

◆ _db_ready

bool polyguard.src.polyguard.PolyGuard._db_ready = False

protected

Definition at line 104 of file polyguard.py.

◆ _function_lock

polyguard.src.polyguard.PolyGuard._function_lock = Lock()

protected

Definition at line 88 of file polyguard.py.

◆ _instance

Optional polyguard.src.polyguard.PolyGuard._instance = None

staticprotected

Definition at line 58 of file polyguard.py.

◆ _lang_cache

polyguard.src.polyguard.PolyGuard._lang_cache = OrderedDict()

protected

Definition at line 108 of file polyguard.py.

◆ db_path

polyguard.src.polyguard.PolyGuard.db_path = POLY_CONST.DEFAULT_DB_PATH

Definition at line 97 of file polyguard.py.

◆ debug

polyguard.src.polyguard.PolyGuard.debug = debug

Definition at line 93 of file polyguard.py.

◆ default_choice

polyguard.src.polyguard.PolyGuard.default_choice = langs

Definition at line 94 of file polyguard.py.

◆ disp

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

static

Definition at line 60 of file polyguard.py.

◆ error

polyguard.src.polyguard.PolyGuard.error = error

Definition at line 91 of file polyguard.py.

◆ log

polyguard.src.polyguard.PolyGuard.log = log

Definition at line 92 of file polyguard.py.

◆ sqlite [1/2]

polyguard.src.polyguard.PolyGuard.sqlite = None

Definition at line 102 of file polyguard.py.

◆ sqlite [2/2]

dict polyguard.src.polyguard.PolyGuard.sqlite = {}

Definition at line 324 of file polyguard.py.

◆ success

polyguard.src.polyguard.PolyGuard.success = success

Definition at line 90 of file polyguard.py.

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

polyguard/src/polyguard.py

Public Member Functions

Data Fields

Static Public Attributes

Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __init__()

Member Function Documentation

◆ __call__()

◆ __new__()

◆ _check_token()

◆ _determine_language_set()

◆ _ensure_initialized()

◆ _sanify_word()

◆ _tokenify()

◆ ensure_connection()

◆ extract_swearword_if_present()

◆ get_list_of_swearwords()

◆ is_a_swearword()

◆ main()

Field Documentation

◆ _cache_limit

◆ _class_lock

◆ _db_ready

◆ _function_lock

◆ _instance

◆ _lang_cache

◆ db_path

◆ debug

◆ default_choice

◆ disp

◆ error

◆ log

◆ sqlite [1/2]

◆ sqlite [2/2]

◆ success

◆ init()

◆ call()

◆ new()