tbot223-core 3.0.1

Python utility library with Result pattern for consistent error handling, file operations, parallel execution, and logging.

tbot223-core

A comprehensive utility package providing core functionalities for Python applications, including file management, logging, error tracking, and various utility functions.

Note

This library returns all external APIs using the Result object. It is designed with safety as the top priority. This may not align with traditional Python values. While we have strived for ease of use, this library is not recommended for beginners.

Features

• Consistent Result Objects: All functions return a standardized Result object for predictable error handling
• Robust File Management: Atomic file operations, JSON handling, and safe file I/O
• Advanced Logging System: Structured logging with automatic log file management
• Exception Tracking: Detailed error tracking with system information and context
• Utility Functions: Encryption, path handling, parallel execution, and more
• Multi-language Support: Built-in localization support
• Shared Memory IPC: Inter-process communication via shared memory with process-safe locking

Installation

pip install tbot223-core

Python Version

Python 3.10 - 3.12

Core Modules

AppCore

Provides core application functionalities:

• Parallel execution with ThreadPoolExecutor / ProcessPoolExecutor
• Console management (clear_console())
• Application lifecycle control (restart_application(), exit_application())
• Multi-language text retrieval (get_text_by_lang())
  WARNING

  You must configure language files before using this feature. Place JSON language files in the Languages directory. Examples can be found in `examples`.
• Safe CLI input with validation and type conversion

FileManager

Safe and reliable file operations:

• Atomic file writing (atomic_write())
• File read operations (read_file()) with text/binary modes
• JSON read/write operations (read_json(), write_json())
• File/directory listing with extension filtering (list_of_files())
• File/directory existence checking
• Safe file/directory deletion (delete_file(), delete_directory())
• Directory creation with parent support (create_directory())
• Cross-platform file locking (_lock())

LogSys

Structured logging system:

• Logger management with automatic file organization (LoggerManager)
• Time-stamped log files
• Configurable log levels
• Centralized log instances (Log)
• Simple setup helper (SimpleSetting)

Utils (Utils/Utils.py)

Collection of utility functions:

• Path conversions (str_to_path())
• Encryption (encrypt()) - md5, sha1, sha256, sha512
• PBKDF2 HMAC hash generation and verification (pbkdf2_hmac(), verify_pbkdf2_hmac())
• List/string manipulation (insert_at_intervals())
• Dictionary operations (find_keys_by_value()) with comparison operators
• Unique ID generation (get_unique_id())

GlobalVars (Utils/GlobalVars.py)

Thread-safe global variable management with shared memory support:

• Variable operations (set(), get(), delete(), clear())
• Variable existence checking (exists(), list_vars())
• Attribute access syntax support (gv.key = value)
• Call syntax for get/set operations (gv("key", value))
• Shared memory creation (shm_gen()) with optional multiprocessing.Lock
• Shared memory connection for child processes (shm_connect())
• Shared memory synchronization (shm_sync(), shm_update()) with pickle/json serialization
• Shared memory access with LRU cache (shm_get(), shm_cache_management())
• Shared memory cleanup (shm_close()) with optional close_only mode
• Context manager support (with gv:) for thread-safe operations
• Internal thread lock access (lock())
• Security: JSON serialization option for safer IPC with untrusted processes

DecoratorUtils (Utils/DecoratorUtils.py)

Utility decorators:

• Runtime measurement decorator (count_runtime())

ExceptionTracker

Comprehensive error tracking:

• Exception location tracking (get_exception_location())
• Detailed exception info with system context (get_exception_info())
• Standardized exception return (get_exception_return())
• System information caching (OS, architecture, Python version)
• Information masking support with mask_tuple parameter for sensitive data
• Decorator for automatic exception handling (ExceptionTrackerDecorator)

Result Object

All functions (except internal ones) return a Result NamedTuple for consistent error handling:

Result(
    success: Optional[bool], # True=success, False=failure, None=cancelled
    error: Optional[str],    # Error message if failed
    context: Optional[str],  # Additional context information
    data: Any               # Returned data
)

Result Methods

• unwrap() - Returns data if successful, raises ResultUnwrapException if failed or cancelled
• expect() - Returns data if successful, raises ResultUnwrapException if not successful
• unwrap_or(default) - Returns data if successful, otherwise returns the default value

Usage Example

from tbot223_core import FileManager
from tbot223_core.Result import ResultUnwrapException

fm = FileManager()
result = fm.read_file("example.txt")

if result.success:
    print(f"File content: {result.data}")
else:
    print(f"Error: {result.error}")

# Using unwrap methods
try:
    content = fm.read_file("example.txt").unwrap()
