dicebear-core 10.1.0__py3-none-any.whl

dicebear/__init__.py

@@ -0,0 +1,33 @@
+"""DiceBear core — deterministic, customizable, vector-based avatars.
+
+A faithful port of ``@dicebear/core`` (JS) and ``dicebear/core`` (PHP) that
+produces byte-identical SVG output for the same style and options.
+"""
+
+from __future__ import annotations
+
+from .avatar import Avatar
+from .errors import (
+    CircularColorReferenceError,
+    OptionsValidationError,
+    StyleValidationError,
+    ValidationError,
+)
+from .options_descriptor import OptionsDescriptor
+from .style import Style
+from .utils.color import Color
+
+# Public surface mirrors the JS index (Avatar, Style, Color, OptionsDescriptor)
+# plus the exception types Python consumers catch. Internals — Options, Prng,
+# Resolver, Renderer — remain importable from their submodules but are not
+# re-exported here.
+__all__ = [
+    "Avatar",
+    "CircularColorReferenceError",
+    "Color",
+    "OptionsDescriptor",
+    "OptionsValidationError",
+    "Style",
+    "StyleValidationError",
+    "ValidationError",
+]

dicebear/avatar.py

@@ -0,0 +1,52 @@
+"""Top-level entry point for rendering an avatar from a style and options."""
+
+from __future__ import annotations
+
+import copy
+from typing import Any
+from urllib.parse import quote
+
+from .options import Options
+from .renderer import Renderer
+from .resolver import Resolver
+from .style import Style
+
+# encodeURIComponent leaves A-Za-z0-9 and -_.!~*'() unescaped. Python's quote
+# always keeps letters, digits, and _.-~; adding !*'() to ``safe`` reproduces
+# the JS set exactly (and drops the default '/' so it is escaped like JS does).
+_DATA_URI_SAFE = "!*'()"
+
+
+class Avatar:
+    """Top-level entry point for rendering an avatar from a style and options.
+
+    Construction immediately resolves and renders the SVG; the various accessor
+    methods return different serializations of that result.
+    """
+
+    def __init__(
+        self, style_input: Any, options_input: dict[str, Any] | None = None
+    ) -> None:
+        style = style_input if isinstance(style_input, Style) else Style(style_input)
+        options = Options(options_input)
+        resolver = Resolver(style, options)
+
+        self._svg = Renderer(style, resolver).render()
+        self._resolved_options = resolver.resolved()
+
+    def __str__(self) -> str:
+        return self._svg
+
+    def to_string(self) -> str:
+        """Return the rendered SVG markup."""
+        return self._svg
+
+    def to_json(self) -> dict[str, Any]:
+        """Return ``{"svg", "options"}`` — the SVG and the resolved options."""
+        return {"svg": self._svg, "options": copy.deepcopy(self._resolved_options)}
+
+    def to_data_uri(self) -> str:
+        """Return the SVG encoded as a ``data:image/svg+xml`` URI."""
+        return "data:image/svg+xml;charset=utf-8," + quote(
+            self._svg, safe=_DATA_URI_SAFE
+        )

dicebear/errors.py

@@ -0,0 +1,66 @@
+"""Domain error types raised by the core."""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+
+class ErrorDetail(TypedDict, total=False):
+    """A single schema-validation failure."""
+
+    message: str
+    instancePath: str
+
+
+class ValidationError(RuntimeError):
+    """Base class for schema validation errors.
+
+    Carries the prefix in the exception message and the per-field failures in
+    :attr:`details`.
+    """
+
+    def __init__(self, prefix: str, details: list[ErrorDetail]) -> None:
+        parts: list[str] = []
+
+        for detail in details:
+            segments: list[str] = []
+
+            instance_path = detail.get("instancePath", "")
+            if instance_path != "":
+                segments.append(instance_path)
+
+            message = detail.get("message", "")
+            if message != "":
+                segments.append(message)
+
+            parts.append(" ".join(segments))
+
+        super().__init__(prefix + ": " + ", ".join(parts))
+        self.details = details
+
+
+class OptionsValidationError(ValidationError):
+    """Raised when avatar options fail schema validation."""
+
+    def __init__(self, details: list[ErrorDetail]) -> None:
+        super().__init__("Invalid options", details)
+
+
+class StyleValidationError(ValidationError):
+    """Raised when a style definition fails schema validation."""
+
+    def __init__(self, details: list[ErrorDetail]) -> None:
+        super().__init__("Invalid style definition", details)
+
+
+class CircularColorReferenceError(RuntimeError):
+    """Raised when a color references itself, directly or indirectly.
+
+    The :attr:`chain` field reproduces the resolution path.
+    """
+
+    def __init__(self, chain: list[str]) -> None:
+        path = " → ".join(chain)
+
+        super().__init__(f"Circular color reference: {path}")
+        self.chain = chain

