Python on Man-You

Rate limiting with a single Lua script

Tue, 10 Feb 2026 09:49:00 +0200

We needed rate limiting across all our services: FastAPI, Django, you name it. The usual approach is to grab a library, wire it up per-framework, and accept the slight differences in behavior between them. We went a different way: one Lua script that runs atomically in Redis, with everything else being thin wrappers around it.

This is how the rate limiting system in application-kit works, including per-project overrides, element-based counting, and a monitor mode for gradual rollouts.

The problem with two rate limiters

Early on, we had two Lua scripts: one for basic path-based rate limiting and another for per-project limits with override support. They did almost the same thing but diverged just enough to be annoying. Bug fixes had to land in two places. Behavior wasn’t always consistent. The classic duplication trap.

The fix was to collapse both into a single script (PROJECT_RATE_LIMITER_LUA) with optional parameters that fall back to sensible defaults. No override key? It behaves like a simple limiter. Pass one? It checks per-project overrides atomically.

One Lua script to rule them all

The core idea: every rate limit check is a single atomic Redis operation. No round-trips, no race conditions between reading the count and incrementing it.

The unified Lua script (simplified)

local rate_limit_key = KEYS[1]
local override_key = KEYS[2]
local default_max_requests = tonumber(ARGV[1])
local default_expiry = tonumber(ARGV[2])
local increment_amount = tonumber(ARGV[3]) or 1

-- Check for per-project override
local max_requests = default_max_requests
local expiry = default_expiry

if override_key ~= "" then
 local override = redis.call('HGETALL', override_key)
 if #override > 0 then
 -- Parse hash fields into max_requests and expiry
 for i = 1, #override, 2 do
 if override[i] == "max_requests" then
 max_requests = tonumber(override[i + 1])
 elseif override[i] == "expiry" then
 expiry = tonumber(override[i + 1])
 end
 end
 end
end

-- Get current count
local count = tonumber(redis.call('GET', rate_limit_key)) or -1
local is_over_limit = 0

if count == -1 then
 -- First request in this window
 redis.call('SET', rate_limit_key, increment_amount)
 redis.call('EXPIRE', rate_limit_key, expiry)
 count = increment_amount
 if count > max_requests then
 is_over_limit = 1
 end
elseif count + increment_amount > max_requests then
 is_over_limit = 1
else
 count = redis.call('INCRBY', rate_limit_key, increment_amount)
end

local ttl = redis.call('TTL', rate_limit_key)
return {is_over_limit, count, ttl, max_requests}

The script takes two keys and three arguments:

KEYS[1]: the counter key (e.g. ratelimit:/api/search:1:42)
KEYS[2]: the override key (empty string means “no overrides”)
ARGV[1..3]: default max requests, expiry in seconds, and increment amount

Everything after that is Redis doing its thing. One EVALSHA, one atomic operation, four values back.

Redis key layout

The key format puts the endpoint first and IDs at the end:

Counter: ratelimit:{endpoint}:{org_id}:{project_id}
Override: ratelimit_override:{endpoint}:{org_id}:{project_id}

This ordering matters. Endpoint names can contain colons (like api:v1:search), so we parse keys from the right: the last two segments are always org_id:project_id. The parse_override_key() function handles this reliably, stripping the known prefix and extracting integers from the tail.

Counters auto-expire via Redis TTL. When the window ends, the key vanishes and the next request starts fresh.

Per-project overrides

The override system uses Redis hashes. An override key like ratelimit_override:/api/search:1:42 stores:

max_requests = "500"
expiry = "120"

Because the Lua script checks for overrides inside the same atomic call, there’s no window where a request could slip through with stale limits. If an override exists, it replaces the defaults. If it doesn’t, the defaults apply. Zero ambiguity.

Overrides have their own optional TTL (independent of the rate limit window), so you can set a temporary elevated limit that auto-expires:

Setting a temporary override

