Helper-functions¶

The Helper-Modul bietet Hilfsfunktionen for wiederkehrende Aufgaben wie Logging, Error Handling, Kryptografie and Datei-Operationen.

Overview¶

Helper-Modul	Description
Logger	Konfigurierbares Logging-System
ErrorHandler / ErrorTraceback	Error Handling and Exception-Tracking
CryptoHelper	Kryptografische functions (Hashing, encryption)
FileReader / FileWriter	Datei-Operationen (JSON, YAML, etc.)
FileLock	Datei-Locking for gleichzeitigen Access
EnvHandler	environment variables-Verwaltung
func (fuzzy_match / deep_merge)	Utility-Funktionen für String-Matching und Dictionary-Operationen

ErrorHandler & ErrorTraceback¶

Error Handling with automatic Traceback:

ErrorTraceback Decorator¶

from vyra_base.helper.error_traceback import ErrorTraceback

@ErrorTraceback.w_check_error_existt
async def my_function():
    """Error are automatically geloggt"""
    # Bei Exception: Traceback is geloggt and Error-Feeder notified
    raise ValueError("Etwas is schiefgelonen")

Functionality:

Automatisches Exception-Logging
Completer Traceback
Integration with ErrorFeeder
Keine Unterbrechung des Programmflusses

ErrorHandler¶

from vyra_base.helper.error_handler import ErrorHandler

try:
    # Riskante Operation
    result = await dangerous_operation()
except Exception as e:
    # Error behandeln
    ErrorHandler.handle_exception(e, context={
        "function": "dangerous_operation",
        "module": "my_module"
    })

CryptoHelper¶

Cryptographic functions for security:

Hashing¶

from vyra_base.helper.crypto_helper import CryptoHelper

# SHA-256 Hash
hash_value = CryptoHelper.hash_sha256("my_password")
print(f"Hash: {hash_value}")

# Password Hashing with Salt (recommended)
hashed_password = CryptoHelper.hash_password("my_password")

# Password Verification
is_valid = CryptoHelper.verify_password("my_password", hashed_password)

encryption¶

# Data encrypt
encrypted = CryptoHelper.encrypt("Secret message", key="my_key")

# Data decrypt
decrypted = CryptoHelper.decrypt(encrypted, key="my_key")

Warnung

Never use hardcoded keys in production code! Use environment variables or secrets management.

Random Values¶

# Generate token
token = CryptoHelper.generate_token(length=32)

# UUID generate
unique_id = CryptoHelper.generate_uuid()

FileReader & FileWriter¶

File operations with automatic format detection:

FileReader¶

from vyra_base.helper.file_reader import FileReader

# JSON read
data = FileReader.read_json("/workspace/config/settings.json")

# YAML read
config = FileReader.read_yaml("/workspace/config/config.yaml")

# Text read
content = FileReader.read_text("/workspace/data/info.txt")

# Binär read
binary_data = FileReader.read_binary("/workspace/data/image.png")

Supported Formats:

JSON (.json)
YAML (.yaml, .yml)
TOML (.toml)
Text (.txt, .md, etc.)
Binary (all others)

FileWriter¶

from vyra_base.helper.file_writer import FileWriter

# JSON write
FileWriter.write_json(
    "/workspace/config/output.json",
    {"key": "value", "number": 42}
)

# YAML write
FileWriter.write_yaml(
    "/workspace/config/output.yaml",
    {"settings": {"debug": True}}
)

# Text write
FileWriter.write_text(
    "/workspace/log/output.txt",
    "Log message"
)

FileLock¶

File locking for concurrent access:

from vyra_base.helper.file_lock import FileLock

lock_file = "/tmp/my_process.lock"

with FileLock(lock_file) as lock:
    if lock.acquired:
        # Exclusive access
        with open("/workspace/data/shared_file.txt", "w") as f:
            f.write("Critical data")
    else:
        print("File is locked by another process")

Tipp

FileLock prevents race conditions during concurrent write access.

EnvHandler¶

environment variables management:

from vyra_base.helper.env_handler import EnvHandler

# Read environment variable
module_name = EnvHandler.get("MODULE_NAME", default="unknown")

# Set environment variable
EnvHandler.set("DEBUG_MODE", "true")

# Load all variables (from .env file)
EnvHandler.load_dotenv("/workspace/.env")

# Parse boolean value
is_debug = EnvHandler.get_bool("DEBUG_MODE", default=False)

# Parse integer value
port = EnvHandler.get_int("PORT", default=8080)

.env file Example:

MODULE_NAME=v2_modulemanager
DEBUG_MODE=true
LOG_LEVEL=INFO
REDIS_HOST=redis
REDIS_PORT=6379

Utility Functions (func.py)¶

General-purpose utility functions used across the VYRA framework.

fuzzy_match¶

fuzzy_match() finds the closest matching strings from a candidate list. It wraps difflib.get_close_matches() and is used throughout the framework to generate actionable error messages whenever a lookup by name fails (e.g. resolving feeder names against interface configs).

from vyra_base.helper.func import fuzzy_match

# Find similar publisher names when a feeder cannot be resolved
known_publishers = ["ErrorFeed", "StateFeed", "NewsFeed", "DiagnosticFeed"]
suggestions = fuzzy_match("StaetFeed", known_publishers)
# → ["StateFeed"]

# In diagnostic messages
if not found:
    hints = fuzzy_match(requested_name, all_names, n=3, cutoff=0.5)
    logger.error("'%s' not found. Did you mean: %s?", requested_name, hints)

Parameters:

Parameter	Default	Description
`word`	—	The string to match.
`possibilities`	—	Sequence of candidate strings to search in.
`n`	`3`	Maximum number of close matches to return.
`cutoff`	`0.6`	Minimum similarity ratio `[0, 1]`. Higher = stricter matching.

Return value: A list of strings from possibilities, sorted by decreasing similarity. Empty list if nothing meets the cutoff.

deep_merge¶

deep_merge() recursively merges two dictionaries, with the second dict’s values taking precedence for non-dict keys:

from vyra_base.helper.func import deep_merge

base   = {"a": 1, "nested": {"x": 10, "y": 20}}
patch  = {"b": 2, "nested": {"y": 99, "z": 30}}
result = deep_merge(base, patch)
# → {"a": 1, "b": 2, "nested": {"x": 10, "y": 99, "z": 30}}

Best Practices¶

Logging¶

✅ Recommended:

Use you structured logging
Use you appropriate log levels (DEBUG < INFO < WARNING < ERROR)
Log important events (start, stop, error)
Avoid sensitive data in logs

❌ Avoid:

Excessive logging in high-frequency loops
Personal or sensitive data
Logging without context information

Error Handling¶

✅ Recommended:

Use you @ErrorTraceback for async functions
Log errors with complete context
Use you ErrorFeeder for central error collection

Cryptography¶

✅ Recommended:

Use you hash_password() instead of simple SHA-256
Store your keys in environment variables
Use you strong, random keys

❌ Avoid:

Hardcoded passwords or keys
Weak hashing algorithms (MD5, SHA1)
Reuse of salts

File Operations¶

✅ Recommended:

Use you FileReader/FileWriter instead of direct I/O
Use you FileLock for concurrent access
Check you path existence before write operations

Further Information¶

vyra_base.helper package - API-Reference
Logger - Logger class
ErrorTraceback - Error Decorator
CryptoHelper - Crypto functions
FileReader - File read
FileWriter - File write
FileLock - File locking
EnvHandler - Environment variables
fuzzy_match() - Fuzzy string matching (difflib wrapper)
deep_merge() - Recursive dictionary merge