dicebear/options.py

@@ -0,0 +1,138 @@
+"""User-supplied option parsing and normalization."""
+
+from __future__ import annotations
+
+import copy
+from typing import Any, cast
+
+from .validator import OptionsValidator
+
+Numeric = int | float
+Range = dict[str, Numeric]
+
+
+class Options:
+    """Validates raw user options and exposes them through typed accessors.
+
+    Each accessor returns the user's input in a normalized form (always a list
+    for options that accept either a scalar or a list, or ``None`` when the
+    option is not set), so consumers — chiefly :class:`Resolver` — never have to
+    do their own normalization.
+
+    Resolution against the style definition and the PRNG happens in
+    :class:`Resolver`; this class is purely about reading user input.
+    """
+
+    def __init__(self, data: dict[str, Any] | None = None) -> None:
+        data = data if data is not None else {}
+        OptionsValidator.validate(data)
+
+        # Deep-copy so later caller mutations cannot leak into resolution,
+        # mirroring the JS core's structuredClone and Style's deep copy.
+        self._data = copy.deepcopy(data)
+
+    def seed(self) -> str | None:
+        return cast("str | None", self._data.get("seed"))
+
+    def size(self) -> int | None:
+        return cast("int | None", self._data.get("size"))
+
+    def id_randomization(self) -> bool | None:
+        return cast("bool | None", self._data.get("idRandomization"))
+
+    def title(self) -> str | None:
+        return cast("str | None", self._data.get("title"))
+
+    def flip(self) -> list[str]:
+        return self._as_array(self._data.get("flip"))
+
+    def font_family(self) -> list[str]:
+        return self._as_array(self._data.get("fontFamily"))
+
+    def font_weight(self) -> list[Numeric]:
+        return self._as_array(self._data.get("fontWeight"))
+
+    def scale(self) -> Range | None:
+        return self._to_range(self._data.get("scale"))
+
+    def border_radius(self) -> Range | None:
+        return self._to_range(self._data.get("borderRadius"))
+
+    def rotate(self) -> Range | None:
+        return self._to_range(self._data.get("rotate"))
+
+    def translate_x(self) -> Range | None:
+        return self._to_range(self._data.get("translateX"))
+
+    def translate_y(self) -> Range | None:
+        return self._to_range(self._data.get("translateY"))
+
+    def component_variant(self, name: str) -> dict[str, Numeric] | None:
+        """Return the variant constraint for ``name`` as a weighted map, or
+        ``None`` when ``{name}Variant`` is unset.
+
+        A bare string or string list is normalized to a map weighted ``1`` each.
+        """
+        raw = self._data.get(name + "Variant")
+
+        if raw is None:
+            return None
+
+        if isinstance(raw, str):
+            return {raw: 1}
+
+        if isinstance(raw, list):
+            return dict.fromkeys(raw, 1)
+
+        return cast("dict[str, Numeric]", raw)
+
+    def component_probability(self, name: str) -> Numeric | None:
+        return cast("Numeric | None", self._data.get(name + "Probability"))
+
+    def color(self, name: str) -> list[str] | None:
+        """Return ``None`` (not ``[]``) when ``{name}Color`` is unset so the
+        resolver can fall back to the style definition's color values.
+        """
+        raw = self._data.get(name + "Color")
+
+        return None if raw is None else self._as_array(raw)
+
+    def color_fill(self, name: str) -> list[str]:
+        return self._as_array(self._data.get(name + "ColorFill"))
+
+    def color_angle(self, name: str) -> Range | None:
+        return self._to_range(self._data.get(name + "ColorAngle"))
+
+    def color_fill_stops(self, name: str) -> Range | None:
+        return self._to_range(self._data.get(name + "ColorFillStops"))
+
+    @staticmethod
+    def _as_array(value: Any) -> list[Any]:
+        if value is None:
+            return []
+
+        return value if isinstance(value, list) else [value]
+
+    @staticmethod
+    def _to_range(value: Any) -> Range | None:
+        """Normalize a range option (bare number, ``[n]``, ``[min, max]``, or
+        ``None``).
+
+        A bare number ``n`` — or a single-element array ``[n]`` — becomes
+        ``{'min': n, 'max': n}`` (a fixed value). An array's smaller/larger
+        element is taken as min/max. An empty array is treated as unset
+        (``None``), so the resolver applies the option's default.
+        """
+        if value is None:
+            return None
+
+        if isinstance(value, bool):
+            return None
+
+        if isinstance(value, (int, float)):
+            return {"min": value, "max": value}
+
+        if isinstance(value, list) and len(value) > 0:
+            return {"min": min(value), "max": max(value)}
+
+        return None