await set_rate_limit_override(
 redis, org_id=1, project_id=42,
 endpoint="/api/search",
 max_requests=500, expiry=120,
 override_ttl=86400 # Override expires in 24h, limit window is still 120s
)

Management functions (set, get, delete, list, clear) are provided but designed for admin/provisioning services. Not every consumer needs them.

Element-based counting

Not all requests are equal. A distance matrix call with 10 origins and 5 destinations should count as 50 elements, not 1 request.

The increment_amount parameter in the Lua script makes this trivial. Instead of INCR, we use INCRBY:

Element-based rate limiting

# Request: 10 origins x 5 destinations = 50 elements
rows, cols = len(request.origins), len(request.destinations)

await apply_element_rate_limit(
 request, response,
 max_requests=1000, # 1000 elements per minute
 expiry=60,
 increment_amount=rows * cols, # This request costs 50
 redis_client=redis,
)

Element counters use a key_suffix (default: /elements) to maintain separate counters from regular request counting. Same endpoint, two independent limits:

ratelimit:/api/matrix:1:42 → request counter
ratelimit:/api/matrix:/elements:1:42 → element counter

Monitor mode

Rolling out rate limits on existing APIs is nerve-wracking. You want to know who would be affected before actually blocking anyone.

Monitor mode (RATE_LIMIT_MODE=monitor) runs the full rate limit logic (counting, checking, setting headers) but never returns a 429. Instead, it tags the Datadog root span:

Monitor mode behavior

if result.is_over_limit and mode == RateLimitMode.monitor:
 span = tracer.current_root_span()
 if span:
 span.set_tag("ratelimit.over_limit", endpoint_path)

Clients still see RateLimit-Remaining: 0 in response headers, so they can self-throttle if they’re polite. But the server won’t enforce it.

Three modes, set via the Bender manifest:

Mode	Counts	Headers	Blocks	Datadog tag
`on`	Yes	Yes	Yes (429)	No
`off`	No	No	No	No
`monitor`	Yes	Yes	No	Yes

The setting is read dynamically on every request. No restart needed to switch modes.

Framework wrappers

FastAPI: three entry points

FastAPI gets the most complete support with three ways to rate limit:

1. ProjectRateLimiter: the recommended default. Uses dependency injection, extracts project identity from the authenticated request, supports overrides and monitor mode:

FastAPI ProjectRateLimiter

@router.get(
 "/search",
 dependencies=[Depends(ProjectRateLimiter(max_requests=100, expiry=60))],
)
async def search():
 ...

It follows the template method pattern: make_key() and make_override_key() can be overridden without touching the rate limit logic itself:

Custom rate limiter via subclassing

class GeoRateLimiter(ProjectRateLimiter):
 def make_key(self, request: Request) -> str | None:
 region = request.headers.get("X-Region", "default")
 base = super().make_key(request)
 return f"{base}:{region}" if base else None

2. PathRateLimiter: simpler, no project isolation. Useful for public or webhook endpoints where there’s no authenticated project:

FastAPI PathRateLimiter

@router.post(
 "/webhook",
 dependencies=[Depends(PathRateLimiter(max_requests=10, expiry=60))],
)
async def webhook():
 ...

3. Programmatic API: apply_rate_limit() and apply_element_rate_limit() for when limits depend on request content:

Runtime-determined limits

async def process_batch(request: Request, response: Response):
 batch_size = len(request.json()["items"])
 await apply_element_rate_limit(
 request, response,
 max_requests=500, expiry=60,
 increment_amount=batch_size,
 redis_client=redis,
 )

Django: decorator-based

Django uses a @rate_limit decorator that auto-detects sync vs. async views:

Django rate limiting

@authenticate_key()
@rate_limit(max_requests=100, expiry=60)
def my_view(request):
 return JsonResponse({"status": "ok"})

The endpoint name is auto-detected from the URL pattern (e.g. /api/v1/datasets/<int:dataset_id>/search). Django middleware catches RateLimitExceeded exceptions and returns a 429 with the proper rate limit headers.

