tellaro-query-language 0.2.2__py3-none-any.whl → 0.2.5__py3-none-any.whl

{tellaro_query_language-0.2.2.dist-info → tellaro_query_language-0.2.5.dist-info}/RECORD

@@ -1,30 +1,32 @@
-tql/__init__.py,sha256=mRrrtun-1Xx9k8g0aaiqxYhhNAwWEyRC4zrVMO49Kkg,1260
+tql/__init__.py,sha256=eqti5Fmu8EjD-NbCwqb1UKGJQ0OpWJLREsVMqqn6Hs4,1260
 tql/analyzer.py,sha256=Sfzj6f7YzqylT8HIL9hDbXdhl0lf8q8DNoafrxkD-F8,15456
 tql/cache/__init__.py,sha256=GIzIEMZUZEYJj72sAhuVLEG-OJEKUG2srUWNM3Ix-T8,213
-tql/cache/base.py,sha256=0b-8uyh3JltayGmXQI45snTqsM5sQu9u0KcNvZIRa-I,687
-tql/cache/memory.py,sha256=ibcmQSAxNvqCy6DksbU7gLu6UArYp1u3fW-oLubxtV0,2056
+tql/cache/base.py,sha256=CwLpobv4WR7WSz99JVWAHNn-XQTtqr38Yg5UiWNXPiA,3192
+tql/cache/memory.py,sha256=4nKFvq8SQSzht4JjVgml4MiEFk5pJmTCH6tHO8vwnrI,5978
 tql/cache/redis.py,sha256=ZU_IsVDvpSYpNvPfnZ4iulJDODpEGx3c4dkXLzPzPVc,2309
-tql/core.py,sha256=bMPrcuutY-1yvC-4M7w2y1JxNitMyBSpxPfg8ohjO60,48406
+tql/cli.py,sha256=dxvYvq0TmLWS5vHAkhdgTUlJK42vORjH8ttNkjIcgqM,15257
+tql/core.py,sha256=_OlFGTrvJ8cBz3OliRxSz-IbD6e1t_nYC5YZFVkOAfc,58413
 tql/core_components/README.md,sha256=Rm7w4UHdQ0vPBEFybE5b62IOvSA5Nzq2GRvtBHOapmc,3068
 tql/core_components/__init__.py,sha256=v8BBybPlqV7dkVY9mw1mblvqyAFJZ7Pf_bEc-jAL7FI,643
 tql/core_components/file_operations.py,sha256=Jr0kkxz_OP2KHOAsIr7KMtYe_lbu8LuBUySt2LQbjJw,3925
-tql/core_components/opensearch_operations.py,sha256=KvmK1FnkGZFBjBysH_sDjzIRnyUcNn7wzLzuRr1rBlg,54264
+tql/core_components/opensearch_operations.py,sha256=zgxGiDpXyPW0ZUX-StpZXxf84s8eLxSymAGM5UUJimk,55253
 tql/core_components/stats_operations.py,sha256=aqTGAqIFvR6EkSbJEd0qft8Ldy8uiTrK2XI9o5bZUOs,8014
 tql/core_components/validation_operations.py,sha256=_VPXh0HABBjsXF99jFT7B6-5QAPsADOCy6poinGrxeE,22454
-tql/evaluator.py,sha256=_JYr-wK3F1wvBoNGIBiAEaP6Ot1g2qxZ4lOjPdOqvDk,17698
+tql/evaluator.py,sha256=6BtC0njH_aR_lXiU6GU5vM5MRhQeSoxL7F95xh-2-ho,17903
 tql/evaluator_components/README.md,sha256=c59yf2au34yPhrru7JWgGop_ORteB6w5vfMhsac8j3k,3882
 tql/evaluator_components/__init__.py,sha256=DourRUSYXWPnCghBFj7W0YfMeymT3X8YTDCwnLIyP1c,535
 tql/evaluator_components/field_access.py,sha256=BuXvL9jlv4H77neT70Vh7_qokmzs-d4EbSDA2FB1IT0,6435
