pyw-core 🌐

Namespace seed & common utilities for the pythonWoods ecosystem.

Overview

pyw-core è il cuore dell'ecosistema pythonWoods, fornendo il namespace condiviso, utilities comuni e le basi architetturali per tutti i moduli. Anche se minimalista per design, è il fondamento che garantisce coerenza e interoperabilità tra tutti i package.

Ecosystem Overview

Package	Description	Status
pyw-core	Namespace & common utilities	0.0.0
pyw-logger	Structured logging (rich + structlog)	0.0.0
pyw-fs	Unified filesystem (local/S3/GCS)	0.0.0
pyw-secret	Secret backends (.env, Vault, SSM)	0.0.0
pyw-cli	Typer CLI scaffolding	0.0.0
pyw-config	Configuration utilities	0.0.0
pyw-vision	Vision utilities & helpers	0.0.0
pyw-motion	Motion detection & tracking	0.0.0
pyw-music21	Music21 stubs & helpers	0.0.0
pyw-musicparser	Parse MIDI/Lilypond	0.0.0

Bundle Packages

Bundle	Description	Includes
pyw-devtools	Developer toolkit	logger, fs, cli, secret, config
pyw-music	Music processing	music21, musicparser
pyw-cv	Computer vision	vision, motion

Philosophy

• Namespace package – import pyw.* per evitare conflitti e garantire coerenza
• Small, composable modules – scegli solo ciò che ti serve, zero bloat
• Typed APIs – Pydantic models e type hints per zero sorprese
• No heavy deps by default – librerie "pesanti" (Torch, OpenCV) come extras opzionali
• Interoperability-first – tutti i moduli condividono pattern e utilities comuni

Installation

pip install pyw-core

pyw-core è intenzionalmente minimalista: fornisce solo il namespace e utilities fondamentali condivise dall'ecosistema.

Core Features

🏗️ Base Classes

from pyw.core import BaseConfig, BaseModel
from pyw.core.types import PathLike, JsonDict

class MyConfig(BaseConfig):
    """Configurazione con validazione type-safe."""
    name: str
    debug: bool = False
    paths: list[PathLike] = []

class DataModel(BaseModel):
    """Modello dati con serializzazione automatica."""
    id: int
    metadata: JsonDict = {}

🔧 Common Utilities

from pyw.core.utils import (
    ensure_list, deep_merge, safe_import,
    classproperty, deprecated
)

# List normalization
items = ensure_list("single_item")  # → ["single_item"]
items = ensure_list(["already", "list"])  # → ["already", "list"]

# Deep dictionary merging
config = deep_merge(
    {"db": {"host": "localhost", "port": 5432}},
    {"db": {"port": 3306, "ssl": True}}
)
# → {"db": {"host": "localhost", "port": 3306, "ssl": True}}

# Safe imports con fallback
requests = safe_import("requests", fallback_message="pip install requests")

# Class properties
class MyClass:
    @classproperty
    def version(cls):
        return "1.0.0"

# Deprecation warnings
@deprecated("Use new_function() instead", version="2.0.0")
def old_function():
    pass

📦 Plugin Discovery

from pyw.core.plugins import discover_plugins, load_plugin

# Trova tutti i plugin pyw installati
plugins = discover_plugins("pyw.*")

# Carica plugin specifico
logger_plugin = load_plugin("pyw.logger")

🔍 Type Utilities

from pyw.core.types import (
    PathLike, JsonDict, OptionalStr,
    Singleton, classproperty
)
from typing import Any

# Type aliases comuni
def process_file(path: PathLike) -> JsonDict:
    """Accetta str, Path, o file-like objects."""
    pass

# Singleton pattern
class DatabaseConnection(Singleton):
    def __init__(self):
        self.connected = False

# Sempre la stessa istanza
db1 = DatabaseConnection()
db2 = DatabaseConnection()
assert db1 is db2

⚡ Performance Utilities

from pyw.core.performance import (
    timer, cache_result, rate_limit,
    memory_usage
)
import time

# Timing decorator
@timer
def slow_function():
    time.sleep(1)
    return "done"

result = slow_function()  # Logs: "slow_function took 1.002s"

# Result caching
@cache_result(ttl=300)  # Cache for 5 minutes
def expensive_computation(x: int) -> int:
    return x ** 2

# Rate limiting
@rate_limit(calls=10, period=60)  # Max 10 calls/minute
def api_call():
    pass

# Memory monitoring
with memory_usage() as mem:
    big_list = list(range(1000000))
print(f"Memory used: {mem.peak_mb:.1f} MB")

Integration Patterns

🔗 Module Integration

# Pattern per moduli pyw
from pyw.core import BaseModule

