htcli 1.1.0__py3-none-any.whl

src/htcli/utils/cache.py

@@ -0,0 +1,613 @@
+"""
+Caching utilities for HTCLI.
+
+This module provides efficient caching strategies for blockchain data
+to improve performance and reduce redundant API calls.
+"""
+
+import asyncio
+import hashlib
+import json
+import time
+from collections.abc import Awaitable, Callable
+from functools import wraps
+from pathlib import Path
+from typing import Any, Optional
+
+from ..utils.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class TTLCache:
+    """
+    Time-to-live cache implementation.
+
+    This cache automatically expires entries after a specified time period.
+    """
+
+    def __init__(self, default_ttl: float = 300.0, max_size: int = 1000):
+        """
+        Initialize TTL cache.
+
+        Args:
+            default_ttl: Default time-to-live in seconds
+            max_size: Maximum number of entries to store
+        """
+        self.default_ttl = default_ttl
+        self.max_size = max_size
+        self._cache: dict[str, dict[str, Any]] = {}
+        self._access_times: dict[str, float] = {}
+
+    def _is_expired(self, key: str) -> bool:
+        """Check if a cache entry is expired."""
+        if key not in self._cache:
+            return True
+
+        entry = self._cache[key]
+        if "expires_at" not in entry:
+            return True
+
+        return time.time() > entry["expires_at"]
+
+    def _cleanup_expired(self) -> None:
+        """Remove expired entries from cache."""
+        current_time = time.time()
+        expired_keys = []
+
+        for key, entry in self._cache.items():
+            if "expires_at" in entry and current_time > entry["expires_at"]:
+                expired_keys.append(key)
+
+        for key in expired_keys:
+            self._cache.pop(key, None)
+            self._access_times.pop(key, None)
+
+    def _evict_lru(self) -> None:
+        """Evict least recently used entry."""
+        if not self._access_times:
+            return
+
+        lru_key = min(self._access_times.keys(), key=lambda k: self._access_times[k])
+        self._cache.pop(lru_key, None)
+        self._access_times.pop(lru_key, None)
+
+    def get(self, key: str) -> Optional[Any]:
+        """
+        Get value from cache.
+
+        Args:
+            key: Cache key
+
+        Returns:
+            Cached value or None if not found/expired
+        """
+        if self._is_expired(key):
+            self._cache.pop(key, None)
+            self._access_times.pop(key, None)
+            return None
+
+        self._access_times[key] = time.time()
+        return self._cache[key]["value"]
+
+    def set(self, key: str, value: Any, ttl: Optional[float] = None) -> None:
+        """
+        Set value in cache.
+
+        Args:
+            key: Cache key
+            value: Value to cache
+            ttl: Time-to-live in seconds (uses default if None)
+        """
+        if ttl is None:
+            ttl = self.default_ttl
+
+        # Clean up expired entries
+        self._cleanup_expired()
+
+        # Evict LRU if at max size
+        if len(self._cache) >= self.max_size and key not in self._cache:
+            self._evict_lru()
+
+        expires_at = time.time() + ttl
+        self._cache[key] = {
+            "value": value,
+            "expires_at": expires_at,
+            "created_at": time.time(),
+        }
+        self._access_times[key] = time.time()
+
+    def delete(self, key: str) -> None:
+        """Delete entry from cache."""
+        self._cache.pop(key, None)
+        self._access_times.pop(key, None)
+
+    def clear(self) -> None:
+        """Clear all cache entries."""
+        self._cache.clear()
+        self._access_times.clear()
+
+    def size(self) -> int:
+        """Get current cache size."""
+        self._cleanup_expired()
+        return len(self._cache)
+
+    def stats(self) -> dict[str, Any]:
+        """Get cache statistics."""
+        self._cleanup_expired()
+
+        if not self._cache:
+            return {
+                "size": 0,
+                "max_size": self.max_size,
+                "hit_rate": 0.0,
+                "avg_ttl": 0.0,
+            }
+
+        total_ttl = sum(
+            entry["expires_at"] - entry["created_at"] for entry in self._cache.values()
+        )
+
+        return {
+            "size": len(self._cache),
+            "max_size": self.max_size,
+            "avg_ttl": total_ttl / len(self._cache),
+            "oldest_entry": min(entry["created_at"] for entry in self._cache.values()),
+            "newest_entry": max(entry["created_at"] for entry in self._cache.values()),
+        }
+
+    async def get_async(self, key: str) -> Optional[Any]:
+        """
+        Async version of get method.
+
+        Args:
+            key: Cache key
+
+        Returns:
+            Cached value or None if not found/expired
+        """
+        # Run the sync get in a thread pool to avoid blocking
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(None, self.get, key)
+
+    async def set_async(
+        self, key: str, value: Any, ttl: Optional[float] = None
+    ) -> None:
+        """
+        Async version of set method.
+
+        Args:
+            key: Cache key
+            value: Value to cache
+            ttl: Time-to-live in seconds (uses default if None)
+        """
+        # Run the sync set in a thread pool to avoid blocking
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(None, self.set, key, value, ttl)
+
+    async def delete_async(self, key: str) -> None:
+        """
+        Async version of delete method.
+
+        Args:
+            key: Cache key to delete
+        """
+        # Run the sync delete in a thread pool to avoid blocking
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(None, self.delete, key)
+
+
+class PersistentCache:
+    """
+    Persistent cache that saves data to disk.
+
+    This cache persists data across application restarts.
+    """
+
+    def __init__(self, cache_dir: Path, default_ttl: float = 3600.0):
+        """
+        Initialize persistent cache.
+
+        Args:
+            cache_dir: Directory to store cache files
+            default_ttl: Default time-to-live in seconds
+        """
+        self.cache_dir = cache_dir
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        self.default_ttl = default_ttl
+        self._memory_cache = TTLCache(default_ttl=default_ttl)
+
+    def _get_cache_file(self, key: str) -> Path:
+        """Get cache file path for a key."""
+        # Hash the key to create a safe filename
+        key_hash = hashlib.sha256(key.encode()).hexdigest()
+        return self.cache_dir / f"{key_hash}.json"
+
+    def get(self, key: str) -> Optional[Any]:
+        """
+        Get value from persistent cache.
+
+        Args:
+            key: Cache key
+
+        Returns:
+            Cached value or None if not found/expired
+        """
+        # Try memory cache first
+        value = self._memory_cache.get(key)
+        if value is not None:
+            return value
+
+        # Try disk cache
+        cache_file = self._get_cache_file(key)
+        if not cache_file.exists():
+            return None
+
+        try:
+            with open(cache_file) as f:
+                data = json.load(f)
+
+            # Check if expired
+            if time.time() > data["expires_at"]:
+                cache_file.unlink()
+                return None
+
+            # Load into memory cache
+            self._memory_cache.set(key, data["value"], data["expires_at"] - time.time())
+            return data["value"]
+
+        except Exception as e:
+            logger.warning(f"Error reading cache file {cache_file}: {e}")
+            return None
+
+    def set(self, key: str, value: Any, ttl: Optional[float] = None) -> None:
+        """
+        Set value in persistent cache.
+
+        Args:
+            key: Cache key
+            value: Value to cache
+            ttl: Time-to-live in seconds (uses default if None)
+        """
+        if ttl is None:
+            ttl = self.default_ttl
+
+        expires_at = time.time() + ttl
+
+        # Set in memory cache
+        self._memory_cache.set(key, value, ttl)
+
+        # Save to disk
+        cache_file = self._get_cache_file(key)
+        try:
+            data = {"value": value, "expires_at": expires_at, "created_at": time.time()}
+
+            with open(cache_file, "w") as f:
+                json.dump(data, f)
+
+        except Exception as e:
+            logger.warning(f"Error writing cache file {cache_file}: {e}")
+
+    def delete(self, key: str) -> None:
+        """Delete entry from persistent cache."""
+        self._memory_cache.delete(key)
+
+        cache_file = self._get_cache_file(key)
+        if cache_file.exists():
+            cache_file.unlink()
+
+    def clear(self) -> None:
+        """Clear all cache entries."""
+        self._memory_cache.clear()
+
+        # Remove all cache files
+        for cache_file in self.cache_dir.glob("*.json"):
+            cache_file.unlink()
+
+    def cleanup_expired(self) -> None:
+        """Clean up expired cache files."""
+        current_time = time.time()
+
+        for cache_file in self.cache_dir.glob("*.json"):
+            try:
+                with open(cache_file) as f:
+                    data = json.load(f)
+
+                if current_time > data["expires_at"]:
+                    cache_file.unlink()
+
+            except Exception as e:
+                logger.warning(f"Error cleaning up cache file {cache_file}: {e}")
+
+    async def get_async(self, key: str) -> Optional[Any]:
+        """
+        Async version of get method.
+
+        Args:
+            key: Cache key
+
+        Returns:
+            Cached value or None if not found/expired
+        """
+        # Run the sync get in a thread pool to avoid blocking
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(None, self.get, key)
+
+    async def set_async(
+        self, key: str, value: Any, ttl: Optional[float] = None
+    ) -> None:
+        """
+        Async version of set method.
+
+        Args:
+            key: Cache key
+            value: Value to cache
+            ttl: Time-to-live in seconds (uses default if None)
+        """
+        # Run the sync set in a thread pool to avoid blocking
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(None, self.set, key, value, ttl)
+
+    async def delete_async(self, key: str) -> None:
+        """
+        Async version of delete method.
+
+        Args:
+            key: Cache key to delete
+        """
+        # Run the sync delete in a thread pool to avoid blocking
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(None, self.delete, key)
+
+    async def cleanup_expired_async(self) -> None:
+        """Async version of cleanup_expired method."""
+        # Run the sync cleanup in a thread pool to avoid blocking
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(None, self.cleanup_expired)
+
+
+# Global cache instances
+_blockchain_cache: Optional[TTLCache] = None
+_persistent_cache: Optional[PersistentCache] = None
+
+
+def get_blockchain_cache() -> TTLCache:
+    """Get the global blockchain cache instance."""
+    global _blockchain_cache
+
+    if _blockchain_cache is None:
+        _blockchain_cache = TTLCache(default_ttl=60.0, max_size=500)  # 1 minute TTL
+
+    return _blockchain_cache
+
+
+def get_persistent_cache() -> PersistentCache:
+    """Get the global persistent cache instance."""
+    global _persistent_cache
+
+    if _persistent_cache is None:
+        cache_dir = Path.home() / ".htcli" / "cache"
+        _persistent_cache = PersistentCache(cache_dir, default_ttl=3600.0)  # 1 hour TTL
+
+    return _persistent_cache
+
+
+def cached(ttl: float = 300.0, cache_type: str = "memory", key_prefix: str = ""):
+    """
+    Decorator to cache function results.
+
+    Args:
+        ttl: Time-to-live in seconds
+        cache_type: Type of cache to use ("memory" or "persistent")
+        key_prefix: Prefix for cache keys
+
+    Returns:
+        Decorated function
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            # Generate cache key
+            cache_key = f"{key_prefix}{func.__name__}:{hash(str(args) + str(kwargs))}"
+
+            # Get appropriate cache
+            if cache_type == "persistent":
+                cache = get_persistent_cache()
+            else:
+                cache = get_blockchain_cache()
+
+            # Try to get from cache
+            result = cache.get(cache_key)
+            if result is not None:
+                logger.debug(f"Cache hit for {cache_key}")
+                return result
+
+            # Execute function and cache result
+            result = func(*args, **kwargs)
+            cache.set(cache_key, result, ttl)
+            logger.debug(f"Cached result for {cache_key}")
+
+            return result
+
+        return wrapper
+
+    return decorator
+
+
+def cache_blockchain_data(key: str, data: Any, ttl: float = 60.0) -> None:
+    """
+    Cache blockchain data.
+
+    Args:
+        key: Cache key
+        data: Data to cache
+        ttl: Time-to-live in seconds
+    """
+    cache = get_blockchain_cache()
+    cache.set(key, data, ttl)
+
+
+def get_cached_blockchain_data(key: str) -> Optional[Any]:
+    """
+    Get cached blockchain data.
+
+    Args:
+        key: Cache key
+
+    Returns:
+        Cached data or None if not found/expired
+    """
+    cache = get_blockchain_cache()
+    return cache.get(key)
+
+
+def cache_persistent_data(key: str, data: Any, ttl: float = 3600.0) -> None:
+    """
+    Cache persistent data.
+
+    Args:
+        key: Cache key
+        data: Data to cache
+        ttl: Time-to-live in seconds
+    """
+    cache = get_persistent_cache()
+    cache.set(key, data, ttl)
+
+
+def get_cached_persistent_data(key: str) -> Optional[Any]:
+    """
+    Get cached persistent data.
+
+    Args:
+        key: Cache key
+
+    Returns:
+        Cached data or None if not found/expired
+    """
+    cache = get_persistent_cache()
+    return cache.get(key)
+
+
+def clear_all_caches() -> None:
+    """Clear all caches."""
+    global _blockchain_cache, _persistent_cache
+
+    if _blockchain_cache:
+        _blockchain_cache.clear()
+
+    if _persistent_cache:
+        _persistent_cache.clear()
+
+    logger.info("All caches cleared")
+
+
+def get_cache_stats() -> dict[str, Any]:
+    """Get cache statistics."""
+    stats = {}
+
+    if _blockchain_cache:
+        stats["blockchain_cache"] = _blockchain_cache.stats()
+
+    if _persistent_cache:
+        stats["persistent_cache"] = _persistent_cache.stats()
+
+    return stats
+
+
+# Async utility functions
+async def cache_blockchain_data_async(key: str, data: Any, ttl: float = 60.0) -> None:
+    """
+    Async version of cache_blockchain_data.
+
+    Args:
+        key: Cache key
+        data: Data to cache
+        ttl: Time-to-live in seconds
+    """
+    cache = get_blockchain_cache()
+    await cache.set_async(key, data, ttl)
+
+
+async def get_cached_blockchain_data_async(key: str) -> Optional[Any]:
+    """
+    Async version of get_cached_blockchain_data.
+
+    Args:
+        key: Cache key
+
+    Returns:
+        Cached data or None if not found/expired
+    """
+    cache = get_blockchain_cache()
+    return await cache.get_async(key)
+
+
+async def cache_persistent_data_async(key: str, data: Any, ttl: float = 3600.0) -> None:
+    """
+    Async version of cache_persistent_data.
+
+    Args:
+        key: Cache key
+        data: Data to cache
+        ttl: Time-to-live in seconds
+    """
+    cache = get_persistent_cache()
+    await cache.set_async(key, data, ttl)
+
+
+async def get_cached_persistent_data_async(key: str) -> Optional[Any]:
+    """
+    Async version of get_cached_persistent_data.
+
+    Args:
+        key: Cache key
+
+    Returns:
+        Cached data or None if not found/expired
+    """
+    cache = get_persistent_cache()
+    return await cache.get_async(key)
+
+
+def async_cached(ttl: float = 300.0, cache_type: str = "memory", key_prefix: str = ""):
+    """
+    Async decorator to cache async function results.
+
+    Args:
+        ttl: Time-to-live in seconds
+        cache_type: Type of cache to use ("memory" or "persistent")
+        key_prefix: Prefix for cache keys
+
+    Returns:
+        Decorated async function
+    """
+
+    def decorator(func: Callable[..., Awaitable[Any]]) -> Callable[..., Awaitable[Any]]:
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            # Generate cache key
+            cache_key = f"{key_prefix}{func.__name__}:{hash(str(args) + str(kwargs))}"
+
+            # Get appropriate cache
+            if cache_type == "persistent":
+                cache = get_persistent_cache()
+            else:
+                cache = get_blockchain_cache()
+
+            # Try to get from cache
+            result = await cache.get_async(cache_key)
+            if result is not None:
+                logger.debug(f"Async cache hit for {cache_key}")
+                return result
+
+            # Execute function and cache result
+            result = await func(*args, **kwargs)
+            await cache.set_async(cache_key, result, ttl)
+            logger.debug(f"Async cached result for {cache_key}")
+
+            return result
+
+        return wrapper
+
+    return decorator

src/htcli/utils/constants.py

@@ -0,0 +1,38 @@
+"""
+Centralized runtime constants
+
+These values originate from `hypertensor-evm/pallets/network/src/lib.rs`.
+Keeping them in one place makes it straightforward to update the CLI whenever
+the chain defaults change.
+"""
+
+from decimal import Decimal
+
+# Percentages in the runtime are expressed as 1e18 = 100%.
+PERCENTAGE_FACTOR: Decimal = Decimal("1e18")
+
+# --- Subnet activation requirements ---------------------------------------------------------
+
+# Minimum number of active/electable nodes a subnet must maintain.
+MIN_SUBNET_NODES: int = 3
+
+# Maximum penalty count before a subnet is considered unhealthy.
+MAX_SUBNET_PENALTY_COUNT: int = 16
+
+# Minimum delegate stake factor (0.1% of total issuance, scaled by node multiplier).
+MIN_SUBNET_DELEGATE_STAKE_FACTOR_RAW: int = 1_000_000_000_000_000
+MIN_SUBNET_DELEGATE_STAKE_FACTOR_PERCENT: Decimal = (
+    Decimal(MIN_SUBNET_DELEGATE_STAKE_FACTOR_RAW) / PERCENTAGE_FACTOR * Decimal(100)
+)
+
+
+def format_percentage(value: Decimal, precision: int = 3) -> str:
+    """
+    Format a decimal percentage (e.g., Decimal('0.1')) into a human readable string.
+    """
+
+    formatted = f"{value:.{precision}f}"
+    if "." in formatted:
+        formatted = formatted.rstrip("0").rstrip(".")
+    return f"{formatted}%"
+

src/htcli/utils/legacy/__init__.py

@@ -0,0 +1,12 @@
+"""
+Legacy utilities - deprecated in favor of the new UI system.
+These modules are kept for backwards compatibility during migration.
+
+Use the new UI system instead:
+- colors.py -> use ui.colors
+- formatting.py -> use ui.display
+- interactive.py -> use ui.prompts
+"""
+
+# No exports - encourage use of new UI system
+__all__ = []