dicebear/options_descriptor.py

@@ -0,0 +1,90 @@
+"""Builds a descriptor of every option a given style accepts."""
+
+from __future__ import annotations
+
+import copy
+from typing import Any
+
+from .style import Style
+
+_ROTATE_RANGE: dict[str, Any] = {"type": "range", "min": -360, "max": 360}
+_TRANSLATE_RANGE: dict[str, Any] = {"type": "range", "min": -1000, "max": 1000}
+
+
+class OptionsDescriptor:
+    """Builds a descriptor of every option a given style accepts.
+
+    Tooling such as the editor uses the result to render form controls and
+    validation hints without having to introspect the style itself.
+    """
+
+    def __init__(self, style: Style) -> None:
+        self._style = style
+        self._descriptor: dict[str, Any] | None = None
+
+    def to_json(self) -> dict[str, Any]:
+        """Return the descriptor, building it lazily on first call.
+
+        Each call returns an independent deep copy so callers can mutate the
+        result without affecting the cached descriptor.
+        """
+        if self._descriptor is None:
+            self._descriptor = self._build()
+
+        return copy.deepcopy(self._descriptor)
+
+    def _build(self) -> dict[str, Any]:
+        """Walk the style's components and colors and assemble the field map."""
+        result: dict[str, Any] = {
+            "seed": {"type": "string"},
+            "size": {"type": "number", "min": 1, "max": 4096},
+            "idRandomization": {"type": "boolean"},
+            "title": {"type": "string"},
+            "flip": {
+                "type": "enum",
+                "values": ["none", "horizontal", "vertical", "both"],
+                "list": True,
+            },
+            "fontFamily": {"type": "string", "list": True},
+            "fontWeight": {"type": "number", "min": 1, "max": 1000, "list": True},
+            "scale": {"type": "range", "min": 0, "max": 10},
+            "borderRadius": {"type": "range", "min": 0, "max": 50},
+            "rotate": dict(_ROTATE_RANGE),
+            "translateX": dict(_TRANSLATE_RANGE),
+            "translateY": dict(_TRANSLATE_RANGE),
+        }
+
+        for name, component in self._style.components().items():
+            if component.extends_name() is not None:
+                continue
+
+            variants = sorted(component.variants().keys())
+
+            result[f"{name}Variant"] = {
+                "type": "enum",
+                "values": variants,
+                "list": True,
+                "weighted": True,
+            }
+            result[f"{name}Probability"] = {"type": "number", "min": 0, "max": 100}
+
+        colors = self._style.colors()
+        color_names = [*colors.keys(), "background"]
+
+        for name in color_names:
+            color_field: dict[str, Any] = {"type": "color", "list": True}
+            contrast_to = colors[name].contrast_to() if name in colors else None
+
+            if contrast_to is not None:
+                color_field["contrastTo"] = contrast_to
+
+            result[f"{name}Color"] = color_field
+            result[f"{name}ColorFill"] = {
+                "type": "enum",
+                "values": ["solid", "linear", "radial"],
+                "list": True,
+            }
+            result[f"{name}ColorFillStops"] = {"type": "range", "min": 2}
+            result[f"{name}ColorAngle"] = dict(_ROTATE_RANGE)
+
+        return result

dicebear/prng/__init__.py

