quantum-framework 0.18.0__py3-none-any.whl

quantum/runtime/param_validation.py

@@ -0,0 +1,218 @@
+"""UMA implementacao de `q:param`, usada pelos dois lugares que validam.
+
+Havia duas, e elas discordavam.
+
+`ComponentRuntime._coerce_param` (quantum/runtime/component.py) aceitava
+`integer|int|long` e `number|numeric|decimal|float|double`, deixava
+string/file/array/object como estavam e aplicava min/max a qualquer valor
+que virasse numero. `ActionHandler._validate_type`
+(quantum/runtime/action_handler.py) conhecia so `integer`, `decimal` e
+`float`, e tudo o mais caia num `return str(value)` final. O mesmo
+
+    <q:param name="idade" type="number" min="18" />
+
+era um float com minimo checado dentro de um componente e a STRING "7" sem
+checagem nenhuma dentro de um `q:action` — 32 arquivos .q do repositorio
+usam `type="number"`, todos nessa situacao quando estao num action.
+
+O caso pior era `type="file"`, que 5 arquivos entregues usam:
+
+    <q:param name="avatar" type="file" required="true" />
+    <q:file action="upload" file="{avatar}" destination="..." />
+
+O `str(value)` final transformava o objeto de upload na sua repr —
+`"<FileStorage: 'foto.png' ('image/png')>"` — e o `q:file` recebia essa
+string no lugar do arquivo. Upload por formulario nao funcionava, e o
+sintoma nao apontava para lugar nenhum.
+
+Este modulo e a uniao das duas: a coercao do componente mais as validacoes
+de `email`/`url` que so o action tinha, mais um tipo de arquivo que nunca e
+convertido para texto.
+"""
+
+import logging
+import re
+from typing import Any, List, Optional, Tuple
+
+from quantum.core.expressions import coerce_number
+
+logger = logging.getLogger('quantum.param')
+
+INT_TYPES = ('integer', 'int', 'long')
+FLOAT_TYPES = ('number', 'numeric', 'decimal', 'float', 'double')
+FILE_TYPES = ('file', 'binary', 'upload')
+# Tipos que passam intactos: converter mudaria dado que o destino espera
+# receber como veio.
+PASSTHROUGH_TYPES = ('string', 'text', 'array', 'object', 'any', 'json')
+
+# FN-4: what q:function returnType= accepts ('void': returns nothing).
+RETURN_TYPES = frozenset(INT_TYPES + FLOAT_TYPES + PASSTHROUGH_TYPES + ('boolean', 'email', 'url', 'void'))
+
+_EMAIL = re.compile(r'^[^@\s]+@[^@\s]+\.[^@\s]+$')
+_URL = re.compile(r'^https?://', re.IGNORECASE)
+
+
+def is_uploaded_file(value: Any) -> bool:
+    """Um upload (werkzeug FileStorage ou equivalente).
+
+    Checado por forma, nao por import: o werkzeug e opcional, e uma checagem
+    por isinstance obrigaria a importa-lo so para decidir se um valor pode
+    virar texto.
+    """
+    return hasattr(value, 'filename') and hasattr(value, 'read')
+
+
+def coerce(param_def, value: Any) -> Tuple[Any, Optional[str]]:
+    """Devolve (valor_convertido, erro). Erro None quando esta tudo bem."""
+    ptype = (getattr(param_def, 'type', None) or 'string').lower()
+    name = getattr(param_def, 'name', '?')
+
+    if ptype in FILE_TYPES:
+        if value is None or is_uploaded_file(value):
+            return value, None
+        return value, (
+            f"Parameter '{name}' must be an uploaded file, got "
+            f"{type(value).__name__}")
+
+    # Um arquivo nunca vira texto nem numero. Antes, `str(value)` produzia a
+    # repr do FileStorage e o resto do fluxo trabalhava com ela.
+    if is_uploaded_file(value):
+        return value, (
+            f"Parameter '{name}' received an uploaded file but is declared "
+            f"type=\"{ptype}\" — use type=\"file\"")
+
+    if ptype in INT_TYPES:
+        if isinstance(value, bool):
+            return value, f"Parameter '{name}' must be an integer"
+        if isinstance(value, int):
+            return value, None
+        try:
+            return int(str(value).strip()), None
+        except (TypeError, ValueError):
+            return value, f"Parameter '{name}' must be an integer, got {value!r}"
+
+    if ptype in FLOAT_TYPES:
+        if isinstance(value, bool):
+            return value, f"Parameter '{name}' must be a number"
+        # Same rule as q:set type="number" (ERR-1): "30" is 30, "2.5" is 2.5.
+        # float() made every form number a float, so "30" displayed as 30.0.
+        numero = coerce_number(value) if isinstance(value, str) else value
+        if isinstance(numero, (int, float)) and not isinstance(numero, bool):
+            return (float(numero) if ptype in ('decimal', 'float', 'double') else numero), None
+        return value, f"Parameter '{name}' must be a number, got {value!r}"
+
+    if ptype == 'boolean':
+        if isinstance(value, bool):
+            return value, None
+        text = str(value).strip().lower()
+        if text in ('true', 'yes', '1', 'on'):
+            return True, None
+        if text in ('false', 'no', '0', 'off', ''):
+            return False, None
+        return value, f"Parameter '{name}' must be a boolean, got {value!r}"
+
+    if ptype == 'email':
+        text = str(value)
+        if not _EMAIL.match(text):
+            return value, f"Parameter '{name}' must be a valid email"
+        return text, None
+
+    if ptype == 'url':
+        text = str(value)
+        if not _URL.match(text):
+            return value, f"Parameter '{name}' must be a valid URL"
+        return text, None
+
+    return value, None
+
+
+def check_rules(param_def, value: Any) -> List[str]:
+    """min/max/minlength/maxlength/pattern/enum."""
+    errors: List[str] = []
+    name = getattr(param_def, 'name', '?')
+
+    # Nada de comprimento, faixa ou padrao faz sentido sobre um arquivo. O que
+    # vale para um upload e accept= (ACT-11).
+    if is_uploaded_file(value):
+        accept = getattr(param_def, 'accept', None)
+        if accept and not accepts_file(value, accept):
+            errors.append(f"Parameter '{name}' accepts {accept}; got "
+                          f"'{getattr(value, 'filename', '')}'")
+        return errors
+
+    minimo = getattr(param_def, 'min', None)
+    maximo = getattr(param_def, 'max', None)
+    if minimo is not None or maximo is not None:
+        try:
+            numeric = float(value)
+        except (TypeError, ValueError):
+            numeric = None
+        if numeric is not None:
+            for bound, comparison, word in (
+                (minimo, lambda a, b: a < b, "at least"),
+                (maximo, lambda a, b: a > b, "at most"),
+            ):
+                if bound is None:
+                    continue
+                try:
+                    limit = float(bound)
+                except (TypeError, ValueError):
+                    continue
+                if comparison(numeric, limit):
+                    errors.append(
+                        f"Parameter '{name}' must be {word} {bound} "
+                        f"(got {value})")
+
+    if isinstance(value, str):
+        minlength = getattr(param_def, 'minlength', None)
+        maxlength = getattr(param_def, 'maxlength', None)
+        if minlength is not None and len(value) < minlength:
+            errors.append(
+                f"Parameter '{name}' must be at least {minlength} characters")
+        if maxlength is not None and len(value) > maxlength:
+            errors.append(
+                f"Parameter '{name}' must be at most {maxlength} characters")
+        pattern = getattr(param_def, 'pattern', None)
+        if pattern:
+            try:
+                if not re.search(pattern, value):
+                    errors.append(
+                        f"Parameter '{name}' does not match {pattern!r}")
+            except re.error as exc:
+                logger.warning(
+                    "q:param %s has an invalid pattern %r: %s",
+                    name, pattern, exc)
+
+    enum = getattr(param_def, 'enum', None)
+    if enum:
+        allowed = [v.strip() for v in str(enum).split(',') if v.strip()]
+        if allowed and str(value) not in allowed:
+            errors.append(
+                f"Parameter '{name}' must be one of: {', '.join(allowed)}")
+
+    return errors
+
+
+def accepts_file(upload, accept: str) -> bool:
+    """ACT-11: does an upload match an HTML-style accept list (".pdf", "image/*")?
+
+    The Content-Type an upload declares comes from the browser, so a MIME
+    pattern is matched against the type the FILE NAME implies as well: an
+    .exe sent as image/png does not pass image/*. An extension pattern is
+    matched against the file name.
+    """
+    import mimetypes
+    nome = (getattr(upload, 'filename', '') or '').lower()
+    pelo_nome = (mimetypes.guess_type(nome)[0] or '').lower()
+    declarado = (getattr(upload, 'content_type', '') or '').split(';')[0].strip().lower()
+    for item in (a.strip().lower() for a in accept.split(',') if a.strip()):
+        if item.startswith('.'):
+            if nome.endswith(item):
+                return True
+        elif item.endswith('/*'):
+            base = item[:-1]
+            if pelo_nome.startswith(base) and (not declarado or declarado.startswith(base)):
+                return True
+        elif pelo_nome == item and (not declarado or declarado == item):
+            return True
+    return False