Both frameworks share the same Lua script, the same key generation functions, and the same result handling logic. The wrappers are genuinely thin.

The result object

Every rate limit check produces a RateLimitResult:

RateLimitResult

@dataclass(frozen=True)
class RateLimitResult:
 is_over_limit: bool
 request_count: int
 ttl: int
 max_requests: int

 @property
 def remaining(self) -> int:
 return max(0, self.max_requests - self.request_count)

 def to_headers(self) -> dict[str, str]:
 return {
 "RateLimit-Limit": str(self.max_requests),
 "RateLimit-Remaining": str(self.remaining),
 "RateLimit-Reset": str(self.ttl),
 }

Frozen dataclass, immutable, with a convenience method for standard rate limit headers. Every response (except when mode is off) gets these three headers so clients can implement their own backoff.

What made this work

A few design decisions that paid off:

Atomic override resolution. The Lua script checks overrides inside the same call that does the counting. No separate Redis roundtrip means no race condition between “check the override” and “apply the limit.”

Optional parameters with backwards-compatible defaults. override_key="" and increment_amount=1 mean the same script handles simple path limiting, per-project limiting, and element counting. No script duplication.

Dynamic configuration. get_rate_limit_mode() calls into Bender on every request. No cached settings, no restarts. Switch from monitor to on when you’re confident.

Separate counters via key suffix. Element counting doesn’t interfere with request counting. Same endpoint, independent limits, same Lua script.

The whole thing is tested with fakeredis[lua], which actually executes the Lua script, so the tests are as close to production behavior as you can get without a real Redis.

Migrating Python containers to Wolfi and uv

Tue, 10 Feb 2026 09:00:00 +0200

Our Python services ran on ubuntu:24.04 with pip-installed dependencies. It worked, but the images carried hundreds of packages we never used, Trivy scans were noisy with OS-level CVEs, and builds were slower than they needed to be. Over a couple of months we migrated to Chainguard’s Wolfi base image and uv for dependency management. This is how it went for the maps service, the one that renders static map tiles with a C++/Python hybrid stack.

Cleaning up dependency management with uv

Before touching the base image, we sorted out the dependency mess. The maps service had drifted. pyproject.toml declared one set of versions, uv.lock referenced another, and a private package (maparazzo) was pinned to a version that didn’t exist on the registry anymore.

The first PR synced the lock file with reality and bumped maparazzo to a published version. The second one removed version constraints from pyproject.toml entirely, keeping only the lock file as the source of truth:

pyproject.toml (before)

dependencies = [
 "application_kit[fastapi]",
 "fastapi>=0.115.0",
 "maparazzo==0.4.0",
 "aiosqlite>=0.20.0",
 "valkey-glide==2.2.5",
 "sniffio>=1.3.1",
 # Dev tools
 "types-redis>=4.6.0",
 "coverage[toml]>=7.6.0",
 "pytest>=8.3.0",
 "pytest-asyncio>=0.24.0",
 "pytest-cov>=6.0.0",
 "respx>=0.22.0",
 "ruff>=0.8.0",
 "mypy>=1.14.0",
]

pyproject.toml (after)

dependencies = [
 "application_kit[fastapi]",
 "maparazzo==2.0.0",
 "aiosqlite",
 "valkey-glide==2.2.5",
 "sniffio",
]

[dependency-groups]
dev = [
 "types-redis",
 "coverage[toml]",
 "pytest",
 "pytest-asyncio",
 "pytest-cov",
 "respx",
 "ruff",
 "mypy",
]

Two changes happened here. First, lower bounds like >=0.115.0 were dropped: the lock file already pins exact versions, so the constraints in pyproject.toml were just noise that could silently go stale. Second, dev tools moved to a proper [dependency-groups] section. This matters for the multi-stage build that comes next: uv sync --no-dev now skips pytest, ruff, mypy, and the rest. Previously they all shipped in the production image.

