mapres 2.3.1__tar.gz → 2.4__tar.gz

{mapres-2.3.1/src/mapres.egg-info → mapres-2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mapres
-Version: 2.3.1
+Version: 2.4
 Summary: A powerfull mapping utility
 Author: iFamished
 License: MIT

{mapres-2.3.1 → mapres-2.4}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mapres"
-version = "2.3.1"
+version = "2.4"
 description = "A powerfull mapping utility"
 readme = "README.md"
 requires-python = ">=3.9"

{mapres-2.3.1 → mapres-2.4}/src/mapres/__init__.py

@@ -7,7 +7,7 @@ try:
 except PackageNotFoundError:
     __version__ = '0.0.0'
 
-from .resolver import MapResolver, res
+from .resolver import MapResolver, res, setGlobalMaps, setDefaultPasses
 from .datamap import DataMap, datamap, syntax
 from .layers import Layer, LayerStack
 
@@ -37,6 +37,8 @@ __all__ = [
     'syntax',
     'Layer',
     'LayerStack',
+    'setGlobalMaps',
+    'setDefaultPasses',
 
     # maps
     'ColorMap',

mapres-2.4/src/mapres/datamap.py

@@ -0,0 +1,90 @@
+import re
+from dataclasses import dataclass, fields, is_dataclass
+
+class syntax:
+    double_braces = r'\{\{([A-Za-z][A-Za-z0-9_]*)\}\}'     # {{value}}
+    dollars       = r'\$\{([A-Za-z][A-Za-z0-9_]*)\}'       # ${value}
+    angles        = r'<([A-Za-z][A-Za-z0-9_]*)>'           # <value>
+    percents      = r'%([A-Za-z][A-Za-z0-9_]*)%'           # %value%
+    at_tags       = r'@([A-Za-z][A-Za-z0-9_]*)@'           # @value@
+    hash_tags     = r'#([A-Za-z][A-Za-z0-9_]*)#'           # #value#
+    pipe_tags     = r'\|([A-Za-z][A-Za-z0-9_]*)\|'         # |value|
+    paren_dollar  = r'\$\(([A-Za-z][A-Za-z0-9_]*)\)'       # $(value)
+    colons        = r':([A-Za-z][A-Za-z0-9_]*):'           # :value:
+
+@dataclass
+class DataMap:
+    '''Core datamap class. Contains logic used to make datamaps'''
+    __syntax__: str = syntax.double_braces
+    __mode__: str | None = None
+
+    def as_map(self):
+        result = {}
+        for f in fields(self):
+            if not f.init or f.name in ('__syntax__', '__mode__'):
+                continue
+            val = getattr(self, f.name)
+            if self.__mode__ == 'dynamic':
+                providers = getattr(self, 'providers', None)
+                if isinstance(providers, dict) and f.name in providers:
+                    val = providers[f.name]
+                if callable(val):
+                    val = val()
+            result[f.name] = val
+        return result
+
+    @classmethod
+    def get_syntax(cls):
+        return getattr(cls, '__syntax__', syntax.double_braces)
+
+
+# main decorator factory
+def datamap(_cls=None, *, syntax=syntax.double_braces, mode=None):
+    '''@datamap decorator with optional values'''
+    def wrap(cls):
+        cls.__syntax__ = syntax
+        cls.__mode__ = mode
+        namespace = dict(cls.__dict__)
+        namespace['__dict__'] = {}
+        rules_obj = namespace.get('rules', None)
+        cls = type(cls.__name__, (DataMap,), namespace)
+        if rules_obj is not None:
+            setattr(cls, 'rules', rules_obj)
+        return dataclass(frozen=False)(cls)
+    if _cls is not None:
+        return wrap(_cls)
+    return wrap
+
+
+# syntax-bound decorator factories
+class _SyntaxFactory:
+    def __init__(self, syntax_value):
+        self._syntax = syntax_value
+
+    def __call__(self, _cls=None, **kwargs):
+        # Case 1: bare decorator: @datamap.colons
+        if _cls is not None and isinstance(_cls, type):
+            return datamap(_cls, syntax=self._syntax)
+
+        # Case 2: decorator with args: @datamap.colons(mode='config')
+        return datamap(syntax=self._syntax, **kwargs)
+
+    @property
+    def config(self):
+        # Case 3: @datamap.colons.config
+        return datamap(syntax=self._syntax, mode='config')
+
+
+# build syntax shortcuts
+datamap.double_braces = _SyntaxFactory(syntax.double_braces)
+datamap.angles        = _SyntaxFactory(syntax.angles)
+datamap.dollars       = _SyntaxFactory(syntax.dollars)
+datamap.percents      = _SyntaxFactory(syntax.percents)
+datamap.at_tags       = _SyntaxFactory(syntax.at_tags)
+datamap.hash_tags     = _SyntaxFactory(syntax.hash_tags)
+datamap.pipe_tags     = _SyntaxFactory(syntax.pipe_tags)
+datamap.paren_dollar  = _SyntaxFactory(syntax.paren_dollar)
+datamap.colons        = _SyntaxFactory(syntax.colons)
+
+# global mode shortcut
+datamap.config = datamap(mode='config')

{mapres-2.3.1 → mapres-2.4}/src/mapres/maps/time.py

@@ -1,31 +1,36 @@
-from datetime import datetime
+from datetime import datetime, timezone
 from zoneinfo import ZoneInfo
 from mapres.datamap import datamap, syntax
 
 
+def safe_zoneinfo(tz: str):
+    try:
+        return ZoneInfo(tz)
+    except Exception:
+        return timezone.utc
+
+
 @datamap(syntax=syntax.percents, mode='dynamic')
 class TimeMap:
-    # default timezone
-    _default_tz = ZoneInfo('UTC')
-
-    # dynamic fields
-    hh: str = None
-    h: str = None
-    h12: str = None
-    hh12: str = None
-    ampm: str = None
-    mm: str = None
-    m: str = None
-    ss: str = None
-    s: str = None
-    ms: str = None
-    YYYY: str = None
-    MM: str = None
-    DD: str = None
-    weekday: str = None
+    _default_tz = safe_zoneinfo("America/Chicago")
+
+    hh: str | None = None
+    h: str | None = None
+    h12: str | None = None
+    hh12: str | None = None
+    ampm: str | None = None
+    mm: str | None = None
+    m: str | None = None
+    ss: str | None = None
+    s: str | None = None
+    ms: str | None = None
+    YYYY: str | None = None
+    MM: str | None = None
+    DD: str | None = None
+    weekday: str | None = None
 
     def __init__(self, tz: str | None = None):
-        self.TZ = ZoneInfo(tz) if tz else self._default_tz
+        self.TZ = safe_zoneinfo(tz) if tz else self._default_tz
 
     @property
     def providers(self):

{mapres-2.3.1 → mapres-2.4}/src/mapres/resolver.py

@@ -5,6 +5,38 @@ from .layers import Layer, LayerStack
 from .exceptions import MapResError, MissingKeyError, MapSyntaxError
 
 
+# escape pipeline
+ESCAPES = {
+    r'\:': '__ESC_COLON__',
+    r'\<': '__ESC_LT__',
+    r'\%': '__ESC_PERCENT__',
+    r'\$': '__ESC_DOLLAR__',
+    r'\{': '__ESC_LBRACE__',
+    r'\|': '__ESC_PIPE__',
+}
+
+# Reverse mapping: placeholder -> literal char (without backslash)
+UNESCAPES = {
+    placeholder: esc[1:]   # remove leading backslash
+    for esc, placeholder in ESCAPES.items()
+}
+
+
+def escape_stage(text: str, ctx: dict, resolver) -> str:
+    """Replace escaped opening delimiters with placeholders."""
+    for esc, placeholder in ESCAPES.items():
+        text = text.replace(esc, placeholder)
+    return text
+
+
+def unescape_stage(text: str, ctx: dict, resolver) -> str:
+    """Restore escaped delimiters after resolution."""
+    for placeholder, literal in UNESCAPES.items():
+        text = text.replace(placeholder, literal)
+    return text
+
+
+# core resolver
 class MapResolver:
     '''
     Core resolution engine for mapres.
@@ -14,7 +46,7 @@ class MapResolver:
     - syntax providers
     - layered maps
     - context substitution
-    - recursive multi-pass resolution
+    - multi-pass resolution (controlled by `passes`)
     - optional caching
     '''
     def __init__(
@@ -24,14 +56,22 @@ class MapResolver:
         pipeline: list | None = None,
         cache: bool = False,
         cache_size: int = 1024,
-        max_depth: int = 5
+        passes_default: int = 5
     ):
         self.layers = layers or LayerStack()
         self.syntax = syntax or []
         self.pipeline = pipeline or []
         self.cache_enabled = cache
         self.cache = LRUCache(cache_size) if cache else None
-        self.max_depth = max_depth
+
+        # unified recursion control
+        self.passes_default = passes_default
+
+        # Insert escape stage FIRST
+        self.pipeline.insert(0, escape_stage)
+
+        # Append unescape stage LAST
+        self.pipeline.append(unescape_stage)
 
     # pipeline
     def _apply_pipeline(self, text: str, ctx: dict) -> str:
@@ -47,22 +87,26 @@ class MapResolver:
         for provider in self.syntax:
             pattern = provider.pattern
             d = provider.get_map(ctx, self)
+
             def repl(match: re.Match) -> str:
                 k = match.group(1)
                 if k not in d:
                     raise MissingKeyError(f'Missing key "{k}" in syntax provider {provider}')
                 return str(d[k])
+
             try:
                 text = re.sub(pattern, repl, text)
             except re.error as exc:
                 raise MapSyntaxError(
                     f'Regex error in syntax provider {provider}: {exc}'
                 ) from exc
+
         return text
 
     # layered maps
     def _apply_maps(self, text: str, ctx: dict, layerstack: LayerStack):
         syntax_patterns = []
+
         for m in layerstack:
             if isinstance(m, type) and hasattr(m, 'as_map'):
                 m = m()
@@ -72,10 +116,13 @@ class MapResolver:
                 pattern = ctx.get('syntax')
                 if pattern:
                     syntax_patterns.append(pattern)
+
         syntax_patterns = list(dict.fromkeys(syntax_patterns))
+
         for pattern in syntax_patterns:
             def repl(match: re.Match):
                 k = match.group(1)
+
                 for m in layerstack:
                     layer = m
                     if isinstance(layer, type) and hasattr(layer, 'as_map'):
@@ -86,6 +133,7 @@ class MapResolver:
                         d = layer
                     else:
                         continue
+
                     if k in d:
                         return str(d[k])
 
@@ -98,19 +146,23 @@ class MapResolver:
                 text = re.sub(pattern, repl, text)
             except re.error as exc:
                 raise MapSyntaxError(f'Regex error in syntax pattern {pattern}: {exc}') from exc
+
         return text
 
     # context
     def _apply_ctx(self, text: str, ctx: dict) -> str:
         if not ctx:
             return text
-        pattern = syntax.braces
+
+        pattern = syntax.double_braces
         d = ctx
+
         def repl(match: re.Match) -> str:
             k = match.group(1)
             if k not in d:
                 raise MissingKeyError(f'Missing ctx key "{k}"')
             return str(d[k])
+
         try:
             return re.sub(pattern, repl, text)
         except re.error as exc:
@@ -124,21 +176,12 @@ class MapResolver:
         text = self._apply_ctx(text, ctx)
         return text
 
-    # recursion
-    def _recursive(self, text: str, ctx: dict, layerstack: LayerStack) -> str:
-        current = text
-        for _ in range(self.max_depth):
-            result = self._resolve_once(current, ctx, layerstack)
-            if result == current:
-                return result
-            current = result
-        return current
-
     # public api
     def res(
         self,
         text: str,
         *,
+        passes: int | None = None,
         extra_maps: dict | None = None,
         override_maps: dict | None = None,
         **ctx
@@ -147,22 +190,38 @@ class MapResolver:
         Resolve a string using maps, syntax providers, pipeline, and context.
         '''
         try:
+            depth = passes if passes is not None else self.passes_default
+
+            if depth <= 0:
+                raise MapResError("passes must be >= 1")
+
+            # override maps
             if override_maps is not None:
                 temp = LayerStack([Layer('override', override_maps, priority=0)])
-                return self._recursive(text, ctx, temp)
+                return self._resolve_once(text, ctx, temp)
 
+            # extra maps
             if extra_maps:
                 temp = self.layers.clone()
                 temp.add_layer(Layer('extra', extra_maps, priority=999))
-                return self._recursive(text, ctx, temp)
+                return self._resolve_once(text, ctx, temp)
 
+            # caching
             if self.cache_enabled:
                 key = (text, tuple(sorted(ctx.items())))
                 cached = self.cache.get(key)
                 if cached is not None:
                     return cached
 
-            result = self._recursive(text, ctx, self.layers)
+            # multi-pass resolution
+            current = text
+            for _ in range(depth):
+                new = self._resolve_once(current, ctx, self.layers)
+                if new == current:
+                    break
+                current = new
+
+            result = current
 
             if self.cache_enabled:
                 self.cache.set(key, result)
@@ -175,11 +234,31 @@ class MapResolver:
             raise MapResError(f'Unhandled resolver error: {exc}') from exc
 
 
-# global resolver
-_DEFAULT = MapResolver()
+# ----------------------------------
+# ---------- SIMPLE USAGE ----------
+# ----------------------------------
+
+_DEFAULT_RESOLVER = MapResolver()
+
+def setGlobalMaps(maps, *, name=None, priority=0):
+    '''
+    Register a global map or datamap class into the default resolver.
+
+    maps: datamap class OR dict
+    name: optional layer name (default = class name or 'global')
+    priority: layer priority (lower = earlier)
+    '''
+    layer_name = name or getattr(maps, "__name__", "global")
+    layer = Layer(layer_name, maps=[maps], priority=priority)
+    _DEFAULT_RESOLVER.layers.add_layer(layer)
+
+def setDefaultPasses(passes: int):
+    if passes < 1:
+        raise MapResError("Passes cannot be less than 1")
+    _DEFAULT_RESOLVER.passes_default = passes
 
-def res(text: str, **ctx) -> str:
+def res(text: str, passes=None, **ctx) -> str:
     '''
-    Resolve using the global default resolver.
+    Simple resolution using the global default resolver.
     '''
-    return _DEFAULT.res(text, **ctx)
+    return _DEFAULT_RESOLVER.res(text, passes=passes, **ctx)

{mapres-2.3.1 → mapres-2.4/src/mapres.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mapres
-Version: 2.3.1
+Version: 2.4
 Summary: A powerfull mapping utility
 Author: iFamished
 License: MIT

mapres-2.3.1/src/mapres/datamap.py

@@ -1,64 +0,0 @@
-import re
-from dataclasses import dataclass, fields, is_dataclass
-
-class syntax:
-    braces   = r'\{([^{}]+)\}'
-    dollars  = r'\$\{([^{}]+)\}'
-    angles   = r'<([^<>]+)>'
-    percents = r'%([^%]+)%'
-
-
-@dataclass
-class DataMap:
-    '''Core datamap class. Contains logic used to make datamaps'''
-    __syntax__: str = syntax.braces
-    __mode__: str | None = None
-
-    def as_map(self):
-        result = {}
-        for f in fields(self):
-            if not f.init or f.name in ('__syntax__', '__mode__'):
-                continue
-            val = getattr(self, f.name)
-            if self.__mode__ == 'dynamic':
-                providers = getattr(self, 'providers', None)
-                if isinstance(providers, dict) and f.name in providers:
-                    val = providers[f.name]
-                if callable(val):
-                    val = val()
-            result[f.name] = val
-        return result
-
-    @classmethod
-    def get_syntax(cls):
-        return getattr(cls, '__syntax__', syntax.braces)
-
-
-# decorator
-def datamap(
-    _cls = None,
-    *,
-    syntax: str = syntax.braces,
-    mode: bool | None = None,
-):
-    '''@datamap decorator with optional values'''
-    def wrap(cls):
-        cls.__syntax__ = syntax
-        cls.__mode__ = mode
-        namespace = dict(cls.__dict__)
-        namespace['__dict__'] = {}
-        # preserve any rules class defined in the original namespace by attaching it to the generated class
-        rules_obj = namespace.get('rules', None)
-        cls = type(cls.__name__, (DataMap,), namespace)
-        # attach rules (if present) to the new class so validators can read them via the datamap class
-        if rules_obj is not None:
-            setattr(cls, 'rules', rules_obj)
-        return dataclass(frozen=False)(cls)
-    return wrap if _cls is None else wrap(_cls)
-
-
-# decorator shortcuts
-datamap.braces = datamap(syntax=syntax.braces)
-datamap.angles = datamap(syntax=syntax.angles)
-datamap.dollars = datamap(syntax=syntax.dollars)
-datamap.percents = datamap(syntax=syntax.percents)