winiutils 1.1.4__tar.gz → 2.3.13__tar.gz

winiutils-2.3.13/PKG-INFO

@@ -0,0 +1,283 @@
+Metadata-Version: 2.4
+Name: winiutils
+Version: 2.3.13
+Summary: A utility library for Python development
+Author: Winipedia
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: cryptography
+Requires-Dist: defusedxml
+Requires-Dist: keyring
+Requires-Dist: keyrings-alt
+Requires-Dist: polars
+Requires-Dist: pyrig
+Requires-Dist: tqdm
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# winiutils
+
+<!-- tooling -->
+[![pyrig](https://img.shields.io/badge/built%20with-pyrig-3776AB?logo=buildkite&logoColor=black)](https://github.com/Winipedia/pyrig)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://pre-commit.com/)
+<!-- code-quality -->
+[![ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)[![mypy](https://img.shields.io/badge/type%20checked-mypy-039dfc.svg)](https://mypy-lang.org/)
+[![security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
+[![pytest](https://img.shields.io/badge/tested%20with-pytest-46a2f1.svg?logo=pytest)](https://pytest.org/)
+[![codecov](https://codecov.io/gh/Winipedia/winiutils/branch/main/graph/badge.svg)](https://codecov.io/gh/Winipedia/winiutils)
+<!-- package-info -->
+[![PyPI](https://img.shields.io/pypi/v/winiutils?logo=pypi&logoColor=white)](https://pypi.org/project/winiutils/)
+[![Python](https://img.shields.io/badge/python-3.12|3.13|3.14-blue.svg?logo=python&logoColor=white)](https://www.python.org/)
+[![License](https://img.shields.io/github/license/Winipedia/winiutils)](https://github.com/Winipedia/winiutils/blob/main/LICENSE)
+<!-- ci/cd -->
+[![CI](https://img.shields.io/github/actions/workflow/status/Winipedia/winiutils/health_check.yaml?label=CI&logo=github)](https://github.com/Winipedia/winiutils/actions/workflows/health_check.yaml)
+[![CD](https://img.shields.io/github/actions/workflow/status/Winipedia/winiutils/release.yaml?label=CD&logo=github)](https://github.com/Winipedia/winiutils/actions/workflows/release.yaml)
+
+
+---
+
+> A utility library for Python development
+
+---
+
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Documentation](#documentation)
+- [Modules](#modules)
+- [Development](#development)
+- [License](#license)
+
+---
+
+## Features
+
+- **DataFrame Cleaning Pipeline** — Extensible Polars DataFrame cleaning with an 8-step pipeline
+- **Concurrent Processing** — Unified multiprocessing and multithreading with automatic resource optimization
+- **OOP Utilities** — Metaclasses and mixins for automatic method logging and instrumentation
+- **Security Tools** — OS keyring integration and AES-GCM encryption utilities
+- **Type Safety** — Full type hints with strict mypy compliance
+- **Production Ready** — Comprehensive test coverage and logging integration
+
+---
+
+## Installation
+
+### Using uv (recommended)
+
+```bash
+uv add winiutils
+```
+
+### Using pip
+
+```bash
+pip install winiutils
+```
+
+### From source
+
+```bash
+git clone https://github.com/Winipedia/winiutils.git
+cd winiutils
+uv sync
+```
+
+---
+
+## Quick Start
+
+### DataFrame Cleaning
+
+```python
+from winiutils.src.data.dataframe.cleaning import CleaningDF
+import polars as pl
+
+class UserDataCleaner(CleaningDF):
+    """Clean and standardize user data."""
+
+    USER_ID = "user_id"
+    EMAIL = "email"
+    SCORE = "score"
+
+    @classmethod
+    def get_rename_map(cls):
+        return {cls.USER_ID: "UserId", cls.EMAIL: "Email", cls.SCORE: "Score"}
+
+    @classmethod
+    def get_col_dtype_map(cls):
+        return {cls.USER_ID: pl.Int64, cls.EMAIL: pl.Utf8, cls.SCORE: pl.Float64}
+
+    # ... implement other abstract methods
+
+# Usage
+cleaned = UserDataCleaner(raw_dataframe)
+result = cleaned.df
+```
+
+### Concurrent Processing
+
+```python
+from winiutils.src.iterating.concurrent.multiprocessing import multiprocess_loop
+from winiutils.src.iterating.concurrent.multithreading import multithread_loop
+
+# CPU-bound tasks (multiprocessing)
+def process_chunk(data, config):
+    return heavy_computation(data, config)
+
+results = multiprocess_loop(
+    process_function=process_chunk,
+    process_args=[(chunk,) for chunk in data_chunks],
+    process_args_static=(config,),
+    process_args_len=len(data_chunks),
+)
+
+# I/O-bound tasks (multithreading)
+def fetch_url(url, headers):
+    return requests.get(url, headers=headers)
+
+results = multithread_loop(
+    process_function=fetch_url,
+    process_args=[(url,) for url in urls],
+    process_args_static=(headers,),
+    process_args_len=len(urls),
+)
+```
+
+### Automatic Method Logging
+
+```python
+from winiutils.src.oop.mixins.mixin import ABCLoggingMixin
+
+class MyService(ABCLoggingMixin):
+    def process_data(self, data: list) -> dict:
+        # Automatically logged with timing
+        return {"processed": len(data)}
+
+# Logs: "MyService - Calling process_data with (...) and {...}"
+# Logs: "MyService - process_data finished with 0.5 seconds -> returning {...}"
+```
+
+### Encryption with Keyring
+
+```python
+from winiutils.src.security.keyring import get_or_create_aes_gcm
+from winiutils.src.security.cryptography import encrypt_with_aes_gcm, decrypt_with_aes_gcm
+
+# Get or create encryption key (stored in OS keyring)
+aes_gcm, key = get_or_create_aes_gcm("my_app", "user@example.com")
+
+# Encrypt and decrypt
+encrypted = encrypt_with_aes_gcm(aes_gcm, b"Secret message")
+decrypted = decrypt_with_aes_gcm(aes_gcm, encrypted)
+```
+
+---
+
+## Documentation
+
+Full documentation is available in the [docs](./docs/) folder:
+
+- [**Data Processing**](./docs/data.md) — DataFrame cleaning pipeline and data structures
+- [**Iterating & Concurrency**](./docs/iterating.md) — Parallel processing utilities
+- [**OOP Utilities**](./docs/oop.md) — Metaclasses and mixins
+- [**Security**](./docs/security.md) — Encryption and keyring integration
+
+---
+
+## Modules
+
+| Module | Description |
+|--------|-------------|
+| [`winiutils.src.data`](./docs/data.md) | DataFrame cleaning pipeline and data structure utilities |
+| [`winiutils.src.iterating`](./docs/iterating.md) | Concurrent processing with multiprocessing and multithreading |
+| [`winiutils.src.oop`](./docs/oop.md) | Metaclasses and mixins for automatic method logging |
+| [`winiutils.src.security`](./docs/security.md) | AES-GCM encryption and OS keyring integration |
+
+---
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/Winipedia/winiutils.git
+cd winiutils
+uv sync --all-groups
+```
+
+### Running Tests
+
+```bash
+uv run pytest
+```
+
+### Code Quality
+
+```bash
+# Linting
+uv run ruff check .
+
+# Type checking
+uv run mypy .
+
+# Security scanning
+uv run bandit -r winiutils/
+```
+
+### Pre-commit Hooks
+
+```bash
+uv run pre-commit install
+uv run pre-commit run --all-files
+```
+
+---
+
+## Project Structure
+
+```
+winiutils/
+├── src/                          # Main source code
+│   ├── data/                     # Data processing
+│   │   ├── dataframe/            # Polars DataFrame cleaning
+│   │   └── structures/           # Dicts, text utilities
+│   ├── iterating/                # Iteration utilities
+│   │   └── concurrent/           # Multiprocessing & multithreading
+│   ├── oop/                      # OOP patterns
+│   │   └── mixins/               # Logging metaclass & mixin
+│   └── security/                 # Security utilities
+│       ├── cryptography.py       # AES-GCM encryption
+│       └── keyring.py            # OS keyring integration
+├── dev/                          # Development tools
+│   ├── cli/                      # CLI subcommands
+│   └── tests/fixtures/           # Test fixtures
+├── docs/                         # Documentation
+└── tests/                        # Test suite
+```
+
+---
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+## Contributing
+
+Contributions are welcome! Please ensure:
+
+1. All tests pass (`uv run pytest`)
+2. Code passes linting (`uv run ruff check .`)
+3. Types are correct (`uv run mypy .`)
+4. New features include tests
+5. Documentation is updated for API changes

winiutils-2.3.13/README.md

@@ -0,0 +1,263 @@
+# winiutils
+
+<!-- tooling -->
+[![pyrig](https://img.shields.io/badge/built%20with-pyrig-3776AB?logo=buildkite&logoColor=black)](https://github.com/Winipedia/pyrig)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://pre-commit.com/)
+<!-- code-quality -->
+[![ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)[![mypy](https://img.shields.io/badge/type%20checked-mypy-039dfc.svg)](https://mypy-lang.org/)
+[![security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
+[![pytest](https://img.shields.io/badge/tested%20with-pytest-46a2f1.svg?logo=pytest)](https://pytest.org/)
+[![codecov](https://codecov.io/gh/Winipedia/winiutils/branch/main/graph/badge.svg)](https://codecov.io/gh/Winipedia/winiutils)
+<!-- package-info -->
+[![PyPI](https://img.shields.io/pypi/v/winiutils?logo=pypi&logoColor=white)](https://pypi.org/project/winiutils/)
+[![Python](https://img.shields.io/badge/python-3.12|3.13|3.14-blue.svg?logo=python&logoColor=white)](https://www.python.org/)
+[![License](https://img.shields.io/github/license/Winipedia/winiutils)](https://github.com/Winipedia/winiutils/blob/main/LICENSE)
+<!-- ci/cd -->
+[![CI](https://img.shields.io/github/actions/workflow/status/Winipedia/winiutils/health_check.yaml?label=CI&logo=github)](https://github.com/Winipedia/winiutils/actions/workflows/health_check.yaml)
+[![CD](https://img.shields.io/github/actions/workflow/status/Winipedia/winiutils/release.yaml?label=CD&logo=github)](https://github.com/Winipedia/winiutils/actions/workflows/release.yaml)
+
+
+---
+
+> A utility library for Python development
+
+---
+
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Documentation](#documentation)
+- [Modules](#modules)
+- [Development](#development)
+- [License](#license)
+
+---
+
+## Features
+
+- **DataFrame Cleaning Pipeline** — Extensible Polars DataFrame cleaning with an 8-step pipeline
+- **Concurrent Processing** — Unified multiprocessing and multithreading with automatic resource optimization
+- **OOP Utilities** — Metaclasses and mixins for automatic method logging and instrumentation
+- **Security Tools** — OS keyring integration and AES-GCM encryption utilities
+- **Type Safety** — Full type hints with strict mypy compliance
+- **Production Ready** — Comprehensive test coverage and logging integration
+
+---
+
+## Installation
+
+### Using uv (recommended)
+
+```bash
+uv add winiutils
+```
+
+### Using pip
+
+```bash
+pip install winiutils
+```
+
+### From source
+
+```bash
+git clone https://github.com/Winipedia/winiutils.git
+cd winiutils
+uv sync
+```
+
+---
+
+## Quick Start
+
+### DataFrame Cleaning
+
+```python
+from winiutils.src.data.dataframe.cleaning import CleaningDF
+import polars as pl
+
+class UserDataCleaner(CleaningDF):
+    """Clean and standardize user data."""
+
+    USER_ID = "user_id"
+    EMAIL = "email"
+    SCORE = "score"
+
+    @classmethod
+    def get_rename_map(cls):
+        return {cls.USER_ID: "UserId", cls.EMAIL: "Email", cls.SCORE: "Score"}
+
+    @classmethod
+    def get_col_dtype_map(cls):
+        return {cls.USER_ID: pl.Int64, cls.EMAIL: pl.Utf8, cls.SCORE: pl.Float64}
+
+    # ... implement other abstract methods
+
+# Usage
+cleaned = UserDataCleaner(raw_dataframe)
+result = cleaned.df
+```
+
+### Concurrent Processing
+
+```python
+from winiutils.src.iterating.concurrent.multiprocessing import multiprocess_loop
+from winiutils.src.iterating.concurrent.multithreading import multithread_loop
+
+# CPU-bound tasks (multiprocessing)
+def process_chunk(data, config):
+    return heavy_computation(data, config)
+
+results = multiprocess_loop(
+    process_function=process_chunk,
+    process_args=[(chunk,) for chunk in data_chunks],
+    process_args_static=(config,),
+    process_args_len=len(data_chunks),
+)
+
+# I/O-bound tasks (multithreading)
+def fetch_url(url, headers):
+    return requests.get(url, headers=headers)
+
+results = multithread_loop(
+    process_function=fetch_url,
+    process_args=[(url,) for url in urls],
+    process_args_static=(headers,),
+    process_args_len=len(urls),
+)
+```
+
+### Automatic Method Logging
+
+```python
+from winiutils.src.oop.mixins.mixin import ABCLoggingMixin
+
+class MyService(ABCLoggingMixin):
+    def process_data(self, data: list) -> dict:
+        # Automatically logged with timing
+        return {"processed": len(data)}
+
+# Logs: "MyService - Calling process_data with (...) and {...}"
+# Logs: "MyService - process_data finished with 0.5 seconds -> returning {...}"
+```
+
+### Encryption with Keyring
+
+```python
+from winiutils.src.security.keyring import get_or_create_aes_gcm
+from winiutils.src.security.cryptography import encrypt_with_aes_gcm, decrypt_with_aes_gcm
+
+# Get or create encryption key (stored in OS keyring)
+aes_gcm, key = get_or_create_aes_gcm("my_app", "user@example.com")
+
+# Encrypt and decrypt
+encrypted = encrypt_with_aes_gcm(aes_gcm, b"Secret message")
+decrypted = decrypt_with_aes_gcm(aes_gcm, encrypted)
+```
+
+---
+
+## Documentation
+
+Full documentation is available in the [docs](./docs/) folder:
+
+- [**Data Processing**](./docs/data.md) — DataFrame cleaning pipeline and data structures
+- [**Iterating & Concurrency**](./docs/iterating.md) — Parallel processing utilities
+- [**OOP Utilities**](./docs/oop.md) — Metaclasses and mixins
+- [**Security**](./docs/security.md) — Encryption and keyring integration
+
+---
+
+## Modules
+
+| Module | Description |
+|--------|-------------|
+| [`winiutils.src.data`](./docs/data.md) | DataFrame cleaning pipeline and data structure utilities |
+| [`winiutils.src.iterating`](./docs/iterating.md) | Concurrent processing with multiprocessing and multithreading |
+| [`winiutils.src.oop`](./docs/oop.md) | Metaclasses and mixins for automatic method logging |
+| [`winiutils.src.security`](./docs/security.md) | AES-GCM encryption and OS keyring integration |
+
+---
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/Winipedia/winiutils.git
+cd winiutils
+uv sync --all-groups
+```
+
+### Running Tests
+
+```bash
+uv run pytest
+```
+
+### Code Quality
+
+```bash
+# Linting
+uv run ruff check .
+
+# Type checking
+uv run mypy .
+
+# Security scanning
+uv run bandit -r winiutils/
+```
+
+### Pre-commit Hooks
+
+```bash
+uv run pre-commit install
+uv run pre-commit run --all-files
+```
+
+---
+
+## Project Structure
+
+```
+winiutils/
+├── src/                          # Main source code
+│   ├── data/                     # Data processing
+│   │   ├── dataframe/            # Polars DataFrame cleaning
+│   │   └── structures/           # Dicts, text utilities
+│   ├── iterating/                # Iteration utilities
+│   │   └── concurrent/           # Multiprocessing & multithreading
+│   ├── oop/                      # OOP patterns
+│   │   └── mixins/               # Logging metaclass & mixin
+│   └── security/                 # Security utilities
+│       ├── cryptography.py       # AES-GCM encryption
+│       └── keyring.py            # OS keyring integration
+├── dev/                          # Development tools
+│   ├── cli/                      # CLI subcommands
+│   └── tests/fixtures/           # Test fixtures
+├── docs/                         # Documentation
+└── tests/                        # Test suite
+```
+
+---
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+## Contributing
+
+Contributions are welcome! Please ensure:
+
+1. All tests pass (`uv run pytest`)
+2. Code passes linting (`uv run ruff check .`)
+3. Types are correct (`uv run mypy .`)
+4. New features include tests
+5. Documentation is updated for API changes

winiutils-2.3.13/pyproject.toml

@@ -0,0 +1,120 @@
+[project]
+name = "winiutils"
+version = "2.3.13"
+description = "A utility library for Python development"
+license = "MIT"
+requires-python = ">=3.12"
+authors = [
+    {name = "Winipedia"},
+]
+readme = "README.md"
+dependencies = [
+    "cryptography",
+    "defusedxml",
+    "keyring",
+    "keyrings-alt",
+    "polars",
+    "pyrig",
+    "tqdm",
+]
+classifiers = [
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+license-files = [
+    "LICENSE",
+]
+
+[project.scripts]
+winipedia-utils = "pyrig.dev.cli.cli:main"
+winiutils = "pyrig.dev.cli.cli:main"
+
+[dependency-groups]
+dev = [
+    "bandit",
+    "dotenv",
+    "mypy",
+    "pillow",
+    "pre-commit",
+    "pygithub",
+    "pyinstaller",
+    "pytest",
+    "pytest-cov",
+    "pytest-mock",
+    "pyyaml",
+    "ruff",
+    "setuptools",
+    "tenacity",
+    "tomlkit",
+    "ty",
+    "types-defusedxml",
+    "types-pyinstaller",
+    "types-pyyaml",
+    "types-setuptools",
+    "types-tqdm",
+]
+
+[build-system]
+requires = [
+    "uv_build",
+]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "winiutils"
+module-root = ""
+
+[tool.ruff]
+exclude = [
+    ".*",
+    "**/migrations/*.py",
+]
+
+[tool.ruff.lint]
+select = [
+    "ALL",
+]
+ignore = [
+    "D203",
+    "D213",
+    "COM812",
+    "ANN401",
+]
+fixable = [
+    "ALL",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    "S101",
+]
+"**/tests/**/*.py" = [
+    "S101",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.mypy]
+strict = true
+warn_unreachable = true
+show_error_codes = true
+files = "."
+
+[tool.pytest.ini_options]
+testpaths = [
+    "tests",
+]
+addopts = "--cov=winiutils --cov-report=term-missing --cov-fail-under=90"
+
+[tool.bandit]
+exclude_dirs = [
+    ".*",
+]
+
+[tool.bandit.assert_used]
+skips = [
+    "*/tests/*.py",
+    "*test_*.py",
+]

winiutils-2.3.13/winiutils/dev/tests/fixtures/fixtures.py

@@ -0,0 +1,32 @@
+"""Fixtures for testing.
+
+This module provides custom fixtures for pytest that can be pluued into tests
+across the entire test suite.
+All fixtures defined under the fixtures package are auto plugged in automatically
+by pyrig via the pytest_plugins mechanism.
+"""
+
+from collections.abc import Callable, Iterator
+
+import keyring
+import pytest
+
+
+@pytest.fixture
+def keyring_cleanup() -> Iterator[Callable[[str, str], None]]:
+    """Factory fixture to clean up keyring entries after test.
+
+    Usage:
+        def test_something(keyring_cleanup):
+            keyring_cleanup("service_name", "username")
+            # ... test code that creates keyring entries ...
+    """
+    entries: list[tuple[str, str]] = []
+
+    def register(service_name: str, username: str) -> None:
+        entries.append((service_name, username))
+
+    yield register
+
+    for service_name, username in entries:
+        keyring.delete_password(service_name, username)

winiutils-2.3.13/winiutils/main.py

@@ -0,0 +1,9 @@
+"""Main entrypoint for the project."""
+
+
+def main() -> None:
+    """Main entrypoint for the project."""
+
+
+if __name__ == "__main__":
+    main()