except ResultUnwrapException as e:
    print(f"Failed: {e}")

# Using unwrap_or for default value
content = fm.read_file("missing.txt").unwrap_or("default content")

Error Information

System information is cached when library classes are instantiated. Access detailed error information via Result.data:

{
    "success": bool,
    "error": {
        "type": "ExceptionType",
        "message": "Exception message"
    },
    "location": {
        "file": "filename",
        "line": 123,
        "function": "function_name"
    },
    "origin_location" {
        "file": "filename",
        "line": 123,
        "function": "function_name"
    },
    "timestamp": "YYYY-MM-DD HH:MM:SS",
    "input_context": {
        "user_input": "...",
        "params": {...}
    },
    "traceback": "Full traceback...",
    "computer_info": {
        "OS": "OS name",
        "OS_version": "OS version",
        "Release": "OS release",
        "Architecture": "Machine architecture",
        "Processor": "Processor information",
        "Python_Version": "Python version",
        "Python_Executable": "Path to Python executable",
        "Current_Working_Directory": "Current working directory"
    }
}

Quick Start

from tbot223_core import AppCore, FileManager

app = AppCore(
    is_logging_enabled=True,
    is_debug_enabled=False,
    default_lang="en"
)

filemanager = FileManager(
    is_logging_enabled=True,
    is_debug_enabled=False,
    # Empty space (set as CWD) or custom path
    base_dir=""
)

# Use FileManager for safe file operations
result = filemanager.write_json("config.json", {"key": "value"})

# Execute functions in parallel
tasks = [
    (somefunc, {"some_arg1": val1}),
    (anotherfunc, {"some_arg1": val1, "some_arg1": val2})
]
result = app.thread_pool_executor(tasks, workers=4)

Shared Memory Usage

from tbot223_core import GlobalVars
from multiprocessing import Process

# Worker function (must be defined at module level)
def worker(shm_name, lock):
    gv_worker = GlobalVars()
    with lock:
        gv_worker.shm_update(shm_name)
        current = gv_worker.get("counter").data
        gv_worker.set("counter", current + 1, overwrite=True)
        gv_worker.shm_sync(shm_name)

if __name__ == "__main__":
    # Main process - all setup must be inside __main__ guard
    gv = GlobalVars()
    result = gv.shm_gen("my_shm", size=4096, create_lock=True)
    shm_lock = result.data  # Get the lock for inter-process sync

    gv.set("counter", 0, overwrite=True)
    gv.shm_sync("my_shm")

    # Start processes (lock must be passed before fork/spawn)
    processes = [Process(target=worker, args=("my_shm", shm_lock)) for _ in range(4)]
    for p in processes:
        p.start()
    for p in processes:
        p.join()

    # Check result
    gv.shm_update("my_shm")
    print(f"Final counter: {gv.get('counter').data}")  # Output: 4

    # Cleanup
    gv.shm_close("my_shm")

License

Apache License 2.0

Links

• GitHub: https://github.com/Tbot223/tbot223-core
• Author: tbot223 ([e-mail])

---

한국어 (Korean)

파이썬 애플리케이션을 위한 핵심 기능을 제공하는 종합 유틸리티 패키지입니다. 파일 관리, 로깅, 에러 추적 및 다양한 유틸리티 함수를 포함합니다.

참고사항

이 라이브러리의 모든 외부 API는 Result 객체를 사용하여 반환합니다. 안전성을 최우선으로 두고 설계되었습니다. 파이썬의 전통적인 가치와는 맞지 않을 수 있습니다. 사용 편의성을 위해 노력했지만, 초보자에게는 권장하지 않습니다.

주요 기능

• 일관된 Result 객체: 모든 함수가 표준화된 Result 객체를 반환하여 예측 가능한 에러 처리 제공
• 안정적인 파일 관리: 원자적 파일 작업, JSON 처리, 안전한 파일 I/O
• 고급 로깅 시스템: 자동 로그 파일 관리를 통한 구조화된 로깅
• 예외 추적: 시스템 정보와 컨텍스트를 포함한 상세한 에러 추적
• 유틸리티 함수: 암호화, 경로 처리, 병렬 실행 등
• 다국어 지원: 내장 지역화 지원
• 공유 메모리 IPC: 프로세스 안전 잠금을 통한 공유 메모리 프로세스 간 통신

설치

pip install tbot223-core

파이썬 버전

Python 3.10 - 3.12

핵심 모듈

AppCore

핵심 애플리케이션 기능 제공:

• ThreadPoolExecutor / ProcessPoolExecutor를 통한 병렬 실행
• 콘솔 관리 (clear_console())
• 애플리케이션 생명주기 제어 (restart_application(), exit_application())
• 다국어 텍스트 조회 (get_text_by_lang())
• 검증 및 타입 변환을 포함한 안전한 CLI 입력

FileManager

안전하고 신뢰할 수 있는 파일 작업:

• 원자적 파일 쓰기 (atomic_write())
• 텍스트/바이너리 모드 파일 읽기 (read_file())
• JSON 읽기/쓰기 (read_json(), write_json())
• 확장자 필터링을 포함한 파일/디렉토리 목록 (list_of_files())
• 파일/디렉토리 존재 확인
• 안전한 파일/디렉토리 삭제 (delete_file(), delete_directory())
• 상위 디렉토리 지원 디렉토리 생성 (create_directory())

LogSys

구조화된 로깅 시스템:

• 자동 파일 구성을 통한 로거 관리 (LoggerManager)
• 타임스탬프 로그 파일
• 설정 가능한 로그 레벨
• 중앙화된 로그 인스턴스 (Log)
• 간단한 설정 헬퍼 (SimpleSetting)

Utils (Utils/Utils.py)

유틸리티 함수 모음:

• 경로 변환 (str_to_path())
• 암호화 (encrypt()) - md5, sha1, sha256, sha512
• PBKDF2 HMAC 해시 생성 및 검증 (pbkdf2_hmac(), verify_pbkdf2_hmac())
• 리스트/문자열 조작 (insert_at_intervals())
• 딕셔너리 작업 (find_keys_by_value())
• 고유 ID 생성 (get_unique_id())

GlobalVars (Utils/GlobalVars.py)

공유 메모리를 지원하는 스레드 안전 전역 변수 관리:

• 변수 작업 (set(), get(), delete(), clear())
• 공유 메모리 생성 (shm_gen()), 연결 (shm_connect())
• 공유 메모리 동기화 (shm_sync(), shm_update())
• 컨텍스트 관리자 지원 (with gv:)
• 보안: 신뢰할 수 없는 프로세스와의 IPC를 위한 JSON 직렬화 옵션

DecoratorUtils (Utils/DecoratorUtils.py)

유틸리티 데코레이터:

• 실행 시간 측정 데코레이터 (count_runtime())

ExceptionTracker

종합적인 에러 추적:

• 예외 위치 추적 (get_exception_location())
• 시스템 컨텍스트를 포함한 상세 예외 정보 (get_exception_info())
• 표준화된 예외 반환 (get_exception_return())
• 민감한 데이터를 위한 mask_tuple 파라미터 마스킹 지원
• 자동 예외 처리를 위한 데코레이터 (ExceptionTrackerDecorator)

Result 객체

모든 함수(내부 함수 제외)는 일관된 에러 처리를 위해 Result NamedTuple을 반환합니다:

Result(
    success: Optional[bool], # True=성공, False=실패, None=취소됨
    error: Optional[str],    # 실패 시 에러 메시지
    context: Optional[str],  # 추가 컨텍스트 정보
    data: Any               # 반환 데이터
)

Result 메서드

• unwrap() - 성공 시 데이터 반환, 실패 또는 취소 시 ResultUnwrapException 발생
• expect() - 성공 시 데이터 반환, 성공이 아닌 경우 ResultUnwrapException 발생
• unwrap_or(default) - 성공 시 데이터 반환, 그렇지 않으면 기본값 반환

사용 예시

from tbot223_core import FileManager
from tbot223_core.Result import ResultUnwrapException

fm = FileManager()
result = fm.read_file("example.txt")

if result.success:
    print(f"파일 내용: {result.data}")
else:
    print(f"에러: {result.error}")

# unwrap 메서드 사용
try:
    content = fm.read_file("example.txt").unwrap()
except ResultUnwrapException as e:
    print(f"실패: {e}")

# 기본값을 위한 unwrap_or 사용
content = fm.read_file("missing.txt").unwrap_or("기본 내용")

빠른 시작

from tbot223_core import AppCore, FileManager

app = AppCore(
    is_logging_enabled=True,
    is_debug_enabled=False,
    default_lang="ko"
)

filemanager = FileManager(
    is_logging_enabled=True,
    is_debug_enabled=False,
    base_dir=""  # 빈 문자열(CWD) 또는 커스텀 경로
)

# FileManager로 안전한 파일 작업
result = filemanager.write_json("config.json", {"key": "value"})

# 병렬로 함수 실행
tasks = [
    (somefunc, {"arg1": val1}),
    (anotherfunc, {"arg1": val1, "arg2": val2})
]
result = app.thread_pool_executor(tasks, workers=4)

라이선스

Apache License 2.0