@@ -0,0 +1,186 @@
+"""Key-based pseudorandom number generator and its primitives."""
+
+from __future__ import annotations
+
+import builtins
+import math
+from collections.abc import Callable, Sequence
+from typing import TypeVar
+
+from ..utils.number import Number
+from .fnv1a import Fnv1a
+from .mulberry32 import Mulberry32
+
+__all__ = ["Fnv1a", "Mulberry32", "Prng"]
+
+T = TypeVar("T")
+
+# The bool() / float() methods below shadow the builtins for the class scope, so
+# signature annotations that need the builtin types reference them via builtins.
+_Float = builtins.float
+_Bool = builtins.bool
+
+Numeric = int | float
+Range = dict[str, Numeric]
+
+
+class Prng:
+    """Key-based pseudorandom number generator.
+
+    Each method takes a key that, combined with the seed, produces a
+    deterministic value. The same seed + key always yields the same result,
+    regardless of call order.
+    """
+
+    def __init__(self, seed: str) -> None:
+        self._seed = seed
+
+    def pick(self, key: str, items: Sequence[T]) -> T | None:
+        """Pick a single item from ``items`` deterministically.
+
+        Returns ``None`` for an empty list. Duplicate values (by string
+        representation) are collapsed before picking so that input order and
+        duplication do not affect the result.
+        """
+        if len(items) == 0:
+            return None
+
+        if len(items) == 1:
+            return items[0]
+
+        unique = _unique_by_code_point(items)
+
+        if len(unique) == 1:
+            return unique[0]
+
+        ordered = sorted(unique, key=_code_point_key)
+        index = math.floor(self.get_value(key) * len(ordered))
+
+        return ordered[index]
+
+    def weighted_pick(self, key: str, weights: dict[str, Numeric]) -> str | None:
+        """Pick a key from ``weights`` proportional to its weight.
+
+        When all weights are zero, falls back to an unweighted :meth:`pick`.
+        Returns ``None`` for an empty map.
+        """
+        if len(weights) == 0:
+            return None
+
+        keys = list(weights.keys())
+
+        if len(keys) == 1:
+            return str(keys[0])
+
+        keys = sorted(keys, key=_code_point_key)
+
+        # Sum in sorted-key order to match JS reduce-over-sorted parity — float
+        # addition is non-associative, so iterating in insertion order would
+        # diverge from JS for fractional weights.
+        total_weight: float = 0.0
+        for k in keys:
+            total_weight += weights[k]
+
+        if total_weight == 0.0:
+            return self.pick(key, [str(k) for k in keys])
+
+        threshold = self.get_value(key) * total_weight
+        cumulative: float = 0
+
+        for k in keys:
+            cumulative += weights[k]
+
+            if threshold < cumulative:
+                return str(k)
+
+        return str(keys[-1])
+
+    def bool(self, key: str, likelihood: _Float = 50) -> _Bool:
+        """Return ``True`` with the given probability (0–100, default 50)."""
+        return self.get_value(key) * 100 < likelihood
+
+    def float(self, key: str, range: Range) -> _Float:
+        """Return a deterministic float in ``range``, rounded to four decimals.
+
+        With ``range['step'] > 0``, the result is drawn uniformly from
+        ``{ min + i*step | 0 <= i <= floor((max - min) / step) }``, so both
+        endpoints of an evenly-divisible range are equally likely. Non-positive
+        or absent step means continuous. ``min``/``max`` are sorted internally,
+        so a reversed pair is tolerated.
+        """
+        low = min(range["min"], range["max"])
+        high = max(range["min"], range["max"])
+        step = range.get("step", 0)
+
+        if step > 0:
+            buckets = math.floor((high - low) / step) + 1
+            i = math.floor(self.get_value(key) * buckets)
+            value = low + i * step
+        else:
+            value = low + self.get_value(key) * (high - low)
+
+        return Number.round_half_up(value * 10000) / 10000
+
+    def integer(self, key: str, range: Range) -> int:
+        """Return a deterministic integer in ``range``.
+
+        ``min``/``max`` are sorted internally, so a reversed pair is tolerated.
+        ``range['step']`` is accepted for symmetry with :meth:`float` but ignored.
+        """
+        low = int(min(range["min"], range["max"]))
+        high = int(max(range["min"], range["max"]))
+
+        return math.floor(self.get_value(key) * (high - low + 1)) + low
+
+    def shuffle(self, key: str, items: Sequence[T]) -> list[T]:
+        """Fisher-Yates shuffle with chained Mulberry32 state.
+
+        Duplicate values (by string representation) are collapsed before
+        shuffling, so a caller's slice off the front cannot accidentally produce
+        a repeated value.
+        """
+        if len(items) <= 1:
+            return list(items)
+
+        result = sorted(_unique_by_code_point(items), key=_code_point_key)
+        prng = Mulberry32(Fnv1a.hash(self._seed + ":" + key))
+
+        for i in range(len(result) - 1, 0, -1):
+            j = math.floor(prng.next_float() * (i + 1))
+            result[i], result[j] = result[j], result[i]
+
+        return result
+
+    def get_value(self, key: str) -> _Float:
+        """Return a single float in ``[0, 1)`` derived from ``seed:key``.
+
+        The same seed/key pair always produces the same value.
+        """
+        return Mulberry32(Fnv1a.hash(self._seed + ":" + key)).next_float()
+
+
+def _code_point_key(value: object) -> str:
+    """Cross-language deterministic sort key.
+
+    Compare by the string representation's code points, matching JS
+    ``String(a) < String(b)`` and PHP ``strcmp`` for the ASCII values sorted in
+    practice (variant names, hex colors).
+    """
+    return str(value)
+
+
+def _unique_by_code_point(
+    items: Sequence[T], key_fn: Callable[[T], str] = str
+) -> list[T]:
+    """Deduplicate by string representation, keeping the first occurrence."""
+    seen: set[str] = set()
+    result: list[T] = []
+
+    for item in items:
+        repr_ = key_fn(item)
+
+        if repr_ not in seen:
+            seen.add(repr_)
+            result.append(item)
+
+    return result