-tql/evaluator_components/special_expressions.py,sha256=K6M5pW4Re2kEqxfxj9sc7I_M1tU3pn6LKJ2AfjHeciA,12917
-tql/evaluator_components/value_comparison.py,sha256=pL7-hxdNbzJ53DrTSiDdd7KYbVLChuNwFRLjG7P_1KM,17939
-tql/exceptions.py,sha256=hatIixXci6p57J9RrkfdvmKM_2i-JKb8ViL2kU4z7a8,5550
+tql/evaluator_components/special_expressions.py,sha256=prhXnVRnFfmecgmuTz0fsefTA1clb2eyyYf-zPtzXGs,15703
+tql/evaluator_components/value_comparison.py,sha256=a0Vo3BWyPxMtEgAKtUuaN0HN9Arc0A7BUVrxgZyH6_o,21200
+tql/exceptions.py,sha256=GVssdBp9134Wyk1bWbcLQFU9U8yQKl5zzquTTrM22A0,5620
+tql/field_type_inference.py,sha256=KOazjp8CK6s9vwOcFkQrdOwcazOwHqSIhYgX8hWCiDo,9700
 tql/geoip_normalizer.py,sha256=tvie-5xevJEeLp2KmjoXDjYdND8AvyVE7lCO8qgUzGY,10486
-tql/mutator_analyzer.py,sha256=OzI7t3C4H0IJOonpywE5LWz2cm5Dco5xnp2RTQOiSWg,55638
+tql/mutator_analyzer.py,sha256=OWx3k5lK5aFHWU9Ez6DaIhenEZDxj9CbB0vM71xqUTw,55670
 tql/mutators/__init__.py,sha256=eTK8sRw4KXXnTZTn5ETIqwcaIek5rSUIVyZsxTwNNHA,6966
 tql/mutators/base.py,sha256=4Ze_x1sTO11OILXfcF2XN7ttyHcZ4gwn96UXFMMaC6M,2523
 tql/mutators/dns.py,sha256=1IKgHolFLRMR4TOgK0AiLjz5vDtFiqO328mVF4Vzk3s,14428
 tql/mutators/encoding.py,sha256=yt12BJrHAIJfBesP8VOSfVlvJqB1yOmEeT_8QDPvNN8,7985
-tql/mutators/geo.py,sha256=fFQSg_Li3KjFKS3TI26yDzrDpWsmC3MfmgcsxYoQMgM,14507
+tql/mutators/geo.py,sha256=H-_5oDvuYaAG8Re17RkGjzCc6Z07YHd7Cr95g6JbnyE,16188
 tql/mutators/list.py,sha256=949ZrKKhL4INkH2Od8bq7Ey80kFX_23PEfRKueG82cU,7084
 tql/mutators/network.py,sha256=1lZpmKt1GoTfNxiXUmSXkTwJIzPQZnQEgU7ojpBSm3A,5458
 tql/mutators/security.py,sha256=XyWuPxgpCi-igHKmkbP0_0V-evOc3FG2a1igY8rQRX4,9256
@@ -34,23 +36,24 @@ tql/opensearch_components/README.md,sha256=gt-qLmmach8Kh7-QwLZmoAxxIL79XIG1EDqJu
 tql/opensearch_components/__init__.py,sha256=_zIZY8Fns7mkEcY6w2p9FNRBXtEmmPFFJEcFRfrVyXA,514
 tql/opensearch_components/field_mapping.py,sha256=fj388cKVyDXLJKi8giSiGHL9zg4cFRzy0VJ6nIsppSo,18102
 tql/opensearch_components/lucene_converter.py,sha256=OvYTZHNBktPGow1fsVm4TMlvxHSmWrnqo42lFZNxXTo,13175
-tql/opensearch_components/query_converter.py,sha256=vLoBqv7W3ntqUH6hcuT4PDJkGkAGSQCxMvAWC482c0g,41971
+tql/opensearch_components/query_converter.py,sha256=INjX6hd-1dlCdCn_dGSBnub2mpNyUBpHXhHA5WoBQX4,41985
 tql/opensearch_mappings.py,sha256=sVLlQlE3eGD7iNNZ_m4F4j5GVzQAJhZyCqDKYRhLRh8,11531
-tql/opensearch_stats.py,sha256=aMV__jtlfogGBnFucsNPazORro2mYTz_C_w9uxOqsMI,24384
-tql/parser.py,sha256=9kewX4IbBL3W5hbq9Xhi4BGrQ4QaoWqz9AJV0Yuf9YA,78665
+tql/opensearch_stats.py,sha256=sxJ4KziV-Yv1kvjo22souxjBQH3chmlm4lAgEhRBtyA,24530
+tql/parser.py,sha256=y4LKYuNqE74Xx5UpHZBZE6PlVaRBiwr5i49NeMJW-jU,80383
 tql/parser_components/README.md,sha256=lvQX72ckq2zyotGs8QIHHCIFqaA7bOHwkP44wU8Zoiw,2322
 tql/parser_components/__init__.py,sha256=zBwHBMPJyHSBbaOojf6qTrJYjJg5A6tPUE8nHFdRiQs,521
 tql/parser_components/ast_builder.py,sha256=erHoeKAMzobswoRIXB9xcsZbzQ5-2ZwaYfQgRWoUAa8,9653
 tql/parser_components/error_analyzer.py,sha256=qlCD9vKyW73aeKQYI33P1OjIWSJ3LPd08wuN9cis2fU,4012
 tql/parser_components/field_extractor.py,sha256=eUEkmiYWX2OexanFqhHeX8hcIkRlfIcgMB667e0HRYs,4629
 tql/parser_components/grammar.py,sha256=h58RBshZHXgbP1EmNwmf7dny-fgVloNg-qN4Rivross,20599
