mapres 2.3__tar.gz → 2.4__tar.gz

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

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

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

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

{mapres-2.3 → 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.4/src/mapres/maps/color.py

@@ -0,0 +1,75 @@
+from mapres.datamap import datamap, syntax
+
+@datamap(syntax=syntax.angles) # produces <>
+class ColorMap:
+    black: str = '\033[30m'
+    dark_blue: str = '\033[34m'
+    dark_green: str = '\033[32m'
+    dark_aqua: str = '\033[36m'
+    dark_red: str = '\033[31m'
+    dark_purple: str = '\033[35m'
+    gold: str = '\033[33m'
+    gray: str = '\033[37m'
+    dark_gray: str = '\033[90m'
+    blue: str = '\033[94m'
+    green: str = '\033[92m'
+    aqua: str = '\033[96m'
+    red: str = '\033[91m'
+    light_purple: str = '\033[95m'
+    yellow: str = '\033[93m'
+    white: str = '\033[97m'
+    reset: str = '\033[0m'
+    bold: str = '\033[1m'
+    italic: str = '\033[3m'
+
+    def as_dict(self):
+        return {f'<{k}>': getattr(self, k) for k in self.__dataclass_fields__}
+
+# ASCII color map
+ascii_colors = ColorMap()
+
+# Minecraft color map
+mc_colors = ColorMap(
+    black='§0',
+    dark_blue='§1',
+    dark_green='§2',
+    dark_aqua='§3',
+    dark_red='§4',
+    dark_purple='§5',
+    gold='§6',
+    gray='§7',
+    dark_gray='§8',
+    blue='§9',
+    green='§a',
+    aqua='§b',
+    red='§c',
+    light_purple='§d',
+    yellow='§e',
+    white='§f',
+    reset='§r',
+    bold='§l',
+    italic='§o'
+)
+
+# Color strip map
+strip_colors = ColorMap(
+    black='',
+    dark_blue='',
+    dark_green='',
+    dark_aqua='',
+    dark_red='',
+    dark_purple='',
+    gold='',
+    gray='',
+    dark_gray='',
+    blue='',
+    green='',
+    aqua='',
+    red='',
+    light_purple='',
+    yellow='',
+    white='',
+    reset='',
+    bold='',
+    italic=''
+)

{mapres-2.3 → 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 → mapres-2.4}/src/mapres/resolver.py

@@ -5,8 +5,40 @@ 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.
 
     Handles:
@@ -14,9 +46,9 @@ class MapResolver:
     - syntax providers
     - layered maps
     - context substitution
-    - recursive multi-pass resolution
+    - multi-pass resolution (controlled by `passes`)
     - optional caching
-    """
+    '''
     def __init__(
         self,
         layers: list | None = None,
@@ -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:
@@ -40,81 +80,93 @@ class MapResolver:
                 text = stage(text, ctx, self)
             return text
         except Exception as exc:
-            raise MapResError(f"Pipeline stage failed: {exc}") from exc
+            raise MapResError(f'Pipeline stage failed: {exc}') from exc
 
     # syntax providers
     def _apply_syntax(self, text: str, ctx: dict) -> str:
         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}")
+                    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}"
+                    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"):
+            if isinstance(m, type) and hasattr(m, 'as_map'):
                 m = m()
-            if hasattr(m, "as_map"):
+            if hasattr(m, 'as_map'):
                 syntax_patterns.append(m.get_syntax())
             elif isinstance(m, dict):
-                pattern = ctx.get("syntax")
+                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"):
+                    if isinstance(layer, type) and hasattr(layer, 'as_map'):
                         layer = layer()
-                    if hasattr(layer, "as_map"):
+                    if hasattr(layer, 'as_map'):
                         d = layer.as_map()
                     elif isinstance(layer, dict):
                         d = layer
                     else:
                         continue
+
                     if k in d:
                         return str(d[k])
 
                 if k in ctx:
                     return str(ctx[k])
 
-                raise MissingKeyError(f"Missing key '{k}' in any layer or context")
+                raise MissingKeyError(f'Missing key "{k}" in any layer or context')
 
             try:
                 text = re.sub(pattern, repl, text)
             except re.error as exc:
-                raise MapSyntaxError(f"Regex error in syntax pattern {pattern}: {exc}") from 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}'")
+                raise MissingKeyError(f'Missing ctx key "{k}"')
             return str(d[k])
+
         try:
             return re.sub(pattern, repl, text)
         except re.error as exc:
-            raise MapSyntaxError(f"Regex error in ctx syntax: {exc}") from exc
+            raise MapSyntaxError(f'Regex error in ctx syntax: {exc}') from exc
 
     # one pass
     def _resolve_once(self, text: str, ctx: dict, layerstack: LayerStack) -> str:
@@ -124,45 +176,52 @@ 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
     ) -> str:
-        """
+        '''
         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)
+                temp = LayerStack([Layer('override', override_maps, priority=0)])
+                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)
+                temp.add_layer(Layer('extra', extra_maps, priority=999))
+                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)
@@ -172,14 +231,34 @@ class MapResolver:
         except MapResError:
             raise
         except Exception as exc:
-            raise MapResError(f"Unhandled resolver error: {exc}") from exc
+            raise MapResError(f'Unhandled resolver error: {exc}') from exc
+
+
+# ----------------------------------
+# ---------- 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)
 
-# global resolver
-_DEFAULT = MapResolver()
+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:
-    """
-    Resolve using the global default resolver.
-    """
-    return _DEFAULT.res(text, **ctx)
+def res(text: str, passes=None, **ctx) -> str:
+    '''
+    Simple resolution using the global default resolver.
+    '''
+    return _DEFAULT_RESOLVER.res(text, passes=passes, **ctx)

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

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

mapres-2.3/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)

mapres-2.3/src/mapres/maps/color.py

@@ -1,75 +0,0 @@
-from mapres.datamap import datamap, syntax
-
-@datamap(syntax=syntax.angles) # produces <>
-class ColorMap:
-    black: str = "\033[30m"
-    dark_blue: str = "\033[34m"
-    dark_green: str = "\033[32m"
-    dark_aqua: str = "\033[36m"
-    dark_red: str = "\033[31m"
-    dark_purple: str = "\033[35m"
-    gold: str = "\033[33m"
-    gray: str = "\033[37m"
-    dark_gray: str = "\033[90m"
-    blue: str = "\033[94m"
-    green: str = "\033[92m"
-    aqua: str = "\033[96m"
-    red: str = "\033[91m"
-    light_purple: str = "\033[95m"
-    yellow: str = "\033[93m"
-    white: str = "\033[97m"
-    reset: str = "\033[0m"
-    bold: str = "\033[1m"
-    italic: str = "\033[3m"
-
-    def as_dict(self):
-        return {f"<{k}>": getattr(self, k) for k in self.__dataclass_fields__}
-
-# ASCII color map
-ascii_colors = ColorMap()
-
-# Minecraft color map
-mc_colors = ColorMap(
-    black="§0",
-    dark_blue="§1",
-    dark_green="§2",
-    dark_aqua="§3",
-    dark_red="§4",
-    dark_purple="§5",
-    gold="§6",
-    gray="§7",
-    dark_gray="§8",
-    blue="§9",
-    green="§a",
-    aqua="§b",
-    red="§c",
-    light_purple="§d",
-    yellow="§e",
-    white="§f",
-    reset="§r",
-    bold="§l",
-    italic="§o"
-)
-
-# Color strip map
-strip_colors = ColorMap(
-    black="",
-    dark_blue="",
-    dark_green="",
-    dark_aqua="",
-    dark_red="",
-    dark_purple="",
-    gold="",
-    gray="",
-    dark_gray="",
-    blue="",
-    green="",
-    aqua="",
-    red="",
-    light_purple="",
-    yellow="",
-    white="",
-    reset="",
-    bold="",
-    italic=""
-)