quantum/runtime/pypy_compat.py

@@ -0,0 +1,317 @@
+"""
+PyPy Compatibility Module - Phase 3 Performance Optimization
+
+Ensures Quantum Framework runs correctly on both CPython and PyPy.
+PyPy provides automatic JIT compilation for 5-10x speedup on hot paths.
+
+Features:
+- Runtime detection of Python implementation
+- Alternative implementations for incompatible code
+- Performance recommendations for PyPy users
+- Dependency compatibility checks
+
+Usage:
+    from quantum.runtime.pypy_compat import is_pypy, get_implementation_info
+
+    if is_pypy():
+        # PyPy-specific optimizations
+        pass
+"""
+
+import sys
+import platform
+from typing import Dict, Any, List, Tuple, Optional
+from dataclasses import dataclass
+
+
+# Runtime detection
+def is_pypy() -> bool:
+    """Check if running on PyPy"""
+    return platform.python_implementation() == 'PyPy'
+
+
+def is_cpython() -> bool:
+    """Check if running on CPython"""
+    return platform.python_implementation() == 'CPython'
+
+
+def get_python_version() -> Tuple[int, int, int]:
+    """Get Python version as tuple"""
+    return sys.version_info[:3]
+
+
+def get_implementation_info() -> Dict[str, Any]:
+    """Get detailed information about the Python implementation"""
+    return {
+        'implementation': platform.python_implementation(),
+        'version': platform.python_version(),
+        'version_tuple': get_python_version(),
+        'compiler': platform.python_compiler(),
+        'is_pypy': is_pypy(),
+        'is_cpython': is_cpython(),
+        'is_64bit': sys.maxsize > 2**32,
+        'platform': sys.platform,
+    }
+
+
+@dataclass
+class CompatibilityResult:
+    """Result of a compatibility check"""
+    name: str
+    compatible: bool
+    message: str
+    severity: str  # 'info', 'warning', 'error'
+    workaround: Optional[str] = None
+
+
+class DependencyChecker:
+    """
+    Check compatibility of dependencies with PyPy.
+
+    Some packages have C extensions that may not work with PyPy.
+    This checker identifies potential issues.
+    """
+
+    # Known compatibility status of common dependencies
+    KNOWN_DEPS = {
+        # Fully compatible
+        'flask': ('compatible', 'Flask works well with PyPy'),
+        'jinja2': ('compatible', 'Jinja2 works well with PyPy'),
+        'click': ('compatible', 'Click works well with PyPy'),
+        'requests': ('compatible', 'Requests works well with PyPy'),
+        'pyyaml': ('compatible', 'PyYAML works with PyPy (pure Python mode)'),
+        'json': ('builtin', 'Standard library, fully compatible'),
+        'sqlite3': ('builtin', 'Standard library, fully compatible'),
+        'asyncio': ('builtin', 'Standard library, fully compatible'),
+        'pathlib': ('builtin', 'Standard library, fully compatible'),
+        're': ('builtin', 'Standard library, fully compatible'),
+
+        # Compatible with caveats
+        'lxml': ('caveat', 'lxml works but may need cffi version: pip install lxml-cffi'),
+        'numpy': ('caveat', 'NumPy works but performance may differ'),
+        'psutil': ('caveat', 'psutil requires cffi build'),
+        'watchdog': ('caveat', 'watchdog works but may need extra setup'),
+
+        # Potentially incompatible
+        'uvloop': ('incompatible', 'uvloop uses Cython, not compatible with PyPy'),
+        'cython': ('incompatible', 'Cython extensions not compatible with PyPy'),
+    }
+
+    @classmethod
+    def check_dependency(cls, name: str) -> CompatibilityResult:
+        """Check a single dependency for PyPy compatibility"""
+        name_lower = name.lower()
+
+        if name_lower in cls.KNOWN_DEPS:
+            status, message = cls.KNOWN_DEPS[name_lower]
+            compatible = status in ('compatible', 'builtin', 'caveat')
+            severity = 'info' if status in ('compatible', 'builtin') else \
+                      'warning' if status == 'caveat' else 'error'
+            return CompatibilityResult(
+                name=name,
+                compatible=compatible,
+                message=message,
+                severity=severity,
+            )
+
+        # Unknown - assume compatible but warn
+        return CompatibilityResult(
+            name=name,
+            compatible=True,
+            message=f'Unknown compatibility status for {name}',
+            severity='info',
+        )
+
+    @classmethod
+    def check_installed_packages(cls) -> List[CompatibilityResult]:
+        """Check all installed packages for PyPy compatibility"""
+        results = []
+
+        try:
+            import pkg_resources
+            for pkg in pkg_resources.working_set:
+                result = cls.check_dependency(pkg.key)
+                if result.severity in ('warning', 'error'):
+                    results.append(result)
+        except ImportError:
+            pass
+
+        return results
+
+    @classmethod
+    def check_quantum_dependencies(cls) -> List[CompatibilityResult]:
+        """Check Quantum Framework's core dependencies"""
+        core_deps = [
+            'flask',
+            'jinja2',
+            'click',
+            'pyyaml',
+            'requests',
+            'watchdog',
+        ]
+
+        return [cls.check_dependency(dep) for dep in core_deps]
+
+
+class PyPyOptimizer:
+    """
+    Provides PyPy-specific optimizations and recommendations.
+    """
+
+    @staticmethod
+    def get_recommendations() -> List[str]:
+        """Get performance recommendations for PyPy users"""
+        if not is_pypy():
+            return ['Not running on PyPy - no PyPy-specific recommendations']
+
+        return [
+            'PyPy JIT is warming up - first requests may be slower',
+            'Avoid using eval() in hot paths - use pre-compiled expressions',
+            'Large dictionaries perform well on PyPy',
+            'Use list comprehensions instead of map/filter for best JIT optimization',
+            'Avoid metaclasses in performance-critical code',
+            'PyPy startup is slower than CPython - use for long-running processes',
+            'Consider using PyPy 7.3+ for best compatibility',
+        ]
+
+    @staticmethod
+    def optimize_for_jit():
+        """
+        Apply PyPy-specific optimizations to help the JIT compiler.
+        Should be called during application startup.
+        """
+        if not is_pypy():
+            return
+
+        # Hint to PyPy JIT about frequently used functions
+        # This is mostly documentation - PyPy will optimize automatically
+        pass
+
+    @staticmethod
+    def warmup_jit(iterations: int = 1000):
+        """
+        Warm up PyPy JIT by running common operations.
+        Call this during application startup for faster first requests.
+
+        Args:
+            iterations: Number of warmup iterations
+        """
+        if not is_pypy():
+            return
+
+        # Warm up common operations
+        for _ in range(iterations):
+            # Dictionary operations
+            d = {'key': 'value', 'num': 42}
+            _ = d.get('key')
+            d['new'] = 'item'
+
+            # List operations
+            lst = [1, 2, 3, 4, 5]
+            _ = [x * 2 for x in lst]
+
+            # String operations
+            s = "hello world"
+            _ = s.upper()
+            _ = s.split()
+
+            # Arithmetic
+            x = 42
+            y = x * 2 + 10 - 5
+
+
+class QuantumPyPyAdapter:
+    """
+    Adapter that provides PyPy-compatible alternatives for
+    any CPython-specific code in Quantum Framework.
+    """
+
+    @staticmethod
+    def get_memory_usage() -> float:
+        """
+        Get current memory usage in MB.
+        Uses different methods for PyPy vs CPython.
+        """
+        try:
+            import psutil
+            process = psutil.Process()
+            return process.memory_info().rss / 1024 / 1024
+        except ImportError:
+            # Fallback for when psutil is not available. `resource` is
+            # POSIX-only: importing it outside the try crashed this on Windows
+            # instead of falling back.
+            try:
+                import resource
+                return resource.getrusage(resource.RUSAGE_SELF).ru_maxrss / 1024
+            except (ImportError, OSError, ValueError):
+                return 0.0
+
+    @staticmethod
+    def gc_collect():
+        """
+        Force garbage collection.
+        PyPy has different GC behavior than CPython.
+        """
+        import gc
+        gc.collect()
+
+        if is_pypy():
+            # PyPy may need multiple collections
+            gc.collect()
+            gc.collect()
+
+    @staticmethod
+    def compile_expression(expr: str, mode: str = 'eval'):
+        """
+        Compile a Python expression.
+        Both CPython and PyPy support this identically.
+        """
+        return compile(expr, '<quantum-expr>', mode)
+
+
+def print_compatibility_report():
+    """Print a detailed compatibility report for the current environment"""
+    info = get_implementation_info()
+
+    print("\n" + "=" * 60)
+    print("  QUANTUM FRAMEWORK - PYTHON COMPATIBILITY REPORT")
+    print("=" * 60)
+
+    print(f"\n  Implementation: {info['implementation']}")
+    print(f"  Version: {info['version']}")
+    print(f"  Platform: {info['platform']}")
+    print(f"  64-bit: {info['is_64bit']}")
+
+    if is_pypy():
+        print("\n  Status: Running on PyPy (JIT enabled)")
+        print("\n  Recommendations:")
+        for rec in PyPyOptimizer.get_recommendations():
+            print(f"    - {rec}")
+    else:
+        print("\n  Status: Running on CPython")
+        print("\n  To use PyPy for better performance:")
+        print("    1. Install PyPy 3.9+ from https://www.pypy.org/")
+        print("    2. Create virtual environment: pypy3 -m venv venv-pypy")
+        print("    3. Install dependencies: pip install -r requirements.txt")
+        print("    4. Run Quantum: pypy3 src/cli/runner.py start")
+
+    print("\n  Dependency Compatibility:")
+    results = DependencyChecker.check_quantum_dependencies()
+    for result in results:
+        status = "OK" if result.compatible else "ISSUE"
+        print(f"    [{status}] {result.name}: {result.message}")
+
+    print("\n" + "=" * 60)
+
+
+# Export commonly used functions
+__all__ = [
+    'is_pypy',
+    'is_cpython',
+    'get_python_version',
+    'get_implementation_info',
+    'DependencyChecker',
+    'PyPyOptimizer',
+    'QuantumPyPyAdapter',
+    'print_compatibility_report',
+]