-tql/post_processor.py,sha256=MZOJzuWTL2qdvu-AUNMryYF2D-piv8rYH5vCcrLt5-A,50069
-tql/scripts.py,sha256=VOr5vCjIvKlW36kwvJx7JGFIRM16IJZlbJcWlBexBtk,3728
-tql/stats_evaluator.py,sha256=OQZuNLwLHAtWrwAh3utdtr1fQt3tftCs6L-1G1NQCGQ,22318
+tql/post_processor.py,sha256=5w_rP0V-t3AC7iAFLnlDxUtawcDFovbhbRsoZxt9yP4,51787
+tql/scripts.py,sha256=DUY0H5IoGs_CNdG_oxITvLiCNVsogb2RJqUs2xXOs24,4319
+tql/stats_evaluator.py,sha256=2qnjeH5Qx14qpHDS_YJn9jRPeoPUfkeiYJabBagdfRs,36126
 tql/stats_transformer.py,sha256=MT-4rDWZSySgn4Fuq9H0c-mvwFYLM6FqWpPv2rHX-rE,7588
+tql/streaming_file_processor.py,sha256=cftWhYcvUo984P3ALf2CO3FoCQPJPe_2s2HLcXTp5UQ,12437
 tql/validators.py,sha256=e9MlX-zQ_O3M8YP8vXyMjKU8iiJMTh6mMK0iv0_4gTY,3771
-tellaro_query_language-0.2.2.dist-info/LICENSE,sha256=zRhQ85LnW55fWgAjQctckwQ67DX5Jmt64lq343ThZFU,1063
-tellaro_query_language-0.2.2.dist-info/METADATA,sha256=QsCXKY_0aHeMorc4PepJ84ViZbTK53suxILmr868Lkk,15740
-tellaro_query_language-0.2.2.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-tellaro_query_language-0.2.2.dist-info/entry_points.txt,sha256=H43APfGBMsZkKsUCnFTaqprQPW-Kce2yz2qsBL3dZrw,164
-tellaro_query_language-0.2.2.dist-info/RECORD,,
+tellaro_query_language-0.2.5.dist-info/LICENSE,sha256=eWf8lkuXlVX_8WiDpUgQvzxc1cxCeVne_e6P-pVJpwM,3038
+tellaro_query_language-0.2.5.dist-info/METADATA,sha256=HCTN5lDkKfutCPvcLYTQztHwW1G4qbo2LP8cYFRayZM,21857
+tellaro_query_language-0.2.5.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+tellaro_query_language-0.2.5.dist-info/entry_points.txt,sha256=D0lbIGUYuDyfcYeqju1rWcMBFzft4sZtfIlw5uPNx5g,181
+tellaro_query_language-0.2.5.dist-info/RECORD,,

{tellaro_query_language-0.2.2.dist-info → tellaro_query_language-0.2.5.dist-info}/entry_points.txt

@@ -4,4 +4,5 @@ cov=tql.scripts:run_coverage
 lint=tql.scripts:run_lint
 lint-all=tql.scripts:run_lint_all
 tests=tql.scripts:run_tests
+tql=tql.cli:main
 

tql/__init__.py

@@ -28,7 +28,7 @@ from .opensearch_mappings import (
     get_sample_data_from_index,
 )
 
