provide-foundation 0.0.0.dev0__py3-none-any.whl

provide/foundation/utils/__init__.py

@@ -0,0 +1,97 @@
+"""
+Utility modules for provide.foundation.
+
+Common utilities that can be used across the foundation and by other packages.
+"""
+
+from provide.foundation.utils.deps import (
+    DependencyStatus,
+    check_optional_deps,
+    get_available_features,
+    get_optional_dependencies,
+    has_dependency,
+    require_dependency,
+)
+from provide.foundation.utils.env import (
+    EnvPrefix,
+    get_bool,
+    get_dict,
+    get_float,
+    get_int,
+    get_list,
+    get_path,
+    get_str,
+    parse_duration,
+    parse_size,
+    require,
+)
+from provide.foundation.utils.formatting import (
+    format_duration,
+    format_number,
+    format_percentage,
+    format_size,
+    format_table,
+    indent,
+    pluralize,
+    strip_ansi,
+    to_camel_case,
+    to_kebab_case,
+    to_snake_case,
+    truncate,
+    wrap_text,
+)
+from provide.foundation.utils.parsing import (
+    auto_parse,
+    parse_bool,
+    parse_dict,
+    parse_list,
+    parse_typed_value,
+)
+from provide.foundation.utils.rate_limiting import TokenBucketRateLimiter
+from provide.foundation.utils.timing import timed_block
+
+__all__ = [
+    "EnvPrefix",
+    # Parsing utilities
+    "auto_parse",
+    # Dependency checking utilities
+    "check_optional_deps",
+    "DependencyStatus",
+    "format_duration",
+    "format_number",
+    "format_percentage",
+    # Formatting utilities
+    "format_size",
+    "format_table",
+    "get_available_features",
+    # Environment utilities
+    "get_bool",
+    "get_dict",
+    "get_float",
+    "get_int",
+    "get_list",
+    "get_optional_dependencies",
+    "get_path",
+    "get_str",
+    "has_dependency",
+    "indent",
+    "parse_bool",
+    "parse_dict",
+    "parse_duration",
+    "parse_list",
+    "parse_size",
+    "parse_typed_value",
+    "pluralize",
+    "require",
+    "require_dependency",
+    "strip_ansi",
+    # Timing utilities
+    "timed_block",
+    "to_camel_case",
+    # Rate limiting utilities
+    "TokenBucketRateLimiter",
+    "to_kebab_case",
+    "to_snake_case",
+    "truncate",
+    "wrap_text",
+]

provide/foundation/utils/deps.py

@@ -0,0 +1,195 @@
+"""Optional dependency checking utilities."""
+
+from typing import NamedTuple
+
+from provide.foundation.logger import get_logger
+
+log = get_logger(__name__)
+
+
+class DependencyStatus(NamedTuple):
+    """Status of an optional dependency."""
+
+    name: str
+    available: bool
+    version: str | None
+    description: str
+
+
+def _check_click() -> DependencyStatus:
+    """Check click availability."""
+    try:
+        import click
+
+        # Use importlib.metadata to avoid deprecation warning
+        try:
+            from importlib.metadata import version
+
+            ver = version("click")
+        except Exception:
+            ver = "unknown"
+        return DependencyStatus(
+            name="click",
+            available=True,
+            version=ver,
+            description="CLI features (console I/O, command building)",
+        )
+    except ImportError:
+        return DependencyStatus(
+            name="click",
+            available=False,
+            version=None,
+            description="CLI features (console I/O, command building)",
+        )
+
+
+def _check_cryptography() -> DependencyStatus:
+    """Check cryptography availability."""
+    try:
+        import cryptography
+
+        return DependencyStatus(
+            name="cryptography",
+            available=True,
+            version=cryptography.__version__,
+            description="Crypto features (keys, certificates, signatures)",
+        )
+    except ImportError:
+        return DependencyStatus(
+            name="cryptography",
+            available=False,
+            version=None,
+            description="Crypto features (keys, certificates, signatures)",
+        )
+
+
+def _check_opentelemetry() -> DependencyStatus:
+    """Check OpenTelemetry availability."""
+    try:
+        import opentelemetry
+
+        try:
+            from importlib.metadata import version
+
+            ver = version("opentelemetry-api")
+        except Exception:
+            ver = "unknown"
+        return DependencyStatus(
+            name="opentelemetry",
+            available=True,
+            version=ver,
+            description="Enhanced telemetry and tracing",
+        )
+    except ImportError:
+        return DependencyStatus(
+            name="opentelemetry",
+            available=False,
+            version=None,
+            description="Enhanced telemetry and tracing",
+        )
+
+
+def get_optional_dependencies() -> list[DependencyStatus]:
+    """Get status of all optional dependencies.
+
+    Returns:
+        List of dependency status objects
+    """
+    return [
+        _check_click(),
+        _check_cryptography(),
+        _check_opentelemetry(),
+    ]
+
+
+def check_optional_deps(
+    *, quiet: bool = False, return_status: bool = False
+) -> list[DependencyStatus] | None:
+    """Check and display optional dependency status.
+
+    Args:
+        quiet: If True, don't print status (just return it)
+        return_status: If True, return the status list
+
+    Returns:
+        Optional list of dependency statuses if return_status=True
+    """
+    deps = get_optional_dependencies()
+
+    if not quiet:
+        print("📦 provide-foundation Optional Dependencies Status")
+        print("=" * 50)
+
+        available_count = sum(1 for dep in deps if dep.available)
+        total_count = len(deps)
+
+        for dep in deps:
+            status_icon = "✅" if dep.available else "❌"
+            version_info = f" (v{dep.version})" if dep.version else ""
+            print(f"  {status_icon} {dep.name}{version_info}")
+            print(f"     {dep.description}")
+            if not dep.available:
+                print(
+                    f"     Install with: pip install 'provide-foundation[{dep.name}]'"
+                )
+            print()
+
+        print(
+            f"📊 Summary: {available_count}/{total_count} optional dependencies available"
+        )
+
+        if available_count == total_count:
+            print("🎉 All optional features are available!")
+        elif available_count == 0:
+            print(
+                "💡 Install optional features with: pip install 'provide-foundation[all]'"
+            )
+        else:
+            missing = [dep.name for dep in deps if not dep.available]
+            print(f"💡 Missing features: {', '.join(missing)}")
+
+    if return_status:
+        return deps
+    return None
+
+
+def has_dependency(name: str) -> bool:
+    """Check if a specific optional dependency is available.
+
+    Args:
+        name: Name of the dependency to check
+
+    Returns:
+        True if dependency is available
+    """
+    deps = get_optional_dependencies()
+    for dep in deps:
+        if dep.name == name:
+            return dep.available
+    return False
+
+
+def require_dependency(name: str) -> None:
+    """Require a specific optional dependency, raise ImportError if missing.
+
+    Args:
+        name: Name of the dependency to require
+
+    Raises:
+        ImportError: If dependency is not available
+    """
+    if not has_dependency(name):
+        raise ImportError(
+            f"Optional dependency '{name}' is required for this feature. "
+            f"Install with: pip install 'provide-foundation[{name}]'"
+        )
+
+
+def get_available_features() -> dict[str, bool]:
+    """Get a dictionary of available optional features.
+
+    Returns:
+        Dictionary mapping feature names to availability
+    """
+    deps = get_optional_dependencies()
+    return {dep.name: dep.available for dep in deps}