mapres Quickstart: Resolve Strings with DataMaps and Layers

This quickstart walks you through the essential building blocks of mapres — from the zero-setup global resolver right through to layered DataMaps and the built-in color and time utilities. By the end you will have a working resolution pipeline and a clear mental model of how all the pieces fit together.

Install and import mapres

Install the package from PyPI if you have not already done so, then import what you need:

pip install mapres

import mapres

# Or import specific names directly:
from mapres import MapResolver, LayerStack, Layer, datamap, syntax
from mapres import ColorMap, ascii_colors, mc_colors, TimeMap

Resolve strings with the global res() shortcut

The fastest way to use mapres requires zero configuration. The module-level res() function wraps a default MapResolver with no layers and resolves {key} placeholders from keyword arguments you pass directly:

from mapres import res

result = res("Hello, {name}!", name="World")
print(result)
# Hello, World!

# Multiple placeholders work the same way
greeting = res("Good morning, {first} {last}!", first="Ada", last="Lovelace")
print(greeting)
# Good morning, Ada Lovelace!

The global res() function uses a default resolver with no layers — pass values as keyword arguments. For layered DataMaps, syntax providers, or pipeline transforms, create a MapResolver instance directly (see the next steps).

Define a typed DataMap

A DataMap is a regular Python dataclass decorated with @datamap. It carries its own placeholder syntax and exposes all its fields as a resolved key-value map via as_map(). Choose a syntax style per class using the built-in syntax constants:

from mapres import datamap, syntax

@datamap(syntax=syntax.braces)   # placeholders look like {key}
class PlayerMap:
    name: str = "Steve"
    level: int = 1
    rank: str = "Member"

# Instantiate with specific values
player = PlayerMap(name="Herobrine", level=42, rank="Admin")

# Inspect the resolved map
print(player.as_map())
# {'name': 'Herobrine', 'level': 42, 'rank': 'Admin'}

The four available syntax styles are:

Constant	Pattern	Example
`syntax.braces`	`{key}`	`{name}`
`syntax.dollars`	`${key}`	`${name}`
`syntax.angles`	`<key>`	`<name>`
`syntax.percents`	`%key%`	`%name%`

You can also use the decorator shortcut forms @datamap.braces, @datamap.angles, @datamap.dollars, and @datamap.percents without passing arguments.

Build a LayerStack and resolve with MapResolver

For real applications you will compose multiple DataMaps into a LayerStack, where each Layer has a priority — lower numbers are applied first, and higher-priority layers win when the same key exists in more than one layer. Pass the stack to a MapResolver and call resolver.res():

from mapres import MapResolver, LayerStack, Layer, datamap, syntax

@datamap(syntax=syntax.braces)
class ServerMap:
    server_name: str = "My Server"
    motd: str = "Welcome!"

@datamap(syntax=syntax.braces)
class PlayerMap:
    name: str = "Steve"
    rank: str = "Member"

# Create layers with explicit priorities
server_layer = Layer("server", [ServerMap()], priority=10)
player_layer = Layer("player", [PlayerMap(name="Herobrine", rank="Admin")], priority=20)

# Stack the layers (higher priority = consulted last, wins on conflict)
stack = LayerStack([server_layer, player_layer])

# Create the resolver and resolve a string
resolver = MapResolver(layers=stack)
result = resolver.res("[{server_name}] {name} ({rank}) joined — {motd}")
print(result)
# [My Server] Herobrine (Admin) joined — Welcome!

You can also pass extra_maps or override_maps at call-time without modifying the base stack:

# Temporarily inject an extra layer for one call
result = resolver.res("{server_name}: {event}", extra_maps={"event": "Server restart"})
print(result)
# My Server: Server restart

Use the built-in ColorMap and TimeMap

mapres ships two ready-made DataMaps. ColorMap uses <key> syntax and maps colour names to ANSI escape codes (or Minecraft § codes). TimeMap uses %key% syntax and dynamically provides live date and time values.ColorMap — terminal ANSI colours:

from mapres import MapResolver, LayerStack, Layer, ascii_colors

color_layer = Layer("colors", [ascii_colors], priority=10)
stack = LayerStack([color_layer])
resolver = MapResolver(layers=stack)

message = resolver.res("<green>Server started<reset> in <yellow>{ms}ms<reset>", ms=42)
print(message)
# (prints "Server started" in green, "42ms" in yellow, rest reset)

ColorMap — Minecraft § codes:

from mapres import MapResolver, LayerStack, Layer, mc_colors

mc_layer = Layer("mc_colors", [mc_colors], priority=10)
stack = LayerStack([mc_layer])
resolver = MapResolver(layers=stack)

broadcast = resolver.res("<gold>[<red>ALERT<gold>]<white> {player} was banned.", player="Griefer99")
print(broadcast)
# §6[§cALERT§6]§f Griefer99 was banned.

TimeMap — live timestamps:

from mapres import MapResolver, LayerStack, Layer, TimeMap

# TimeMap accepts an optional IANA timezone string
time_layer = Layer("time", [TimeMap(tz="America/New_York")], priority=10)
stack = LayerStack([time_layer])
resolver = MapResolver(layers=stack)

log_line = resolver.res("[%YYYY%-%MM%-%DD% %hh%:%mm%:%ss%] Server heartbeat OK")
print(log_line)
# [2024-07-15 14:32:07] Server heartbeat OK

Available TimeMap keys include: %hh%, %h%, %hh12%, %h12%, %ampm%, %mm%, %m%, %ss%, %s%, %ms%, %YYYY%, %MM%, %DD%, and %weekday%.strip_colors — remove all colour codes:strip_colors is a pre-built ColorMap instance where every colour name maps to an empty string. Use it to strip colour placeholders from a string without producing any ANSI or Minecraft codes:

from mapres import MapResolver, LayerStack, Layer, strip_colors

strip_layer = Layer("colors", [strip_colors], priority=10)
stack = LayerStack([strip_layer])
resolver = MapResolver(layers=stack)

plain = resolver.res("<green>Hello<reset>, <bold>world<reset>!")
print(plain)
# Hello, world!

time alias and maps namespace:The time export is an alias for the TimeMap class itself — both names refer to the same object:

from mapres import time, TimeMap

assert time is TimeMap  # True

All color and time exports are also available through the maps namespace object, which groups them for convenience:

from mapres import maps

# maps.ColorMap, maps.ascii_colors, maps.mc_colors, maps.strip_colors
# maps.TimeMap, maps.time
color_layer = Layer("colors", [maps.ascii_colors], priority=10)

Next steps

Core Concepts

Deep-dive into DataMaps, LayerStack priority resolution, and the full MapResolver API.

Built-in Maps

Explore all ColorMap colour names, Minecraft colour codes, and the complete TimeMap token reference.

Pipeline Guide

Learn how to chain transform stages through the MapResolver pipeline to pre- or post-process resolved strings.

Get Started

Core Concepts

Built-in Maps

Guides

mapres Quickstart: Resolve Strings with DataMaps and Layers

Next steps

Core Concepts

Built-in Maps

Pipeline Guide

Build docs developers (and LLMs) love

Get Started

Core Concepts

Built-in Maps

Guides

Documentation Index

​Next steps

Core Concepts

Built-in Maps

Pipeline Guide

Build docs developers (and LLMs) love

Next steps