class MyModule(BaseModule):
    """Template per nuovi moduli pyw."""
    
    name = "my-module"
    version = "1.0.0"
    dependencies = ["pyw-core>=0.1.0"]
    
    def __init__(self, config=None):
        super().__init__()
        self.config = config or self.default_config()
    
    @classmethod
    def default_config(cls):
        return {"enabled": True}

🧪 Testing Support

from pyw.core.testing import (
    temporary_directory, mock_environment,
    assert_type_safe, benchmark
)

def test_my_function():
    with temporary_directory() as tmpdir:
        # Test con directory temporanea
        pass
    
    with mock_environment({"DEBUG": "true"}):
        # Test con environment variables mock
        pass
    
    # Type safety testing
    result = my_typed_function("input")
    assert_type_safe(result, MyExpectedType)
    
    # Performance benchmarking
    with benchmark("my_operation") as b:
        expensive_operation()
    assert b.elapsed < 1.0  # Max 1 second

Bundle Installation

Per installare gruppi di moduli correlati:

# Developer toolkit completo
pip install pyw-devtools  # logger + fs + cli + secret + config

# Music processing
pip install pyw-music     # music21 + musicparser  

# Computer vision
pip install pyw-cv        # vision + motion

Advanced Usage

🔌 Custom Extensions

from pyw.core.extensions import register_extension

@register_extension("mycompany.custom")
class CustomExtension:
    """Estensione personalizzata per pyw."""
    
    def setup(self):
        # Inizializzazione custom
        pass

# Auto-discovered da pyw.core.plugins

📊 Ecosystem Stats

from pyw.core import ecosystem_info

# Info sull'ecosistema installato
info = ecosystem_info()
print(f"Installed pyw modules: {len(info.modules)}")
for module in info.modules:
    print(f"  {module.name} v{module.version}")

🎯 Quality Assurance

from pyw.core.qa import (
    validate_module, check_compatibility,
    run_ecosystem_tests
)

# Valida un modulo pyw
issues = validate_module("pyw.mymodule")
if issues:
    for issue in issues:
        print(f"⚠️  {issue}")

# Check compatibilità tra moduli
compat = check_compatibility(["pyw-logger==1.0", "pyw-fs==2.0"])
assert compat.compatible

Development Tools

🏗️ Module Scaffolding

# Crea nuovo modulo pyw
pyw-core scaffold my-module --type=utility
cd pyw-my-module/

# Struttura generata:
# pyw-my-module/
# ├── pyw/
# │   └── my_module/
# │       ├── __init__.py
# │       └── core.py
# ├── tests/
# ├── pyproject.toml
# └── README.md

📋 Quality Checks

# Linting ecosystem-wide
pyw-core lint --all-modules

# Type checking
pyw-core mypy --strict

# Run all tests
pyw-core test --coverage

# Check dependencies
pyw-core deps --check-conflicts

Roadmap

• 🏗️ Enhanced utilities: Async helpers, concurrency utilities
• 📦 Plugin system: Hot-reloading, dependency injection
• 🔧 Dev experience: Better debugging, profiling integration
• 📚 Documentation: Auto-generated API docs, examples
• 🎯 Quality tools: Advanced linting, security scanning
• 🌐 Ecosystem: Package discovery, compatibility matrix
• ⚡ Performance: Caching strategies, optimization helpers

Contributing

pyw-core è il cuore dell'ecosistema - ogni contributo deve essere attentamente valutato:

1. Fork & Clone: git clone https://github.com/pythonWoods/pyw-core.git
2. Development setup: poetry install && poetry shell
3. Quality checks: ruff check . && mypy && pytest
4. Documentation: Aggiorna docs per ogni modifica API
5. Compatibility: Assicurati che le modifiche non rompano altri moduli
6. Pull Request: CI esegue test completi dell'ecosistema

Architecture Notes

pyw-core (namespace + utilities)
├── pyw/__init__.py          # Namespace package
├── pyw/core/
│   ├── __init__.py         # Public API exports
│   ├── base.py             # BaseConfig, BaseModel
│   ├── utils.py            # Common utilities  
│   ├── types.py            # Type aliases & helpers
│   ├── plugins.py          # Plugin discovery
│   ├── performance.py      # Performance tools
│   ├── testing.py          # Test utilities
│   └── exceptions.py       # Common exceptions
└── tests/                  # Comprehensive test suite

Felice coding nella foresta di pythonWoods! 🌲🐾

Links utili

Documentazione dev (work-in-progress) → https://pythonwoods.dev/docs/pyw-core/latest/

Issue tracker → https://github.com/pythonWoods/pyw-core/issues

Changelog → https://github.com/pythonWoods/pyw-core/releases

© pythonWoods — MIT License