pyobjtojson 0.8__tar.gz → 0.9.1__tar.gz

{pyobjtojson-0.8 → pyobjtojson-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyobjtojson
-Version: 0.8
+Version: 0.9.1
 Summary: A Python library that simplifies serializing any Python object to JSON-friendly structures, gracefully handling circular references.
 Author-email: "Carlos A. Planchón" <carlosandresplanchonprestes@gmail.com>
 License-Expression: MIT
@@ -8,9 +8,12 @@ Project-URL: Repository, https://github.com/carlosplanchon/pyobjtojson.git
 Keywords: json,serialization,circular references,pydantic,dataclasses
 Classifier: Intended Audience :: Developers
 Classifier: Topic :: Software Development :: Libraries
+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
-Requires-Python: >=3.13
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Provides-Extra: dev
@@ -34,12 +37,14 @@ A lightweight Python library that simplifies the process of serializing **any**
   Works seamlessly with dictionaries, lists, custom classes, dataclasses, and Pydantic models (including both `model_dump()` from v2 and `dict()` from v1).
 - **Extended Standard Types Support**
   Native support for `datetime`, `date`, `time`, `UUID`, `Decimal`, `bytes`, `Enum`, `Path`, `set`, and `frozenset`.
+- **JSON-Safe Dictionary Keys**
+  Non-string keys (`UUID`, `datetime`, `Enum`, tuples, and other objects) are converted so the returned structure always survives `json.dumps`.
 - **Full Type Hints Support**
   Complete type annotations for better IDE autocomplete, type checking with mypy, and improved code documentation.
 - **Non-Intrusive Serialization**
   No special inheritance or overrides needed. Uses reflection and standard Python methods (`__dict__`, `asdict()`, `to_dict()`, etc.) where available.
 - **Easy to Integrate**
-  Just call `obj_to_json()` on your data structure—no additional configuration required.
+  Just call `obj_to_json()` on your data structure. No additional configuration required.
 
 ### DeepWiki Docs: [https://deepwiki.com/carlosplanchon/pyobjtojson](https://deepwiki.com/carlosplanchon/pyobjtojson)
 
@@ -63,7 +68,12 @@ data = {
     "nested": {"inner_key": "inner_value"}
 }
 
-json_obj = obj_to_json(data)  # Using json.dumps kwargs
+# obj_to_json returns a JSON-serializable structure (nested dicts, lists and
+# primitives), not a JSON string. Pass it to json.dumps() when you need text:
+json_obj = obj_to_json(data)
+
+import json
+json_text = json.dumps(json_obj)
 ```
 
 **Output** (example):
@@ -201,9 +211,47 @@ obj_to_json(data)
 - **Path** → string representation
 - **set, frozenset** → sorted lists
 
+### 5. Dictionary Keys
+
+JSON object keys must be strings, so **pyobjtojson** normalizes non-string keys
+to keep the result compatible with `json.dumps`:
+
+- `str`, `int`, `float`, `bool`, and `None` keys are kept as-is (`json.dumps`
+  already coerces the non-string primitives to strings itself).
+- Typed keys such as `UUID`, `datetime`, `Enum`, `Decimal`, and `Path` are
+  converted to their natural scalar form (e.g. `UUID` → string, `datetime` →
+  ISO string), respecting `decimal_as_float`.
+- Any remaining composite key (a tuple, `frozenset`, or custom object) is
+  stringified as a last resort.
+
+```python
+from uuid import UUID
+from pyobjtojson import obj_to_json
+
+data = {
+    UUID("12345678-1234-5678-1234-567812345678"): "by uuid",
+    (1, 2): "by tuple",
+    42: "by int",
+}
+
+obj_to_json(data)
+```
+
+**Output**:
+```json
+{
+  "12345678-1234-5678-1234-567812345678": "by uuid",
+  "[1, 2]": "by tuple",
+  "42": "by int"
+}
+```
+
+> **Note:** If two distinct keys normalize to the same string, the last one
+> wins. This mirrors how JSON itself collapses duplicate keys.
+
 ## API Reference
 
-### `obj_to_json(obj, check_circular=True, decimal_as_float=True)`
+### `obj_to_json(obj, check_circular=True, decimal_as_float=True, non_finite="null")`
 
 Returns a cycle-free structure (nested dictionaries/lists) that is JSON-serializable.
 
@@ -211,10 +259,33 @@ Returns a cycle-free structure (nested dictionaries/lists) that is JSON-serializ
 - `obj` (Any): The object to serialize to JSON-like structures.
 - `check_circular` (bool, optional): If True (default), detect and mark circular references as `"<circular reference>"`.
 - `decimal_as_float` (bool, optional): If True (default), convert `Decimal` to `float`. If False, convert to string for high precision.
+- `non_finite` (str, optional): How to represent non-finite floats (`inf`, `-inf`, `nan`), which have no JSON literal. One of:
+  - `"null"` (default): convert to `None`, matching JavaScript's `JSON.stringify`.
+  - `"string"`: convert to `"Infinity"`, `"-Infinity"`, or `"NaN"`.
+  - `"keep"`: leave the float as-is. Note this is **not** valid JSON and will raise with `json.dumps(..., allow_nan=False)`.
+
+  An unknown value raises `ValueError`.
 
 **Returns:**
 - `dict | list | Any`: A JSON-serializable structure.
 
+#### Non-finite floats
+
+`inf`, `-inf`, and `nan` are valid Python floats but have no representation in
+the JSON spec. Left untouched they break `json.dumps(..., allow_nan=False)` and
+produce the non-standard `Infinity`/`NaN` tokens that strict parsers reject. By
+default **pyobjtojson** converts them to `null` so the output is always valid,
+portable JSON:
+
+```python
+from pyobjtojson import obj_to_json
+
+data = {"ratio": float("inf"), "value": float("nan"), "ok": 1.5}
+
+obj_to_json(data)                      # {"ratio": None, "value": None, "ok": 1.5}
+obj_to_json(data, non_finite="string") # {"ratio": "Infinity", "value": "NaN", "ok": 1.5}
+```
+
 ## Type Hints
 
 **pyobjtojson** is fully typed and passes strict mypy checking. This provides:

{pyobjtojson-0.8 → pyobjtojson-0.9.1}/README.md

@@ -12,12 +12,14 @@ A lightweight Python library that simplifies the process of serializing **any**
   Works seamlessly with dictionaries, lists, custom classes, dataclasses, and Pydantic models (including both `model_dump()` from v2 and `dict()` from v1).
 - **Extended Standard Types Support**
   Native support for `datetime`, `date`, `time`, `UUID`, `Decimal`, `bytes`, `Enum`, `Path`, `set`, and `frozenset`.
+- **JSON-Safe Dictionary Keys**
+  Non-string keys (`UUID`, `datetime`, `Enum`, tuples, and other objects) are converted so the returned structure always survives `json.dumps`.
 - **Full Type Hints Support**
   Complete type annotations for better IDE autocomplete, type checking with mypy, and improved code documentation.
 - **Non-Intrusive Serialization**
   No special inheritance or overrides needed. Uses reflection and standard Python methods (`__dict__`, `asdict()`, `to_dict()`, etc.) where available.
 - **Easy to Integrate**
-  Just call `obj_to_json()` on your data structure—no additional configuration required.
+  Just call `obj_to_json()` on your data structure. No additional configuration required.
 
 ### DeepWiki Docs: [https://deepwiki.com/carlosplanchon/pyobjtojson](https://deepwiki.com/carlosplanchon/pyobjtojson)
 
@@ -41,7 +43,12 @@ data = {
     "nested": {"inner_key": "inner_value"}
 }
 
-json_obj = obj_to_json(data)  # Using json.dumps kwargs
+# obj_to_json returns a JSON-serializable structure (nested dicts, lists and
+# primitives), not a JSON string. Pass it to json.dumps() when you need text:
+json_obj = obj_to_json(data)
+
+import json
+json_text = json.dumps(json_obj)
 ```
 
 **Output** (example):
@@ -179,9 +186,47 @@ obj_to_json(data)
 - **Path** → string representation
 - **set, frozenset** → sorted lists
 
+### 5. Dictionary Keys
+
+JSON object keys must be strings, so **pyobjtojson** normalizes non-string keys
+to keep the result compatible with `json.dumps`:
+
+- `str`, `int`, `float`, `bool`, and `None` keys are kept as-is (`json.dumps`
+  already coerces the non-string primitives to strings itself).
+- Typed keys such as `UUID`, `datetime`, `Enum`, `Decimal`, and `Path` are
+  converted to their natural scalar form (e.g. `UUID` → string, `datetime` →
+  ISO string), respecting `decimal_as_float`.
+- Any remaining composite key (a tuple, `frozenset`, or custom object) is
+  stringified as a last resort.
+
+```python
+from uuid import UUID
+from pyobjtojson import obj_to_json
+
+data = {
+    UUID("12345678-1234-5678-1234-567812345678"): "by uuid",
+    (1, 2): "by tuple",
+    42: "by int",
+}
+
+obj_to_json(data)
+```
+
+**Output**:
+```json
+{
+  "12345678-1234-5678-1234-567812345678": "by uuid",
+  "[1, 2]": "by tuple",
+  "42": "by int"
+}
+```
+
+> **Note:** If two distinct keys normalize to the same string, the last one
+> wins. This mirrors how JSON itself collapses duplicate keys.
+
 ## API Reference
 
-### `obj_to_json(obj, check_circular=True, decimal_as_float=True)`
+### `obj_to_json(obj, check_circular=True, decimal_as_float=True, non_finite="null")`
 
 Returns a cycle-free structure (nested dictionaries/lists) that is JSON-serializable.
 
@@ -189,10 +234,33 @@ Returns a cycle-free structure (nested dictionaries/lists) that is JSON-serializ
 - `obj` (Any): The object to serialize to JSON-like structures.
 - `check_circular` (bool, optional): If True (default), detect and mark circular references as `"<circular reference>"`.
 - `decimal_as_float` (bool, optional): If True (default), convert `Decimal` to `float`. If False, convert to string for high precision.
+- `non_finite` (str, optional): How to represent non-finite floats (`inf`, `-inf`, `nan`), which have no JSON literal. One of:
+  - `"null"` (default): convert to `None`, matching JavaScript's `JSON.stringify`.
+  - `"string"`: convert to `"Infinity"`, `"-Infinity"`, or `"NaN"`.
+  - `"keep"`: leave the float as-is. Note this is **not** valid JSON and will raise with `json.dumps(..., allow_nan=False)`.
+
+  An unknown value raises `ValueError`.
 
 **Returns:**
 - `dict | list | Any`: A JSON-serializable structure.
 
+#### Non-finite floats
+
+`inf`, `-inf`, and `nan` are valid Python floats but have no representation in
+the JSON spec. Left untouched they break `json.dumps(..., allow_nan=False)` and
+produce the non-standard `Infinity`/`NaN` tokens that strict parsers reject. By
+default **pyobjtojson** converts them to `null` so the output is always valid,
+portable JSON:
+
+```python
+from pyobjtojson import obj_to_json
+
+data = {"ratio": float("inf"), "value": float("nan"), "ok": 1.5}
+
+obj_to_json(data)                      # {"ratio": None, "value": None, "ok": 1.5}
+obj_to_json(data, non_finite="string") # {"ratio": "Infinity", "value": "NaN", "ok": 1.5}
+```
+
 ## Type Hints
 
 **pyobjtojson** is fully typed and passes strict mypy checking. This provides:

pyobjtojson-0.9.1/pyobjtojson/__init__.py

@@ -0,0 +1,384 @@
+#!/usr/bin/env python3
+
+import base64
+import dataclasses
+import math
+from collections.abc import Mapping, Sequence
+from datetime import datetime, date, time
+from decimal import Decimal
+from enum import Enum
+from pathlib import Path
+from typing import Any
+from uuid import UUID
+
+
+# Allowed policies for representing non-finite floats (inf/-inf/nan).
+_NON_FINITE_MODES = ("null", "string", "keep")
+
+
+def _non_finite_repr(value: float, non_finite: str) -> Any:
+    """
+    Represent a non-finite float (``inf``, ``-inf`` or ``nan``) according to
+    the chosen policy. JSON has no literal for these values, so leaving them
+    as-is yields output that either breaks ``json.dumps(..., allow_nan=False)``
+    or produces the non-standard ``Infinity``/``NaN`` tokens that strict
+    parsers reject.
+
+    - ``"null"``: return ``None`` (matches JavaScript's ``JSON.stringify``).
+    - ``"string"``: return ``"Infinity"``, ``"-Infinity"`` or ``"NaN"``.
+    - ``"keep"``: return the float unchanged (legacy behavior).
+
+    :param value: A non-finite float.
+    :param non_finite: One of the policies above.
+    :return: The chosen JSON-compatible representation.
+    """
+    if non_finite == "null":
+        return None
+    if non_finite == "string":
+        if value != value:  # NaN is the only value not equal to itself
+            return "NaN"
+        return "Infinity" if value > 0 else "-Infinity"
+    return value  # "keep"
+
+
+def _serialize_for_json(
+    obj: Any,
+    visited: set[int],
+    check_circular: bool = True,
+    _skip_circular_check: bool = False,
+    decimal_as_float: bool = True,
+    non_finite: str = "null"
+) -> Any:
+    """
+    Internal recursion logic that can handle circular references
+    using `visited`. This includes careful exception handling so
+    partial failures don't break the entire serialization.
+
+    :param obj: The object to serialize.
+    :param visited: A set used to track visited objects (for cycle detection).
+    :param check_circular: Whether to check for and mark circular references.
+    :param _skip_circular_check: Internal flag to skip adding intermediate
+                                   conversion results to visited set.
+    :param decimal_as_float: If True, convert Decimal to float; otherwise to string.
+    :param non_finite: How to represent non-finite floats (inf/-inf/nan):
+                       "null", "string", or "keep".
+    :return: A JSON-serializable structure, or a string if it cannot be
+             converted more structurally.
+    """
+
+    # Enum → underlying value. This must run before the primitive fast-path
+    # below: IntEnum/StrEnum members are also int/str instances, so the
+    # fast-path would otherwise return the enum member itself instead of its
+    # documented `.value`.
+    if isinstance(obj, Enum):
+        return obj.value
+
+    # Non-finite floats (inf, -inf, nan) have no JSON representation. Route
+    # them through the chosen policy before the primitive fast-path returns
+    # them verbatim. bool/int are always finite, so only float needs this.
+    if isinstance(obj, float) and not math.isfinite(obj):
+        return _non_finite_repr(obj, non_finite)
+
+    # If it's None, bool, int, float, or str, it's already JSON-serializable.
+    if obj is None or isinstance(obj, (bool, int, float, str)):
+        return obj
+
+    # === Standard Python types support ===
+
+    # datetime, date, time → ISO format
+    if isinstance(obj, datetime):
+        return obj.isoformat()
+    if isinstance(obj, date):
+        return obj.isoformat()
+    if isinstance(obj, time):
+        return obj.isoformat()
+
+    # UUID → string
+    if isinstance(obj, UUID):
+        return str(obj)
+
+    # Decimal → float or string
+    if isinstance(obj, Decimal):
+        if decimal_as_float:
+            # A Decimal can also be non-finite (Decimal("inf")/Decimal("nan")),
+            # so apply the same policy once converted to float.
+            as_float = float(obj)
+            if not math.isfinite(as_float):
+                return _non_finite_repr(as_float, non_finite)
+            return as_float
+        return str(obj)
+
+    # bytes, bytearray → base64
+    if isinstance(obj, (bytes, bytearray)):
+        return base64.b64encode(bytes(obj)).decode('utf-8')
+
+    # Path → string
+    if isinstance(obj, Path):
+        return str(obj)
+
+    # set, frozenset → list
+    if isinstance(obj, (set, frozenset)):
+        try:
+            # Try to sort if elements are comparable
+            return sorted(list(obj))
+        except TypeError:
+            # If not sortable, convert to list without sorting
+            return list(obj)
+
+    obj_id = id(obj)
+
+    # If circular checking is enabled, see if this object is already on the
+    # current traversal path. We track whether *this* frame added the id so we
+    # can remove it again on the way out (see the `finally` below). Keeping
+    # `visited` as the active path (not every object ever seen) is what makes
+    # this real cycle detection: a shared sub-object referenced from two
+    # sibling branches (a DAG, not a cycle) must not be flagged circular.
+    added_to_visited = False
+    if check_circular is True and not _skip_circular_check:
+        if obj_id in visited:
+            return "<circular reference>"
+        visited.add(obj_id)
+        added_to_visited = True
+
+    try:
+        # Handle Mapping (like dict). Build a new dict item by item,
+        # catching errors.
+        if isinstance(obj, Mapping):
+            result_dict: dict[Any, Any] = {}
+            for key, value in obj.items():
+                # Keys must also be JSON-compatible, otherwise json.dumps would
+                # reject the returned structure even though the values are fine.
+                json_key = _serialize_key(
+                    key, visited, check_circular=check_circular,
+                    decimal_as_float=decimal_as_float, non_finite=non_finite
+                )
+                try:
+                    result_dict[json_key] = _serialize_for_json(
+                        value, visited, check_circular=check_circular,
+                        decimal_as_float=decimal_as_float, non_finite=non_finite
+                    )
+                except Exception as exc:
+                    result_dict[json_key] = f"<serialization error: {exc}>"
+            return result_dict
+
+        # Handle Sequence (like list/tuple), but not string.
+        if isinstance(obj, Sequence) and not isinstance(obj, str):
+            result_list: list[Any] = []
+            for index, item in enumerate(obj):
+                try:
+                    result_list.append(
+                        _serialize_for_json(
+                            obj=item,
+                            visited=visited,
+                            check_circular=check_circular,
+                            decimal_as_float=decimal_as_float,
+                            non_finite=non_finite
+                        )
+                    )
+                except Exception as exc:
+                    result_list.append(f"<serialization error at index {index}: {exc}>")
+            return result_list
+
+        # Try Pydantic v2 model_dump(), but fall back if it fails
+        if hasattr(obj, "model_dump") and callable(obj.model_dump):
+            try:
+                model_data = obj.model_dump()
+                # Skip re-adding the intermediate dict to `visited`; this object
+                # is already on the path, so its converted form must not be
+                # treated as a separate node.
+                return _serialize_for_json(
+                    obj=model_data,
+                    visited=visited,
+                    check_circular=check_circular,
+                    _skip_circular_check=True,
+                    decimal_as_float=decimal_as_float,
+                    non_finite=non_finite
+                )
+            except Exception:
+                # Fall through to next check if this fails
+                ...
+
+        # Try Pydantic v1 .dict(), but fall back if it fails
+        if hasattr(obj, "dict") and callable(obj.dict):
+            try:
+                dict_data = obj.dict()
+                # Skip circular check for the intermediate dict
+                return _serialize_for_json(
+                    obj=dict_data,
+                    visited=visited,
+                    check_circular=check_circular,
+                    _skip_circular_check=True,
+                    decimal_as_float=decimal_as_float,
+                    non_finite=non_finite
+                )
+            except Exception:
+                # Fall through to next check if this fails
+                ...
+
+        # If it's a dataclass, convert it using asdict(), but handle exceptions
+        if dataclasses.is_dataclass(obj):
+            try:
+                # is_dataclass can return True for both instances and types,
+                # but we only process instances here
+                dc_data = dataclasses.asdict(obj)  # type: ignore[arg-type]
+                # Skip circular check for the intermediate dict
+                return _serialize_for_json(
+                    obj=dc_data,
+                    visited=visited,
+                    check_circular=check_circular,
+                    _skip_circular_check=True,
+                    decimal_as_float=decimal_as_float,
+                    non_finite=non_finite
+                )
+            except Exception:
+                # Fall through to next check if this fails
+                ...
+
+        # If there's a custom .to_dict() method, try that
+        if hasattr(obj, "to_dict") and callable(obj.to_dict):
+            try:
+                custom_dict_data = obj.to_dict()
+                # Skip circular check for the intermediate dict
+                return _serialize_for_json(
+                    obj=custom_dict_data,
+                    visited=visited,
+                    check_circular=check_circular,
+                    _skip_circular_check=True,
+                    decimal_as_float=decimal_as_float,
+                    non_finite=non_finite
+                )
+            except Exception:
+                # Fall through to next check if this fails
+                ...
+
+        # If the object has a __dict__, recurse into that
+        if hasattr(obj, "__dict__"):
+            try:
+                # Skip circular check for the __dict__ to avoid false positives
+                return _serialize_for_json(
+                    obj=obj.__dict__,
+                    visited=visited,
+                    check_circular=check_circular,
+                    _skip_circular_check=True,
+                    decimal_as_float=decimal_as_float,
+                    non_finite=non_finite
+                )
+            except Exception:
+                # Fall through to next check if this fails
+                pass
+
+        # Last resort: convert to string, but even this can fail
+        # if __str__ is broken
+        try:
+            return str(obj)
+        except Exception as exc:
+            # If that fails, return a generic serialization error.
+            return f"<serialization error: {exc}>"
+    finally:
+        # Leave the traversal path: this object is no longer an ancestor of
+        # whatever we serialize next, so remove it to allow legitimate reuse
+        # of the same instance elsewhere in the tree.
+        if added_to_visited:
+            visited.discard(obj_id)
+
+
+def _serialize_key(
+    key: Any,
+    visited: set[int],
+    check_circular: bool = True,
+    decimal_as_float: bool = True,
+    non_finite: str = "null"
+) -> Any:
+    """
+    Convert a mapping key into something ``json.dumps`` accepts as an object
+    key: ``str``, ``int``, ``float``, ``bool`` or ``None``.
+
+    ``json.dumps`` already coerces int/float/bool/None keys to strings itself,
+    so those (and plain strings) pass through unchanged. Any other key is run
+    through the normal value serializer so that common non-string keys become
+    their natural scalar form (``UUID`` → str, ``datetime`` → ISO string,
+    ``Enum`` → its value, ``Decimal`` → float/str). If the result is still a
+    composite (e.g. a tuple serialized to a list), it is stringified as a last
+    resort so the returned structure always survives ``json.dumps``.
+
+    :param key: The mapping key to serialize.
+    :param visited: The traversal-path set shared with the value serializer.
+    :param check_circular: Whether cycle detection is enabled.
+    :param decimal_as_float: If True, convert Decimal to float; otherwise string.
+    :param non_finite: Policy for non-finite float keys (see _serialize_for_json).
+    :return: A ``json.dumps``-compatible key.
+    """
+    # json.dumps natively accepts these as object keys, so leave them as-is to
+    # preserve its default behavior (e.g. int key 1 -> "1"). A non-finite float
+    # key is the one exception: it must follow the non_finite policy.
+    if isinstance(key, float) and not math.isfinite(key):
+        return _non_finite_repr(key, non_finite)
+    if key is None or isinstance(key, (str, bool, int, float)):
+        return key
+
+    # Reuse the value machinery so typed keys become their natural scalar form.
+    try:
+        serialized = _serialize_for_json(
+            obj=key,
+            visited=visited,
+            check_circular=check_circular,
+            decimal_as_float=decimal_as_float,
+            non_finite=non_finite
+        )
+    except Exception as exc:
+        return f"<unserializable key: {exc}>"
+
+    if serialized is None or isinstance(serialized, (str, bool, int, float)):
+        return serialized
+
+    # Composite results (lists/dicts from e.g. a tuple or a custom object)
+    # can't be object keys; fall back to a string form.
+    try:
+        return str(serialized)
+    except Exception as exc:
+        return f"<unserializable key: {exc}>"
+
+
+def obj_to_json(
+    obj: Any,
+    check_circular: bool = True,
+    decimal_as_float: bool = True,
+    non_finite: str = "null"
+) -> Any:
+    """
+    Public-facing function that starts with a fresh visited set
+    to handle cycles (if `check_circular=True`). Calls the internal
+    _serialize_for_json.
+
+    Supports standard Python types including:
+    - datetime, date, time (converted to ISO format)
+    - UUID (converted to string)
+    - Decimal (converted to float or string based on decimal_as_float)
+    - bytes, bytearray (converted to base64)
+    - Enum (converted to underlying value)
+    - Path (converted to string)
+    - set, frozenset (converted to sorted list)
+
+    :param obj: The object to serialize to JSON-like structures.
+    :param check_circular: If True, detect and mark circular references.
+    :param decimal_as_float: If True, convert Decimal to float; otherwise to string.
+                             Default is True.
+    :param non_finite: How to represent non-finite floats (inf/-inf/nan), which
+                       have no JSON literal. One of:
+                       - "null" (default): convert to None, matching JavaScript.
+                       - "string": convert to "Infinity"/"-Infinity"/"NaN".
+                       - "keep": leave the float as-is (not valid JSON).
+    :return: A JSON-serializable structure (dict, list, str, int, float, bool, None).
+    """
+    if non_finite not in _NON_FINITE_MODES:
+        raise ValueError(
+            f"non_finite must be one of {_NON_FINITE_MODES}, got {non_finite!r}"
+        )
+    visited: set[int] = set()
+    return _serialize_for_json(
+        obj=obj,
+        visited=visited,
+        check_circular=check_circular,
+        decimal_as_float=decimal_as_float,
+        non_finite=non_finite
+    )

{pyobjtojson-0.8 → pyobjtojson-0.9.1}/pyobjtojson.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyobjtojson
-Version: 0.8
+Version: 0.9.1
 Summary: A Python library that simplifies serializing any Python object to JSON-friendly structures, gracefully handling circular references.
 Author-email: "Carlos A. Planchón" <carlosandresplanchonprestes@gmail.com>
 License-Expression: MIT
@@ -8,9 +8,12 @@ Project-URL: Repository, https://github.com/carlosplanchon/pyobjtojson.git
 Keywords: json,serialization,circular references,pydantic,dataclasses
 Classifier: Intended Audience :: Developers
 Classifier: Topic :: Software Development :: Libraries
+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
-Requires-Python: >=3.13
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Provides-Extra: dev
@@ -34,12 +37,14 @@ A lightweight Python library that simplifies the process of serializing **any**
   Works seamlessly with dictionaries, lists, custom classes, dataclasses, and Pydantic models (including both `model_dump()` from v2 and `dict()` from v1).
 - **Extended Standard Types Support**
   Native support for `datetime`, `date`, `time`, `UUID`, `Decimal`, `bytes`, `Enum`, `Path`, `set`, and `frozenset`.
+- **JSON-Safe Dictionary Keys**
+  Non-string keys (`UUID`, `datetime`, `Enum`, tuples, and other objects) are converted so the returned structure always survives `json.dumps`.
 - **Full Type Hints Support**
   Complete type annotations for better IDE autocomplete, type checking with mypy, and improved code documentation.
 - **Non-Intrusive Serialization**
   No special inheritance or overrides needed. Uses reflection and standard Python methods (`__dict__`, `asdict()`, `to_dict()`, etc.) where available.
 - **Easy to Integrate**
-  Just call `obj_to_json()` on your data structure—no additional configuration required.
+  Just call `obj_to_json()` on your data structure. No additional configuration required.
 
 ### DeepWiki Docs: [https://deepwiki.com/carlosplanchon/pyobjtojson](https://deepwiki.com/carlosplanchon/pyobjtojson)
 
@@ -63,7 +68,12 @@ data = {
     "nested": {"inner_key": "inner_value"}
 }
 
-json_obj = obj_to_json(data)  # Using json.dumps kwargs
+# obj_to_json returns a JSON-serializable structure (nested dicts, lists and
+# primitives), not a JSON string. Pass it to json.dumps() when you need text:
+json_obj = obj_to_json(data)
+
+import json
+json_text = json.dumps(json_obj)
 ```
 
 **Output** (example):
@@ -201,9 +211,47 @@ obj_to_json(data)
 - **Path** → string representation
 - **set, frozenset** → sorted lists
 
+### 5. Dictionary Keys
+
+JSON object keys must be strings, so **pyobjtojson** normalizes non-string keys
+to keep the result compatible with `json.dumps`:
+
+- `str`, `int`, `float`, `bool`, and `None` keys are kept as-is (`json.dumps`
+  already coerces the non-string primitives to strings itself).
+- Typed keys such as `UUID`, `datetime`, `Enum`, `Decimal`, and `Path` are
+  converted to their natural scalar form (e.g. `UUID` → string, `datetime` →
+  ISO string), respecting `decimal_as_float`.
+- Any remaining composite key (a tuple, `frozenset`, or custom object) is
+  stringified as a last resort.
+
+```python
+from uuid import UUID
+from pyobjtojson import obj_to_json
+
+data = {
+    UUID("12345678-1234-5678-1234-567812345678"): "by uuid",
+    (1, 2): "by tuple",
+    42: "by int",
+}
+
+obj_to_json(data)
+```
+
+**Output**:
+```json
+{
+  "12345678-1234-5678-1234-567812345678": "by uuid",
+  "[1, 2]": "by tuple",
+  "42": "by int"
+}
+```
+
+> **Note:** If two distinct keys normalize to the same string, the last one
+> wins. This mirrors how JSON itself collapses duplicate keys.
+
 ## API Reference
 
-### `obj_to_json(obj, check_circular=True, decimal_as_float=True)`
+### `obj_to_json(obj, check_circular=True, decimal_as_float=True, non_finite="null")`
 
 Returns a cycle-free structure (nested dictionaries/lists) that is JSON-serializable.
 
@@ -211,10 +259,33 @@ Returns a cycle-free structure (nested dictionaries/lists) that is JSON-serializ
 - `obj` (Any): The object to serialize to JSON-like structures.
 - `check_circular` (bool, optional): If True (default), detect and mark circular references as `"<circular reference>"`.
 - `decimal_as_float` (bool, optional): If True (default), convert `Decimal` to `float`. If False, convert to string for high precision.
+- `non_finite` (str, optional): How to represent non-finite floats (`inf`, `-inf`, `nan`), which have no JSON literal. One of:
+  - `"null"` (default): convert to `None`, matching JavaScript's `JSON.stringify`.
+  - `"string"`: convert to `"Infinity"`, `"-Infinity"`, or `"NaN"`.
+  - `"keep"`: leave the float as-is. Note this is **not** valid JSON and will raise with `json.dumps(..., allow_nan=False)`.
+
+  An unknown value raises `ValueError`.
 
 **Returns:**
 - `dict | list | Any`: A JSON-serializable structure.
 
+#### Non-finite floats
+
+`inf`, `-inf`, and `nan` are valid Python floats but have no representation in
+the JSON spec. Left untouched they break `json.dumps(..., allow_nan=False)` and
+produce the non-standard `Infinity`/`NaN` tokens that strict parsers reject. By
+default **pyobjtojson** converts them to `null` so the output is always valid,
+portable JSON:
+
+```python
+from pyobjtojson import obj_to_json
+
+data = {"ratio": float("inf"), "value": float("nan"), "ok": 1.5}
+
+obj_to_json(data)                      # {"ratio": None, "value": None, "ok": 1.5}
+obj_to_json(data, non_finite="string") # {"ratio": "Infinity", "value": "NaN", "ok": 1.5}
+```
+
 ## Type Hints
 
 **pyobjtojson** is fully typed and passes strict mypy checking. This provides:

{pyobjtojson-0.8 → pyobjtojson-0.9.1}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pyobjtojson"
-version = "0.8"
+version = "0.9.1"
 authors = [
     {name = "Carlos A. Planchón", email = "carlosandresplanchonprestes@gmail.com"},
 ]
 description = "A Python library that simplifies serializing any Python object to JSON-friendly structures, gracefully handling circular references."
 
-requires-python = ">=3.13"
+requires-python = ">=3.10"
 
 license = "MIT"
 license-files = ["LICENSE"]
@@ -18,6 +18,9 @@ license-files = ["LICENSE"]
 classifiers = [
     "Intended Audience :: Developers",
     "Topic :: Software Development :: Libraries",
+    "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"
 ]
@@ -53,13 +56,15 @@ addopts = [
 ]
 
 [tool.mypy]
-python_version = "3.13"
+python_version = "3.10"
 strict = true
 warn_return_any = true
 warn_unused_configs = true
 disallow_untyped_defs = true
+disallow_any_unimported = false
 show_error_codes = true
 show_column_numbers = true
+pretty = true
 follow_imports = "normal"
 ignore_missing_imports = true
 exclude = ["tests/", ".venv/", "build/", "dist/"]

{pyobjtojson-0.8 → pyobjtojson-0.9.1}/tests/test_circular_references.py

@@ -87,7 +87,8 @@ class TestCircularReferences:
         assert result["next"]["next"]["next"]["next"] == "<circular reference>"
 
     def test_multiple_references_same_object(self):
-        """Test that same object referenced multiple times (not circular)."""
+        """Same object referenced several times in sibling branches is a DAG,
+        not a cycle, and every reference must be serialized in full."""
         shared = {"shared": "data"}
         container = {
             "ref1": shared,
@@ -97,8 +98,43 @@ class TestCircularReferences:
 
         result = obj_to_json(container, check_circular=True)
 
-        # First reference should be serialized normally
-        assert result["ref1"]["shared"] == "data"
-        # Subsequent references to the same object are marked as circular
-        assert result["ref2"] == "<circular reference>"
-        assert result["ref3"] == "<circular reference>"
+        # None of these is a cycle: the shared object is not an ancestor of
+        # itself, so each reference is serialized normally.
+        assert result["ref1"] == {"shared": "data"}
+        assert result["ref2"] == {"shared": "data"}
+        assert result["ref3"] == {"shared": "data"}
+
+    def test_shared_object_in_list(self):
+        """The same instance repeated in a list is not circular."""
+        item = {"n": 1}
+
+        result = obj_to_json([item, item, item], check_circular=True)
+
+        assert result == [{"n": 1}, {"n": 1}, {"n": 1}]
+
+    def test_diamond_shared_reference(self):
+        """A diamond-shaped DAG (shared node reached by two paths) is not a
+        cycle and must be fully serialized on every path."""
+        shared = {"x": 1}
+        container = {
+            "left": shared,
+            "right": {"nested": shared},
+        }
+
+        result = obj_to_json(container, check_circular=True)
+
+        assert result["left"] == {"x": 1}
+        assert result["right"]["nested"] == {"x": 1}
+
+    def test_sibling_reuse_is_not_flagged_but_cycle_is(self):
+        """Reusing an object across siblings is fine; a genuine back-reference
+        into an ancestor is still detected."""
+        shared = {"v": 1}
+        node = {"a": shared, "b": shared}
+        node["self"] = node  # real cycle back into an ancestor
+
+        result = obj_to_json(node, check_circular=True)
+
+        assert result["a"] == {"v": 1}
+        assert result["b"] == {"v": 1}
+        assert result["self"] == "<circular reference>"

{pyobjtojson-0.8 → pyobjtojson-0.9.1}/tests/test_edge_cases.py

@@ -1,6 +1,7 @@
 #!/usr/bin/env python3
 """Tests for edge cases and error handling."""
 
+import json
 import pytest
 from pyobjtojson import obj_to_json
 
@@ -122,16 +123,70 @@ class TestEdgeCases:
         assert result == obj
 
     def test_dict_with_non_string_keys(self):
-        """Test dict with non-string keys (should work as-is)."""
+        """Non-string keys must yield a json.dumps-compatible structure.
+
+        int/float/bool/None keys are kept as-is (json.dumps coerces them to
+        strings itself); other keys are stringified so the result never breaks
+        json.dumps.
+        """
         obj = {
             1: "one",
             2: "two",
             (3, 4): "tuple key"
         }
         result = obj_to_json(obj)
+
+        # Primitive keys pass through unchanged.
         assert result[1] == "one"
         assert result[2] == "two"
-        assert result[(3, 4)] == "tuple key"
+        # The tuple key is no longer a valid JSON key, so it is stringified.
+        assert (3, 4) not in result
+        assert result["[3, 4]"] == "tuple key"
+
+    def test_output_with_non_string_keys_is_json_dumpable(self):
+        """The whole point of the fix: json.dumps must not raise."""
+        import json
+
+        obj = {(1, 2): "x", frozenset({9}): "y", 5: "z"}
+        result = obj_to_json(obj)
+
+        # Must not raise TypeError: keys must be str, int, float, bool or None.
+        json.dumps(result)
+
+    def test_typed_keys_are_serialized(self):
+        """Common typed keys become their natural scalar string form."""
+        from uuid import UUID
+        from datetime import datetime, date
+        from enum import Enum
+        from pathlib import Path
+
+        class Color(Enum):
+            RED = "red"
+
+        obj = {
+            UUID(int=0): "uuid",
+            datetime(2024, 1, 15, 10, 30): "dt",
+            date(2024, 1, 15): "date",
+            Color.RED: "enum",
+            Path("/tmp/x"): "path",
+        }
+        result = obj_to_json(obj)
+
+        assert result["00000000-0000-0000-0000-000000000000"] == "uuid"
+        assert result["2024-01-15T10:30:00"] == "dt"
+        assert result["2024-01-15"] == "date"
+        assert result["red"] == "enum"
+        assert result["/tmp/x"] == "path"
+
+    def test_decimal_key_respects_decimal_as_float(self):
+        """Decimal keys follow the same decimal_as_float option as values."""
+        from decimal import Decimal
+
+        as_float = obj_to_json({Decimal("9.99"): "v"})
+        assert as_float[9.99] == "v"
+
+        as_str = obj_to_json({Decimal("9.99"): "v"}, decimal_as_float=False)
+        assert as_str["9.99"] == "v"
 
     def test_broken_str_method(self):
         """Test object with broken __str__ method."""
@@ -184,3 +239,63 @@ class TestEdgeCases:
         }
         result = obj_to_json(obj)
         assert result == obj
+
+
+class TestNonFiniteFloats:
+    """Test the `non_finite` policy for inf/-inf/nan floats."""
+
+    def test_default_is_null(self):
+        """By default non-finite floats become None, producing valid JSON."""
+        result = obj_to_json(
+            {"a": float("inf"), "b": float("-inf"), "c": float("nan")}
+        )
+        assert result == {"a": None, "b": None, "c": None}
+        # The whole point: strict json.dumps must not raise.
+        json.dumps(result, allow_nan=False)
+
+    def test_finite_floats_untouched(self):
+        """Finite floats are never altered by the policy."""
+        obj = {"x": 1.5, "y": -3.0, "z": 0.0}
+        assert obj_to_json(obj) == obj
+
+    def test_string_mode(self):
+        """String mode yields the standard-looking token strings."""
+        result = obj_to_json(
+            {"pos": float("inf"), "neg": float("-inf"), "nan": float("nan")},
+            non_finite="string",
+        )
+        assert result == {"pos": "Infinity", "neg": "-Infinity", "nan": "NaN"}
+        json.dumps(result, allow_nan=False)
+
+    def test_keep_mode_preserves_legacy_behavior(self):
+        """Keep mode returns the floats unchanged (not strict-JSON valid)."""
+        result = obj_to_json({"a": float("inf")}, non_finite="keep")
+        assert result["a"] == float("inf")
+        assert isinstance(result["a"], float)
+
+    def test_non_finite_decimal(self):
+        """Non-finite Decimal values follow the same policy once floated."""
+        from decimal import Decimal
+
+        assert obj_to_json(Decimal("Infinity")) is None
+        assert obj_to_json(Decimal("NaN"), non_finite="string") == "NaN"
+        # With decimal_as_float=False the Decimal is stringified anyway.
+        assert obj_to_json(Decimal("Infinity"), decimal_as_float=False) == "Infinity"
+
+    def test_non_finite_dict_key(self):
+        """A non-finite float used as a dict key follows the policy too."""
+        assert obj_to_json(
+            {float("inf"): "v"}, non_finite="string"
+        ) == {"Infinity": "v"}
+        result = obj_to_json({float("nan"): "v"})  # default null
+        assert result == {None: "v"}
+        json.dumps(result)  # None key becomes "null", still valid JSON
+
+    def test_non_finite_in_list(self):
+        """Non-finite values inside sequences are handled."""
+        assert obj_to_json([1.0, float("nan"), float("inf")]) == [1.0, None, None]
+
+    def test_invalid_mode_raises(self):
+        """An unknown policy is a programming error and raises ValueError."""
+        with pytest.raises(ValueError, match="non_finite must be one of"):
+            obj_to_json({"a": 1}, non_finite="bogus")

{pyobjtojson-0.8 → pyobjtojson-0.9.1}/tests/test_standard_types.py

@@ -2,6 +2,7 @@
 """Tests for standard Python types support (datetime, UUID, Decimal, etc)."""
 
 import base64
+import sys
 import pytest
 from datetime import datetime, date, time
 from decimal import Decimal
@@ -198,9 +199,39 @@ class TestEnum:
         assert result == "active"
 
     def test_int_enum(self):
-        """Test int-based Enum."""
+        """IntEnum must serialize to its plain underlying value.
+
+        ``== 3`` alone is not enough: an IntEnum member compares equal to its
+        int value, so we also assert the result is a plain int and not the
+        enum member itself. The plain-primitive fast-path used to intercept
+        IntEnum/StrEnum before the Enum branch and return the member as-is.
+        """
         result = obj_to_json(Priority.HIGH)
         assert result == 3
+        assert type(result) is int
+        assert not isinstance(result, Enum)
+
+    def test_string_enum_returns_plain_str(self):
+        """A plain Enum with string values yields a plain str, not the member."""
+        result = obj_to_json(Status.ACTIVE)
+        assert type(result) is str
+        assert not isinstance(result, Enum)
+
+    @pytest.mark.skipif(
+        sys.version_info < (3, 11),
+        reason="StrEnum was added in Python 3.11"
+    )
+    def test_str_enum(self):
+        """StrEnum must serialize to its plain underlying str value."""
+        from enum import StrEnum
+
+        class Color(StrEnum):
+            RED = "red"
+
+        result = obj_to_json(Color.RED)
+        assert result == "red"
+        assert type(result) is str
+        assert not isinstance(result, Enum)
 
     def test_enum_in_dict(self):
         """Test Enum in dictionary."""

pyobjtojson-0.8/pyobjtojson/__init__.py

@@ -1,243 +0,0 @@
-#!/usr/bin/env python3
-
-import base64
-import dataclasses
-from collections.abc import Mapping, Sequence
-from datetime import datetime, date, time
-from decimal import Decimal
-from enum import Enum
-from pathlib import Path
-from typing import Any
-from uuid import UUID
-
-
-def _serialize_for_json(
-    obj: Any,
-    visited: set[int],
-    check_circular: bool = True,
-    _skip_circular_check: bool = False,
-    decimal_as_float: bool = True
-) -> Any:
-    """
-    Internal recursion logic that can handle circular references
-    using `visited`. This includes careful exception handling so
-    partial failures don't break the entire serialization.
-
-    :param obj: The object to serialize.
-    :param visited: A set used to track visited objects (for cycle detection).
-    :param check_circular: Whether to check for and mark circular references.
-    :param _skip_circular_check: Internal flag to skip adding intermediate
-                                   conversion results to visited set.
-    :param decimal_as_float: If True, convert Decimal to float; otherwise to string.
-    :return: A JSON-serializable structure, or a string if it cannot be
-             converted more structurally.
-    """
-
-    # If it's None, bool, int, float, or str, it's already JSON-serializable.
-    if obj is None or isinstance(obj, (bool, int, float, str)):
-        return obj
-
-    # === Standard Python types support ===
-
-    # datetime, date, time → ISO format
-    if isinstance(obj, datetime):
-        return obj.isoformat()
-    if isinstance(obj, date):
-        return obj.isoformat()
-    if isinstance(obj, time):
-        return obj.isoformat()
-
-    # UUID → string
-    if isinstance(obj, UUID):
-        return str(obj)
-
-    # Decimal → float or string
-    if isinstance(obj, Decimal):
-        if decimal_as_float:
-            return float(obj)
-        return str(obj)
-
-    # bytes, bytearray → base64
-    if isinstance(obj, (bytes, bytearray)):
-        return base64.b64encode(bytes(obj)).decode('utf-8')
-
-    # Enum → underlying value
-    if isinstance(obj, Enum):
-        return obj.value
-
-    # Path → string
-    if isinstance(obj, Path):
-        return str(obj)
-
-    # set, frozenset → list
-    if isinstance(obj, (set, frozenset)):
-        try:
-            # Try to sort if elements are comparable
-            return sorted(list(obj))
-        except TypeError:
-            # If not sortable, convert to list without sorting
-            return list(obj)
-
-    obj_id = id(obj)
-
-    # If circular checking is enabled, see if we've already
-    # visited this object.
-    if check_circular is True and not _skip_circular_check:
-        if obj_id in visited:
-            return "<circular reference>"
-        visited.add(obj_id)
-
-    # Handle Mapping (like dict). Build a new dict item by item,
-    # catching errors.
-    if isinstance(obj, Mapping):
-        result_dict: dict[Any, Any] = {}
-        for key, value in obj.items():
-            try:
-                result_dict[key] = _serialize_for_json(
-                    value, visited, check_circular=check_circular,
-                    decimal_as_float=decimal_as_float
-                )
-            except Exception as exc:
-                result_dict[key] = f"<serialization error: {exc}>"
-        return result_dict
-
-    # Handle Sequence (like list/tuple), but not string.
-    if isinstance(obj, Sequence) and not isinstance(obj, str):
-        result_list: list[Any] = []
-        for index, item in enumerate(obj):
-            try:
-                result_list.append(
-                    _serialize_for_json(
-                        obj=item,
-                        visited=visited,
-                        check_circular=check_circular,
-                        decimal_as_float=decimal_as_float
-                    )
-                )
-            except Exception as exc:
-                result_list.append(f"<serialization error at index {index}: {exc}>")
-        return result_list
-
-    # Try Pydantic v2 model_dump(), but fall back if it fails
-    if hasattr(obj, "model_dump") and callable(obj.model_dump):
-        try:
-            model_data = obj.model_dump()
-            # Skip circular check for the intermediate dict to avoid false positives
-            # when Python reuses memory addresses
-            return _serialize_for_json(
-                obj=model_data,
-                visited=visited,
-                check_circular=check_circular,
-                _skip_circular_check=True,
-                decimal_as_float=decimal_as_float
-            )
-        except Exception:
-            # Fall through to next check if this fails
-            ...
-
-    # Try Pydantic v1 .dict(), but fall back if it fails
-    if hasattr(obj, "dict") and callable(obj.dict):
-        try:
-            dict_data = obj.dict()
-            # Skip circular check for the intermediate dict
-            return _serialize_for_json(
-                obj=dict_data,
-                visited=visited,
-                check_circular=check_circular,
-                _skip_circular_check=True,
-                decimal_as_float=decimal_as_float
-            )
-        except Exception:
-            # Fall through to next check if this fails
-            ...
-
-    # If it's a dataclass, convert it using asdict(), but handle exceptions
-    if dataclasses.is_dataclass(obj):
-        try:
-            # is_dataclass can return True for both instances and types,
-            # but we only process instances here
-            dc_data = dataclasses.asdict(obj)  # type: ignore[arg-type]
-            # Skip circular check for the intermediate dict
-            return _serialize_for_json(
-                obj=dc_data,
-                visited=visited,
-                check_circular=check_circular,
-                _skip_circular_check=True,
-                decimal_as_float=decimal_as_float
-            )
-        except Exception:
-            # Fall through to next check if this fails
-            ...
-
-    # If there's a custom .to_dict() method, try that
-    if hasattr(obj, "to_dict") and callable(obj.to_dict):
-        try:
-            custom_dict_data = obj.to_dict()
-            # Skip circular check for the intermediate dict
-            return _serialize_for_json(
-                obj=custom_dict_data,
-                visited=visited,
-                check_circular=check_circular,
-                _skip_circular_check=True,
-                decimal_as_float=decimal_as_float
-            )
-        except Exception:
-            # Fall through to next check if this fails
-            ...
-
-    # If the object has a __dict__, recurse into that
-    if hasattr(obj, "__dict__"):
-        try:
-            # Skip circular check for the __dict__ to avoid false positives
-            return _serialize_for_json(
-                obj=obj.__dict__,
-                visited=visited,
-                check_circular=check_circular,
-                _skip_circular_check=True,
-                decimal_as_float=decimal_as_float
-            )
-        except Exception:
-            # Fall through to next check if this fails
-            pass
-
-    # Last resort: convert to string, but even this can fail
-    # if __str__ is broken
-    try:
-        return str(obj)
-    except Exception as exc:
-        # If that fails, return a generic serialization error.
-        return f"<serialization error: {exc}>"
-
-
-def obj_to_json(
-    obj: Any,
-    check_circular: bool = True,
-    decimal_as_float: bool = True
-) -> Any:
-    """
-    Public-facing function that starts with a fresh visited set
-    to handle cycles (if `check_circular=True`). Calls the internal
-    _serialize_for_json.
-
-    Supports standard Python types including:
-    - datetime, date, time (converted to ISO format)
-    - UUID (converted to string)
-    - Decimal (converted to float or string based on decimal_as_float)
-    - bytes, bytearray (converted to base64)
-    - Enum (converted to underlying value)
-    - Path (converted to string)
-    - set, frozenset (converted to sorted list)
-
-    :param obj: The object to serialize to JSON-like structures.
-    :param check_circular: If True, detect and mark circular references.
-    :param decimal_as_float: If True, convert Decimal to float; otherwise to string.
-                             Default is True.
-    :return: A JSON-serializable structure (dict, list, str, int, float, bool, None).
-    """
-    visited: set[int] = set()
-    return _serialize_for_json(
-        obj=obj,
-        visited=visited,
-        check_circular=check_circular,
-        decimal_as_float=decimal_as_float
-    )