dicebear-core 10.1.0__tar.gz

dicebear_core-10.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv
+dist
+dist-build
+*.egg-info
+__pycache__
+.pytest_cache
+.mypy_cache
+.ruff_cache

dicebear_core-10.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Florian Körner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dicebear_core-10.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: dicebear-core
+Version: 10.1.0
+Summary: Unique avatars from dozens of styles — deterministic, customizable, vector-based.
+Project-URL: Homepage, https://www.dicebear.com
+Project-URL: Repository, https://github.com/dicebear/dicebear
+Project-URL: Issues, https://github.com/dicebear/dicebear/issues
+Author-email: Florian Körner <contact@florian-koerner.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: avatar,dicebear,svg
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.10
+Requires-Dist: dicebear-schema>=1.1.0
+Requires-Dist: jsonschema>=4.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# DiceBear Core (Python)
+
+Deterministic, customizable, vector-based avatars — the Python port of the
+DiceBear core engine. It produces **byte-identical** SVG output to the
+JavaScript (`@dicebear/core`) and PHP (`dicebear/core`) implementations for the
+same style definition and options.
+
+This package contains only the rendering engine. Avatar **style definitions**
+ship separately as language-agnostic JSON via
+[`dicebear-styles`](https://pypi.org/project/dicebear-styles/) (or any other
+source of a DiceBear style definition).
+
+## Installation
+
+```bash
+pip install dicebear-core
+```
+
+Requires Python 3.10 or newer.
+
+## Usage
+
+```python
+import json
+from importlib.resources import files
+
+from dicebear import Avatar
+
+# Load a style definition (here from the dicebear-styles package).
+style = json.loads(
+    files("dicebear_styles").joinpath("adventurer.json").read_text("utf-8")
+)
+
+avatar = Avatar(style, {"seed": "John"})
+
+avatar.to_string()    # the SVG markup
+avatar.to_data_uri()  # data:image/svg+xml;charset=utf-8,...
+avatar.to_json()      # {"svg": ..., "options": {...resolved options...}}
+```
+
+`Avatar` accepts either a raw style-definition dict or a `Style` instance, plus
+an optional options dict:
+
+```python
+from dicebear import Avatar, Style
+
+style = Style(style_data)
+Avatar(style, {"seed": "John", "size": 128, "backgroundColor": ["b6e3f4"]})
+```
+
+## Development
+
+This package lives in the
+[DiceBear monorepo](https://github.com/dicebear/dicebear) under
+`src/python/core`. See `CONTRIBUTING.md` in the repository root for the full
+workflow.
+
+```bash
+cd src/python/core
+pip install -e ".[dev]"
+ruff check .
+mypy src
+pytest
+```
+
+The decisive check is `tests/test_parity.py`, which asserts byte-identical
+output against the shared fixtures in `tests/fixtures/parity/` (generated from
+the JavaScript reference).
+
+## License
+
+[MIT](https://github.com/dicebear/dicebear/blob/10.x/src/python/core/LICENSE)

dicebear_core-10.1.0/README.md

@@ -0,0 +1,72 @@
+# DiceBear Core (Python)
+
+Deterministic, customizable, vector-based avatars — the Python port of the
+DiceBear core engine. It produces **byte-identical** SVG output to the
+JavaScript (`@dicebear/core`) and PHP (`dicebear/core`) implementations for the
+same style definition and options.
+
+This package contains only the rendering engine. Avatar **style definitions**
+ship separately as language-agnostic JSON via
+[`dicebear-styles`](https://pypi.org/project/dicebear-styles/) (or any other
+source of a DiceBear style definition).
+
+## Installation
+
+```bash
+pip install dicebear-core
+```
+
+Requires Python 3.10 or newer.
+
+## Usage
+
+```python
+import json
+from importlib.resources import files
+
+from dicebear import Avatar
+
+# Load a style definition (here from the dicebear-styles package).
+style = json.loads(
+    files("dicebear_styles").joinpath("adventurer.json").read_text("utf-8")
+)
+
+avatar = Avatar(style, {"seed": "John"})
+
+avatar.to_string()    # the SVG markup
+avatar.to_data_uri()  # data:image/svg+xml;charset=utf-8,...
+avatar.to_json()      # {"svg": ..., "options": {...resolved options...}}
+```
+
+`Avatar` accepts either a raw style-definition dict or a `Style` instance, plus
+an optional options dict:
+
+```python
+from dicebear import Avatar, Style
+
+style = Style(style_data)
+Avatar(style, {"seed": "John", "size": 128, "backgroundColor": ["b6e3f4"]})
+```
+
+## Development
+
+This package lives in the
+[DiceBear monorepo](https://github.com/dicebear/dicebear) under
+`src/python/core`. See `CONTRIBUTING.md` in the repository root for the full
+workflow.
+
+```bash
+cd src/python/core
+pip install -e ".[dev]"
+ruff check .
+mypy src
+pytest
+```
+
+The decisive check is `tests/test_parity.py`, which asserts byte-identical
+output against the shared fixtures in `tests/fixtures/parity/` (generated from
+the JavaScript reference).
+
+## License
+
+[MIT](https://github.com/dicebear/dicebear/blob/10.x/src/python/core/LICENSE)

dicebear_core-10.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+# hatchling >= 1.27 is required for the PEP 639 `license = "MIT"` SPDX string.
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dicebear-core"
+version = "10.1.0"
+description = "Unique avatars from dozens of styles — deterministic, customizable, vector-based."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Florian Körner", email = "contact@florian-koerner.com" }]
+keywords = ["dicebear", "avatar", "svg"]
+classifiers = [
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Multimedia :: Graphics",
+]
+dependencies = ["jsonschema>=4.0", "dicebear-schema>=1.1.0"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "mypy>=1.8", "ruff>=0.6"]
+
+[project.urls]
+Homepage = "https://www.dicebear.com"
+Repository = "https://github.com/dicebear/dicebear"
+Issues = "https://github.com/dicebear/dicebear/issues"
+
+# The package lives under src/dicebear. The JSON Schemas are not vendored: they
+# come from the `dicebear-schema` dependency and are read at runtime via
+# importlib.resources (files("dicebear_schema")), mirroring how the JS/PHP ports
+# pin @dicebear/schema / dicebear/schema.
+[tool.hatch.build.targets.wheel]
+packages = ["src/dicebear"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/dicebear", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src"]
+
+# jsonschema ships no type stubs; the validator wraps it behind a typed boundary.
+[[tool.mypy.overrides]]
+module = ["jsonschema", "jsonschema.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

dicebear_core-10.1.0/src/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_core-10.1.0/src/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_core-10.1.0/src/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_core-10.1.0/src/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_core-10.1.0/src/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