Running uv lock --upgrade after removing the constraints updated 23 packages in under 3 seconds. That’s the part of uv that makes the biggest day-to-day difference: resolving a 60-package graph is nearly instant.

The Ubuntu Dockerfile

Here’s what we had before:

Dockerfile (Ubuntu-based)

FROM ubuntu:24.04 AS base
ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy
ENV UV_PYTHON_INSTALL_DIR=/python
ENV UV_PYTHON_PREFERENCE=only-managed

COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

RUN uv python install 3.12

WORKDIR /usr/src/app
ENV UV_PROJECT_ENVIRONMENT=/usr/src/venv

RUN --mount=type=cache,target=/root/.cache/uv \
 --mount=type=bind,source=uv.lock,target=uv.lock \
 --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
 uv sync --frozen --no-install-project --no-dev

ADD . /usr/src/app

RUN --mount=type=cache,target=/root/.cache/uv \
 uv sync --frozen --no-dev

FROM ubuntu:24.04

ARG DEBIAN_FRONTEND="noninteractive"
ENV PACKAGES="ca-certificates libopengl0 libegl1 curl"

RUN apt-get update && apt-get install --no-install-recommends -y \
 ${PACKAGES} && apt-get clean && apt-get autoclean && apt-get autoremove \
 && rm -rf /var/lib/apt/lists/*

COPY --from=base --chown=python:python /python /python
COPY --from=base --chown=app:app /usr/src/venv /usr/src/venv
COPY --from=base --chown=app:app /usr/src/app /usr/src/app

WORKDIR /usr/src/app
ENV PATH="/usr/src/venv/bin:$PATH"

RUN python ./minify_styles.py

EXPOSE 8000

This was already using uv and multi-stage builds, which was good. But the production stage started from a fresh ubuntu:24.04, which pulls in apt, dpkg, systemd fragments, locales, and hundreds of other packages that a Python web service never touches. The apt-get update && apt-get install dance also meant the image wasn’t reproducible: two builds a week apart could get different package versions.

The COPY --from=ghcr.io/astral-sh/uv:latest was another problem. latest means the uv version changes silently. If a new uv release changes lock file behavior or introduces a bug, your CI breaks with no obvious diff.

Switching to Wolfi

Wolfi is a Linux distribution built specifically for containers. No package manager bloat, no shell login infrastructure, minimal base. Chainguard maintains it and publishes daily CVE-patched images.

The new Dockerfile:

Dockerfile (Wolfi-based)

FROM cgr.dev/chainguard/wolfi-base AS base

RUN apk add --no-cache \
 mesa-egl \
 mesa-gl \
 mesa-gbm \
 libgcc \
 libstdc++ \
 bash \
 ca-certificates-bundle

ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy
ENV UV_PYTHON_INSTALL_DIR=/python
ENV UV_PYTHON_PREFERENCE=only-managed

COPY --from=ghcr.io/astral-sh/uv:0.9.18 /uv /uvx /bin/

RUN uv python install 3.12

WORKDIR /usr/src/app
ENV UV_PROJECT_ENVIRONMENT=/usr/src/venv

RUN --mount=type=cache,target=/root/.cache/uv,id=uv-base \
 --mount=type=bind,source=uv.lock,target=uv.lock \
 --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
 uv sync --frozen --no-install-project --no-dev

COPY . /usr/src/app

RUN --mount=type=cache,target=/root/.cache/uv,id=uv-base \
 uv sync --frozen --no-dev

RUN /usr/src/venv/bin/python ./minify_styles.py


FROM base AS build

RUN --mount=type=cache,target=/root/.cache/uv,id=uv-build \
 uv sync --frozen

ENV PATH="/usr/src/venv/bin:$PATH"
ENV RUFF_CACHE_DIR=/tmp/.ruff_cache
ENV MYPY_CACHE_DIR=/tmp/.mypy_cache
ENV COVERAGE_FILE=/tmp/.coverage


FROM base AS prod

ENV PATH="/usr/src/venv/bin:$PATH"
ENV PYTHONUNBUFFERED=1

USER 65532

EXPOSE 8000

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
 CMD ["/usr/src/app/healthcheck.sh"]

A few things to unpack.

Three stages instead of two

The old Dockerfile had base (build everything) and a final production stage that copied artifacts. The new one has three:

Stage	Purpose	Packages
`base`	Install runtime deps, sync production packages	Runtime only
`build`	Extends base, adds dev deps for testing in CI	Runtime + dev
`prod`	Extends base, sets non-root user and healthcheck	Runtime only

The build stage is what CI uses to run pytest, ruff, and mypy. The prod stage is what ships. Both extend base, so there’s no duplication of the dependency installation step.

The build stage redirects tool caches to /tmp because the app directory is read-only for the non-root user:

Tool cache redirection for CI

ENV RUFF_CACHE_DIR=/tmp/.ruff_cache
ENV MYPY_CACHE_DIR=/tmp/.mypy_cache
ENV COVERAGE_FILE=/tmp/.coverage

Pinned uv version

uv:latest became uv:0.9.18. One line, but it eliminates an entire class of “works on my machine” issues. When we want to upgrade uv, we do it explicitly in a PR.

Non-root production

The prod stage runs as UID 65532, matching the convention from distroless images. The base stage still runs as root (needed for apk add and uv python install), but the production image drops privileges before the entrypoint.

Minification at build time

The old Dockerfile ran python ./minify_styles.py in the production stage at container startup (well, at build time of the final stage, but from a fresh Ubuntu). The new one runs it in the base stage right after syncing dependencies. This means the minified assets are baked in and shared by both build and prod.

Build cache isolation

The --mount=type=cache directives got id=uv-base and id=uv-build suffixes. Without these, Docker can share cache mounts between stages that run concurrently in BuildKit, which causes lock contention.

The s5cmd surprise

After deploying the Wolfi image, the tile generation job broke. It ran a shell script that downloaded s5cmd (an S3-compatible file transfer tool) at runtime:

tile.sh (runtime download, broken)

if ! [ -x "$(command -v s5cmd)" ]; then
 curl -L \
 https://github.com/peak/s5cmd/releases/download/v2.2.2/s5cmd_2.2.2_Linux-64bit.tar.gz \
 > s5cmd.tar.gz
 tar -xzvf ./s5cmd.tar.gz --directory /usr/local/bin/
 rm ./s5cmd.tar.gz
fi

Two problems. First, curl wasn’t in the image anymore; we’d removed it during the Wolfi migration because the application code doesn’t need it. Second, even if curl was there, extracting to /usr/local/bin/ would fail because the container runs as non-root.

The fix was one line in the Dockerfile and deleting the download script:

Installing s5cmd via apk

RUN apk add --no-cache \
 mesa-egl \
 mesa-gl \
 mesa-gbm \
 libgcc \
 libstdc++ \
 bash \
 s5cmd \
 ca-certificates-bundle

Wolfi has s5cmd v2.3.0 in its package repository, newer than the v2.2.2 being downloaded. Installing it at build time is faster, more reliable, and gets security updates through the normal apk channel.

This is the kind of thing that falls out of a migration like this. Runtime downloads of binaries are a pattern that works on fat base images but breaks the moment you tighten things up. And they should break. Downloading unsigned tarballs into a running container is a supply chain risk hiding in plain sight.

Scan results

After the migration, Trivy against the production image:

Severity	Before (Ubuntu)	After (Wolfi)
CRITICAL	0	0
HIGH	3	0
MEDIUM	12	0
LOW	27	0

The Ubuntu image had 42 findings, all in OS packages we never used. The Wolfi image has zero because it only contains packages we explicitly installed. The Python dependency layer had 2 findings in both cases (a starlette version that needed bumping), but the OS layer went from noisy to clean.

Dockle (Dockerfile best-practices linter) reports one false positive: it flags settings.py as a potential credential file because of the filename. Suppressed with dockle -af settings.py.

What made it work

A few things that helped this go smoothly:

uv’s dependency groups. Separating dev tools from runtime dependencies in pyproject.toml is what makes --no-dev actually useful. Before, pytest and ruff shipped in production because they were in the same flat dependency list.

Wolfi’s package repository. Having s5cmd, Mesa GL libraries, and a recent bash available via apk meant we didn’t need to maintain custom installation scripts. The packages are rebuilt daily with CVE patches.

The three-stage pattern. base splitting into build and prod is now our standard for Python services. CI targets build, production targets prod, and both share the same dependency installation.

Pinning uv. Sounds trivial but it removed a real source of non-determinism. uv:latest in a Dockerfile is the same antipattern as pip install package without a version: it works until it doesn’t, and you won’t know why.

A map style compiler in Python

Sat, 07 Feb 2026 16:00:00 +0200

BAM!

Generating Mapbox GL GL style JSON from Python code instead of editing 3,000-line JSON files by hand. Hierarchical style resolution, a Django-style filter DSL, injection-based layer ordering, and a Go sprite generator called from Python via ctypes.

The problem with style JSON

A Mapbox GL GL style is a single JSON file that describes everything about how a map looks. Background color, road widths at every zoom level, label fonts, icon placement, landcover tints, building extrusion heights. All of it.

A real production style runs to thousands of lines. Ours had over 150 layers. Roads alone need six layer variants each (tunnel casing, tunnel fill, road casing, road fill, bridge casing, bridge fill), and there are eight road classes. That’s 48 road layers before you count labels, oneway arrows, or rail.

Editing this by hand is slow and error-prone. Change the motorway color and you need to find it in six places. Add a new road class and you need to insert layers at exactly the right positions between tunnels and bridges. Reorder a layer and you break z-ordering for everything above it.

Python instead of JSON

The style compiler replaces hand-edited JSON with Python code. You define layers, colors, filters, and style properties in Python. The compiler resolves everything and emits a Mapbox GL GL style JSON file.

python -m map_style --style=streets -o style/streets_classic.json

The output is a standard Mapbox GL GL style: the renderer doesn’t know or care that it was generated. But the source is modular, typed, and DRY.

Layer definitions

A road is defined once. ClassicRoadDataNode generates all six variants:

streets_classic/roads.py

ClassicRoadDataNode(
 "motorway",
 classes=["motorway"],
 feature_type="road.highway.motorway",
 extra_filter=~Q(ramp__eq=1),
 casing_feature_type="road.highway.motorway",
)

This produces:

tunnel_motorway_casing: tunnel stroke
tunnel_motorway: tunnel fill
road_motorway_casing: road stroke
road_motorway: road fill
bridge_motorway_casing: bridge stroke
bridge_motorway: bridge fill

Each variant gets the correct brunnel filter automatically. Tunnel layers filter on brunnel == "tunnel", bridge on brunnel == "bridge", normal roads on brunnel not in ["bridge", "tunnel"].

Rail works the same way: ClassicRailDataNode generates tunnel, road, and bridge variants with optional hatching layers for the cross-ties pattern.

Injection points

With 150+ layers, ordering is everything. Roads must render above landcover. Bridges must render above buildings. Labels above everything. Getting one layer out of place breaks the visual hierarchy.

Instead of maintaining an explicit ordered list, the system uses injection points: named slots that define the rendering order:

generator/data.py

class InjectionsNames(Enum):
 TUNNEL_ROAD_CASING = "tunnel_road_casing"
 TUNNEL_ROAD = "tunnel_road"
 ROAD_AREA = "road_area"
 ROAD_CASING = "road_casing"
 ROAD = "road"
 BUILDING = "_building_injection"
 BRIDGE_ROAD_CASING = "bridge_road_casing"
 BRIDGE_ROAD = "bridge_road"
 BUILDING_3D = "building_3d"
 LABEL = "labels"
 POI_SYMBOL = "poi_symbol"

Layers insert themselves before a named injection point:

stack.add_layer_before(InjectionsNames.ROAD, Layer("road_motorway", ...))
stack.add_layer_before(InjectionsNames.BRIDGE_ROAD, Layer("bridge_motorway", ...))

The Stack maintains the order. Injection points themselves are stripped from the final output. They’re scaffolding, not layers. Adding a new road class doesn’t require knowing the index of every other layer. You just say “this goes in the ROAD group” and the system handles placement.

Filter DSL

Mapbox GL filters are nested JSON arrays. Writing them by hand is unreadable:

["all", ["==", ["get", "class"], "motorway"], ["!", ["in", ["get", "brunnel"], ["literal", ["bridge", "tunnel"]]]]]

The compiler uses Django-style Q objects instead:

Q(class__eq="motorway") & ~Q(brunnel__in=["bridge", "tunnel"])

& means AND, | means OR, ~ means NOT. The ExpressionSet class compiles Q trees to Mapbox GL expressions:

generator/filters.py

OPERATORS = {
 "eq": "==", "neq": "!=",
 "gt": ">", "gte": ">=",
 "lt": "<", "lte": "<=",
}

# Q(class__in=["motorway"]) becomes:
# ["in", ["get", "class"], ["literal", ["motorway"]]]

# Q(brunnel__exists=False) becomes:
# ["!", ["has", "brunnel"]]

Filters compose naturally. The ramp filter for motorway links:

Q(class__in=["motorway"]) & Q(ramp__eq=1)

The non-ramp filter for main motorways:

Q(class__in=["motorway"]) & ~Q(ramp__eq=1)

The Case class builds conditional expressions for layers that vary by feature class, like different icon colors per POI type:

case = Case({"restaurant": Q(class__eq="restaurant"), "hospital": Q(class__eq="hospital")})
case.resolve({"restaurant": "#e74c3c", "hospital": "#3498db"}, default="#666")
# ["case", ["==", ["get", "class"], "restaurant"], "#e74c3c",
# ["==", ["get", "class"], "hospital"], "#3498db", "#666"]

Hierarchical style resolution

A StyleTree organizes paint and layout properties in a dot-separated hierarchy. Child selectors inherit from parents:

streets_classic/style.py

styles = {
 "road": StyleElement(paint=LinePaint(line_cap="round")),
 "road.highway": StyleElement(paint=LinePaint(line_color=ROAD_HIGHWAY_FILL_COLOR, line_width=4)),
 "road.highway.motorway": StyleElement(paint=LinePaint(line_width=6)),
}

Resolving road.highway.motorway walks the tree from root to leaf, collecting all StyleElement instances along the path. Properties merge: the motorway gets line_cap="round" from road, line_color="#fc8" from road.highway, and line_width=6 from its own node.

generator/styler.py

def resolve(self, selector_path: str) -> list[StyleElement]:
 nodes = self.get_node_path(selector_path)
 elements: list[StyleElement] = []
 for node in nodes:
 elements += node.elements
 return elements

Same pattern as CSS cascade, but explicit. You see exactly what inherits from where by reading the selector paths. No specificity wars.

Colors

The color module parses hex, RGB, RGBA, HSL, and HTML color names. More usefully, it does HSL-based transformations:

generator/color.py

Color("#fc8").darken(-0.3).to_rgba()
# Shifts lightness down by 30%, used for deriving label colors from fill colors

All colors live in one file per style:

streets_classic/colors.py

BACKGROUND_COLOR = "rgba(252, 247, 229, 1)"
WATER_COLOR = "rgba(134, 204, 250, 1)"
ROAD_HIGHWAY_FILL_COLOR = "#fc8"
ROAD_HIGHWAY_STROKE_COLOR = "#e9ac77"
ROAD_MINOR_FILL_COLOR = "#fff"
ROAD_MINOR_STROKE_COLOR = "hsl(35, 6%, 80%)"

Change a color constant, regenerate, and every layer using it updates. No grep through JSON.

Pydantic models for the style spec

Every Mapbox GL layer type has a corresponding Pydantic v2 model with strict validation:

generator/mapbox_style.py

class LinePaint(BaseModel):
 model_config = ConfigDict(populate_by_name=True)

 line_color: str | list[Any] | None = Field(None, alias="line-color")
 line_width: float | list[Any] | None = Field(None, alias="line-width")
 line_opacity: float | list[Any] | None = Field(None, alias="line-opacity")
 line_dasharray: list[float] | None = Field(None, alias="line-dasharray")
 line_cap: str | None = Field(None, alias="line-cap")
 # ...

The alias parameter handles the mismatch between Python identifiers (underscores) and Mapbox GL property names (hyphens). line_color in Python becomes line-color in JSON output.

Pydantic catches type errors at definition time, not when the renderer fails to parse the JSON. Pass a string where a number is expected and you get an immediate error.

Sprite generation

Map icons (POI markers, highway shields, oneway arrows) are packed into a sprite sheet: a single PNG with a JSON manifest mapping icon names to pixel regions.

The sprite generator is written in Go for performance. Python calls it through ctypes:

generator/sprite.py

lib = ctypes.CDLL(lib_path)
lib.GenerateSprite.argtypes = [ctypes.c_char_p, ctypes.c_char_p, ctypes.c_int]
lib.GenerateSprite.restype = ctypes.c_char_p

result = lib.GenerateSprite(
 icon_library_path.encode(),
 output_path.encode(),
 pixel_ratio, # 1 for sprite.png, 2 for sprite@2x.png
)

The Go library handles SVG rasterization, SDF (signed distance field) generation for runtime-colorable icons, bin-packing into a texture atlas, and both 1x and 2x output.

Template-based icon names resolve from filter context. When a layer uses icon-image: "{class}_15", the compiler extracts which class values the filter allows and registers each concrete icon (restaurant_15, hospital_15, etc.) for sprite generation.

POI metadata

POI layers carry metadata beyond what Mapbox GL needs. The Woosmap API uses it to support dynamic styling at runtime:

class POIMetadata:
 filter: list[Any]
 symbol_color: str
 text_color: str
 icon: str
 visible: bool

This metadata embeds in the layer’s metadata field (which Mapbox GL ignores but passes through). The API can query which POI categories exist, their colors, and their visibility, without parsing the style expressions.

Feature types follow a hierarchy: poi.school, poi.sports_complex, transit.station.rail. The LayerRegistry maps these to the concrete Mapbox GL layers they affect, enabling Google Maps-style feature type styling through the Woosmap SDK.

Multiple styles

The architecture supports multiple style variants from the same infrastructure. streets_classic is the production style. streets_satellite reuses the same layer definitions, road nodes, and filter DSL with a different color palette tuned for satellite imagery overlay: higher contrast labels, semi-transparent fills, no background color.

Adding a new style variant means writing a new color file and adjusting a few layer properties. The layer structure, injection points, and filter expressions stay the same.

What this gets you

The streets_classic style has ~150 renderable layers. The Python source is organized across about a dozen files: colors, roads, mapping, style tree, POI definitions. Each file is under 300 lines.

The equivalent hand-maintained JSON was one file, thousands of lines, with duplicated filter expressions and no inheritance. Every road color change required finding and editing six layer definitions. Every new road class required inserting layers at the correct positions relative to all other layers.

Now it’s: change a constant in colors.py, run the compiler, get a valid style JSON. Type-checked, with the layer ordering handled by injection points instead of manual index management.