dicebear/prng/fnv1a.py

@@ -0,0 +1,47 @@
+"""FNV-1a 32-bit hash."""
+
+from __future__ import annotations
+
+import struct
+
+
+class Fnv1a:
+    """FNV-1a 32-bit hash.
+
+    Offset basis: ``0x811c9dc5``, prime: ``0x01000193``.
+
+    See https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function
+    """
+
+    @staticmethod
+    def hash(value: str) -> int:
+        """Return the unsigned 32-bit FNV-1a hash of ``value``.
+
+        The input is decomposed into UTF-16 code units before hashing so the
+        result is identical across language ports.
+        """
+        result = 0x811C9DC5
+
+        for code in _utf16_code_units(value):
+            result = ((result ^ code) * 0x01000193) & 0xFFFFFFFF
+
+        return result
+
+    @staticmethod
+    def hex(value: str) -> str:
+        """Return the FNV-1a hash of ``value`` as an 8-char lowercase hex string."""
+        return format(Fnv1a.hash(value), "08x")
+
+
+def _utf16_code_units(value: str) -> list[int]:
+    """Convert a string to its UTF-16 code units, matching JS ``charCodeAt``.
+
+    Iterating ``value`` directly would yield code points and break on non-BMP
+    input (e.g. emoji), so encode to little-endian UTF-16 and read uint16 units.
+    """
+    if value == "":
+        return []
+
+    encoded = value.encode("utf-16-le")
+
+    return list(struct.unpack(f"<{len(encoded) // 2}H", encoded))

dicebear/prng/mulberry32.py

@@ -0,0 +1,57 @@
+"""Mulberry32 PRNG."""
+
+from __future__ import annotations
+
+_UINT32_MAX_PLUS_1 = 2**32
+
+
+class Mulberry32:
+    """Mulberry32 PRNG — stateful, matching the C reference by Tommy Ettinger.
+
+    C original::
+
+        uint32_t z = (x += 0x6D2B79F5UL);
+        z = (z ^ (z >> 15)) * (z | 1UL);
+        z ^= z + (z ^ (z >> 7)) * (z | 61UL);
+        return z ^ (z >> 14);
+
+    All arithmetic is unsigned 32-bit. Python ints are arbitrary precision, so
+    every operation is masked with ``& 0xFFFFFFFF`` to emulate JS ``Math.imul``
+    / ``>>>`` and keep parity with the JS reference.
+
+    See https://gist.github.com/tommyettinger/46a874533244883189143505d203312c
+    """
+
+    def __init__(self, seed: int = 0) -> None:
+        self._state = seed & 0xFFFFFFFF
+
+    def next(self) -> int:
+        """Advance the state and return the next unsigned 32-bit value."""
+        z = (self._state + 0x6D2B79F5) & 0xFFFFFFFF
+        self._state = z
+
+        z = _mul(z ^ (z >> 15), z | 1)
+        z ^= _add(z, _mul(z ^ (z >> 7), z | 61))
+
+        return (z ^ (z >> 14)) & 0xFFFFFFFF
+
+    def next_float(self) -> float:
+        """Advance the state and return the next value in ``[0, 1)``."""
+        return self.next() / _UINT32_MAX_PLUS_1
+
+    def state(self) -> int:
+        """Return the current state as a signed 32-bit value (for JS compat)."""
+        if self._state >= 0x80000000:
+            return self._state - _UINT32_MAX_PLUS_1
+
+        return self._state
+
+
+def _mul(a: int, b: int) -> int:
+    """Unsigned 32-bit multiply (low 32 bits), matching JS ``Math.imul``."""
+    return (a * b) & 0xFFFFFFFF
+
+
+def _add(a: int, b: int) -> int:
+    """Unsigned 32-bit add."""
+    return (a + b) & 0xFFFFFFFF