-__version__ = "0.1.0"
+__version__ = "0.2.2"
 __all__ = [
     "TQL",
     "TQLParseError",

tql/cache/base.py

@@ -1,25 +1,97 @@
-"""Base cache infrastructure."""
+"""Base cache infrastructure for TQL.
+
+This module provides the base CacheManager class that defines the caching
+interface used throughout TQL. Concrete implementations include LocalCacheManager
+for in-memory caching and RedisCacheManager for distributed caching.
+"""
 
 from typing import Any, Dict, Optional
 
 
 class CacheManager:
-    """Base class for cache management."""
+    """Base class for cache management.
+
+    This class defines the interface for all cache implementations in TQL.
+    Subclasses should override these methods to provide actual caching functionality.
+
+    The base implementation provides no-op defaults that can be safely used when
+    caching is disabled or not needed.
+
+    Example:
+        >>> cache = LocalCacheManager()
+        >>> cache.set("user:123", {"name": "Alice", "age": 30}, ttl=3600)
+        >>> user = cache.get("user:123")
+        >>> cache.delete("user:123")
+    """
 
     def get(self, key: str) -> Optional[Any]:
-        """Retrieve value from cache."""
+        """Retrieve a value from the cache.
+
+        Args:
+            key: The cache key to look up. Should be a string identifier.
+
+        Returns:
+            The cached value if it exists and hasn't expired, None otherwise.
+
+        Example:
+            >>> value = cache.get("my_key")
+            >>> if value is not None:
+            ...     print(f"Found: {value}")
+        """
         return None
 
     def set(self, key: str, value: Any, ttl: Optional[int] = None) -> None:
-        """Store value in cache."""
+        """Store a value in the cache.
+
+        Args:
+            key: The cache key under which to store the value.
+            value: The value to cache. Can be any Python object.
+            ttl: Time-to-live in seconds. If None or 0, the value never expires.
+
+        Example:
+            >>> cache.set("config", {"debug": True}, ttl=300)  # Cache for 5 minutes
+            >>> cache.set("permanent", {"version": "1.0"})  # Never expires
+        """
 
     def delete(self, key: str) -> None:
-        """Remove value from cache."""
+        """Remove a value from the cache.
+
+        Args:
+            key: The cache key to delete.
+
+        Example:
+            >>> cache.delete("expired_key")
+        """
 
     def clear_pattern(self, pattern: str) -> int:  # pylint: disable=unused-argument
-        """Clear all keys matching pattern."""
+        """Clear all keys matching a pattern.
+
+        Args:
+            pattern: A pattern string to match keys. Format depends on implementation.
+                    For Redis: supports wildcards like "user:*" or "session:?123"
+                    For Local: basic string matching
+
+        Returns:
+            The number of keys that were deleted.
+
+        Example:
+            >>> count = cache.clear_pattern("temp:*")
+            >>> print(f"Cleared {count} temporary keys")
+        """
         return 0
 
     def get_stats(self) -> Dict[str, Any]:
-        """Get cache statistics."""
+        """Get cache statistics and metrics.
+
+        Returns:
+            Dictionary containing cache statistics such as:
+            - hit_rate: Cache hit rate percentage
+            - miss_rate: Cache miss rate percentage
+            - size: Number of items in cache
+            - memory_usage: Memory used by cache (if available)
+
+        Example:
+            >>> stats = cache.get_stats()
+            >>> print(f"Hit rate: {stats.get('hit_rate', 0)}%")
+        """
         return {}

tql/cache/memory.py

@@ -1,63 +1,171 @@
-"""In-memory cache implementation."""
+"""In-memory cache implementation for TQL.
+
+This module provides a simple in-memory cache with TTL (time-to-live) support
+and basic LRU (Least Recently Used) eviction when the cache reaches its size limit.
+"""
 
 import time
-from typing import Any, Dict, Optional, Tuple
+from typing import Any, Dict, Optional
 
 from .base import CacheManager
 
 
 class LocalCacheManager(CacheManager):
-    """Local in-memory cache using LRU."""
+    """Local in-memory cache with TTL and LRU eviction.
+
+    This implementation provides thread-safe in-memory caching suitable for
+    single-process applications. For distributed caching across multiple
+    processes or servers, use RedisCacheManager instead.
+
+    Features:
+        - TTL-based expiration
+        - LRU eviction when cache is full
+        - Hit/miss statistics tracking
+        - Pattern-based key clearing
+
+    Args:
+        max_size: Maximum number of items to store (default: 10000)
+        default_ttl: Default time-to-live in seconds (default: 3600 = 1 hour)
+
+    Example:
+        >>> cache = LocalCacheManager(max_size=1000, default_ttl=600)
+        >>> cache.set("user:123", {"name": "Alice"}, ttl=300)
+        >>> user = cache.get("user:123")
+        >>> stats = cache.get_stats()
+        >>> print(f"Hit rate: {stats['hit_rate']:.2%}")
+
+    Attributes:
+        max_size: Maximum cache size
+        default_ttl: Default TTL for cached items
+    """
 
     def __init__(self, max_size: int = 10000, default_ttl: int = 3600):
+        """Initialize the local cache.
+
+        Args:
+            max_size: Maximum number of items to cache before eviction starts.
+            default_ttl: Default expiration time in seconds for cached items.
+        """
         self.max_size = max_size
         self.default_ttl = default_ttl
-        self._cache: Dict[str, Tuple[Any, float]] = {}
+        self._cache: Dict[str, Any] = {}
+        self._expiry: Dict[str, float] = {}
         self._hits = 0
         self._misses = 0
 
     def get(self, key: str) -> Optional[Any]:
-        """Retrieve value from cache if not expired."""
+        """Retrieve value from cache if not expired.
+
+        Args:
+            key: The cache key to retrieve.
+
+        Returns:
+            The cached value if present and not expired, None otherwise.
+
+        Note:
+            This method automatically removes expired keys when accessed.
+            Hit/miss statistics are updated on each call.
+        """
         if key in self._cache:
-            value, expiry = self._cache[key]
-            if expiry > time.time():
+            expiry = self._expiry.get(key, float("inf"))
+            if expiry == 0 or expiry > time.time():
                 self._hits += 1
-                return value
+                return self._cache[key]
             else:
-                # Expired
+                # Expired - clean up
                 del self._cache[key]
+                del self._expiry[key]
         self._misses += 1
         return None
 
     def set(self, key: str, value: Any, ttl: Optional[int] = None) -> None:
-        """Store value in cache with TTL."""
-        if len(self._cache) >= self.max_size:
-            # Simple eviction: remove oldest
+        """Store value in cache with optional TTL.
+
+        Args:
+            key: The cache key under which to store the value.
+            value: The value to cache (any Python object).
+            ttl: Time-to-live in seconds. If None, uses default_ttl.
+                 If 0, the item never expires.
+
+        Note:
+            When the cache is full (reaches max_size), the oldest item
+            is evicted to make room for the new one (LRU eviction).
+        """
+        if len(self._cache) >= self.max_size and key not in self._cache:
+            # Simple eviction: remove oldest (first in dict)
             oldest_key = next(iter(self._cache))
             del self._cache[oldest_key]
+            self._expiry.pop(oldest_key, None)
 
-        expiry = time.time() + (ttl or self.default_ttl)
-        self._cache[key] = (value, expiry)
+        self._cache[key] = value
+        if ttl == 0:
+            # Never expires
+            self._expiry[key] = 0
+        else:
+            expiry_time = time.time() + (ttl if ttl is not None else self.default_ttl)
+            self._expiry[key] = expiry_time
 
     def delete(self, key: str) -> None:
-        """Remove value from cache."""
+        """Remove value from cache.
+
+        Args:
+            key: The cache key to delete.
+
+        Note:
+            If the key doesn't exist, this method does nothing (no error raised).
+        """
         self._cache.pop(key, None)
+        self._expiry.pop(key, None)
 
     def clear_pattern(self, pattern: str) -> int:
-        """Clear all keys matching pattern."""
+        """Clear all keys matching a glob pattern.
+
+        Args:
+            pattern: A glob pattern to match keys. Supports wildcards:
+                    - '*' matches any sequence of characters
+                    - '?' matches any single character
+                    - '[seq]' matches any character in seq
+                    - '[!seq]' matches any character not in seq
+
+        Returns:
+            The number of keys that were deleted.
+
+        Example:
+            >>> cache.set("user:123", data1)
+            >>> cache.set("user:456", data2)
+            >>> cache.set("session:789", data3)
+            >>> count = cache.clear_pattern("user:*")  # Deletes user:123 and user:456
+            >>> print(count)  # 2
+        """
         import fnmatch
 
         keys_to_delete = [k for k in self._cache.keys() if fnmatch.fnmatch(k, pattern)]
         for key in keys_to_delete:
             del self._cache[key]
+            self._expiry.pop(key, None)
         return len(keys_to_delete)
 
     def get_stats(self) -> Dict[str, Any]:
-        """Get cache statistics."""
+        """Get cache performance statistics.
+
+        Returns:
+            Dictionary containing:
+            - hits: Number of successful cache retrievals
+            - misses: Number of cache misses
+            - hit_rate: Ratio of hits to total requests (0.0 to 1.0)
+            - size: Current number of items in cache
+            - max_size: Maximum cache capacity
+
+        Example:
+            >>> stats = cache.get_stats()
+            >>> print(f"Cache is {stats['hit_rate']:.2%} effective")
+            >>> print(f"Using {stats['size']}/{stats['max_size']} slots")
+        """
+        total_requests = self._hits + self._misses
         return {
             "hits": self._hits,
             "misses": self._misses,
-            "hit_rate": self._hits / (self._hits + self._misses) if (self._hits + self._misses) > 0 else 0,
+            "hit_rate": self._hits / total_requests if total_requests > 0 else 0.0,
             "size": len(self._cache),
             "max_size": self.max_size,
         }