polyguard

Take a look

This project now has automated documentation that gets generated, this manually written one will remain for legacy reasons, but you can now take a look at the automatic documentation here: https://hanra-s-work.github.io/polyguard/

Description

Table of Content

1. polyguard
2. Description
3. Table of Content
4. Installation
   1. Using pip
   2. Using python
5. Usage
   1. Running as a script
   2. Importing
   3. Initialising
6. Documentation
7. Author

Installation

Using pip

pip install -U polyguard

Using python

Under Windows:

py -m pip install -U polyguard

Under Linux/Mac OS:

python3 -m pip install -U polyguard

Usage

Running as a script

You can run polyguard directly as a script to start an interactive terminal session:

python -m polyguard

This will launch the interactive PolyGuard interface where you can execute commands.

Importing

from polyguard import PolyGuard

Initialising

To initialize PolyGuard, you need to create a language configuration and pass it to the constructor:

from polyguard.src.polyguard import PolyGuard
from polyguard.src.constants import LangConfig

# Create a language configuration (enable desired languages)
lang_config = LangConfig()
# By default, all supported languages are enabled

# Initialize PolyGuard with optional parameters
polyguard_instance = PolyGuard(
    langs=lang_config,
    db_path=None,  # Uses default package database if None
    success=0,     # Exit code for success
    error=1,       # Exit code for error
    log=True,      # Enable logging
    debug=False    # Enable debug-level logging
)

Usage Examples

Once initialized, you can use the following methods:

# Check if a word is profanity (returns bool)
if polyguard_instance.is_a_swearword("hello world"):
    print("Contains profanity")
else:
    print("Clean text")

# Extract the first matching swearword (returns Optional[str])
offending_word = polyguard_instance.extract_swearword_if_present("some bad word here")
if offending_word:
    print(f"Found profanity: {offending_word}")

# Get all swearwords for enabled languages (returns Dict[str, Set])
all_words = polyguard_instance.get_list_of_swearwords()
for language, words in all_words.items():
    print(f"{language}: {len(words)} words")

Note: The database initialization happens automatically on the first call to any lookup function, so you don't need to call main() manually.

Per-Call Language Configuration

All lookup functions accept an optional languages_to_check parameter, allowing you to override the default language configuration on a case-by-case basis:

from polyguard import LangConfig

# Create a custom language config for this specific check
custom_langs = LangConfig()
custom_langs.en = True   # Only check English
custom_langs.fr = False  # Don't check French
custom_langs.de = False  # Don't check German
# ... set other languages as needed

# Use the custom config for this lookup only
if polyguard_instance.is_a_swearword("hello world", languages_to_check=custom_langs):
    print("Contains profanity in enabled languages")

# Extract swearword with custom language set
word = polyguard_instance.extract_swearword_if_present(
    "bonjour monde", 
    languages_to_check=custom_langs
)

# Get swearwords for custom language subset
words = polyguard_instance.get_list_of_swearwords(languages=custom_langs)

This is useful when you need to:

• Check text against only specific languages
• Perform different validations for different contexts
• Optimize performance by limiting language checks to what's needed

If languages_to_check/languages is not provided, the instance's default configuration (set during initialization) is used.

Documentation

Comprehensive Doxygen-generated documentation is available online at https://hanra-s-work.github.io/polyguard/. This includes detailed API references, class documentation, and usage examples.

To generate the documentation locally, navigate to the doxygen_generation directory and run the provided scripts.

Author

This module was written by (c) Henry Letellier Attributions are appreciated.