json-object-mapper 2.0.0__py3-none-any.whl

json_object_mapper/__init__.py

@@ -0,0 +1,6 @@
+"""json_object_mapper public interface."""
+
+from .core import JSONObjectMapper
+from .exceptions import JSONAccessError
+
+__all__ = ["JSONAccessError", "JSONObjectMapper"]

json_object_mapper/core.py

@@ -0,0 +1,220 @@
+import copy
+import json
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Iterable,
+    Iterator,
+    List,
+    Mapping,
+    MutableMapping,
+    Optional,
+    Tuple,
+    Union,
+)
+
+from .exceptions import JSONAccessError
+from .helpers import (
+    assign_at,
+    delete_on_parent,
+    ensure_next,
+    is_identifier,
+    is_last,
+    parse_path_tokens,
+    peek_is_index,
+    traverse_parent,
+    wrap_value,
+)
+
+JSONScalar = Union[str, int, float, bool, None]
+JSONType = Union[JSONScalar, "JSONObjectMapper", List["JSONObjectMapper"], Dict[str, Any]]
+
+
+class JSONObjectMapper:
+    __slots__ = ("__autocreate_missing", "__default_factory", "__json", "__readonly")
+
+    def __init__(
+        self,
+        data: Union[str, bytes, bytearray, Mapping[str, Any], MutableMapping[str, Any], List[Any]],
+        *,
+        readonly: bool = False,
+        default_factory: Optional[Callable[[], Any]] = None,
+        autocreate_missing: bool = False,
+        _no_copy: bool = False,
+    ) -> None:
+        self.__json = (
+            json.loads(data)
+            if isinstance(data, (str, bytes, bytearray))
+            else (data if _no_copy else copy.deepcopy(data))
+        )
+        if not isinstance(self.__json, (dict, list)):
+            raise TypeError("JSONObjectMapper must wrap a dict or list (or JSON string thereof).")
+        self.__readonly = bool(readonly)
+        self.__default_factory = default_factory
+        self.__autocreate_missing = bool(autocreate_missing)
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"JSONObjectMapper(readonly={self.__readonly}, data={self.__json!r})"
+
+    def to_dict(self) -> Any:
+        return copy.deepcopy(self.__json)
+
+    def to_json(self, *, indent: Optional[int] = None, sort_keys: bool = False) -> str:
+        return json.dumps(self.__json, indent=indent, sort_keys=sort_keys)
+
+    @classmethod
+    def from_json(
+        cls, json_string: Union[str, bytes, bytearray], *, readonly: bool = False
+    ) -> "JSONObjectMapper":
+        return cls(json_string, readonly=readonly)
+
+    def readonly(self) -> bool:
+        return self.__readonly
+
+    # ---------------------------- attribute access ----------------------------
+
+    def __getattr__(self, attribute_name: str) -> Any:
+        data = object.__getattribute__(self, "_JSONObjectMapper__json")
+        if isinstance(data, list):
+            raise JSONAccessError(f"Cannot access attribute '{attribute_name}' on list")
+        if attribute_name in type(self).__dict__:
+            return object.__getattribute__(self, attribute_name)
+        if not is_identifier(attribute_name):
+            raise JSONAccessError(f"'{attribute_name}' is not a valid attribute identifier")
+        try:
+            value = data[attribute_name]
+        except KeyError as error:
+            value = self._on_missing_attr(data, attribute_name, error)
+        return self._wrap(value)
+
+    def _on_missing_attr(self, data: dict, attribute_name: str, error: Exception) -> Any:
+        factory = object.__getattribute__(self, "_JSONObjectMapper__default_factory")
+        readonly_flag = object.__getattribute__(self, "_JSONObjectMapper__readonly")
+        autocreate_flag = object.__getattribute__(self, "_JSONObjectMapper__autocreate_missing")
+        if factory is None:
+            raise JSONAccessError(f"'{attribute_name}' not found") from error
+        produced = factory()
+        if autocreate_flag and not readonly_flag:
+            data[attribute_name] = produced
+        return produced
+
+    def _wrap(self, value: Any) -> Any:
+        readonly_flag = object.__getattribute__(self, "_JSONObjectMapper__readonly")
+        default_factory = object.__getattribute__(self, "_JSONObjectMapper__default_factory")
+        autocreate_flag = object.__getattribute__(self, "_JSONObjectMapper__autocreate_missing")
+        return wrap_value(
+            value, readonly_flag, default_factory, autocreate_flag, factory_object=self.__class__
+        )
+
+    def __setattr__(self, attribute_name: str, value: Any) -> None:
+        if attribute_name in {
+            "_JSONObjectMapper__json",
+            "_JSONObjectMapper__readonly",
+            "_JSONObjectMapper__default_factory",
+            "_JSONObjectMapper__autocreate_missing",
+        }:
+            return object.__setattr__(self, attribute_name, value)
+        if self.__readonly:
+            raise AttributeError("Mapper is read-only")
+        if isinstance(self.__json, list):
+            raise AttributeError("Cannot set attributes on a list")
+        if not is_identifier(attribute_name):
+            raise AttributeError(f"'{attribute_name}' is not a valid attribute name")
+        self.__json[attribute_name] = value
+
+    # ----------------------------- mapping access -----------------------------
+
+    def __getitem__(self, key: Union[int, str]) -> Any:
+        try:
+            value = self.__json[key]  # type: ignore[index]
+        except Exception as error:
+            raise KeyError(key) from error
+        return self._wrap(value)
+
+    def __setitem__(self, key: Union[int, str], value: Any) -> None:
+        if self.__readonly:
+            raise AttributeError("Mapper is read-only")
+        self.__json[key] = value  # type: ignore[index]
+
+    def __iter__(self) -> Iterator:
+        return iter(self.__json)
+
+    def __len__(self) -> int:
+        return len(self.__json)
+
+    def get(self, key: Union[str, int], default: Any = None) -> Any:
+        try:
+            value = self.__json[key]  # type: ignore[index]
+        except Exception:
+            return default
+        return self._wrap(value)
+
+    def keys(self) -> Iterable:
+        if isinstance(self.__json, dict):
+            return self.__json.keys()
+        raise TypeError("keys() only valid for dict roots")
+
+    def items(self) -> Iterable[Tuple[Any, Any]]:
+        if isinstance(self.__json, dict):
+            return ((key, self._wrap(value)) for key, value in self.__json.items())
+        raise TypeError("items() only valid for dict roots")
+
+    def values(self) -> Iterable[Any]:
+        if isinstance(self.__json, dict):
+            return (self._wrap(value) for value in self.__json.values())
+        raise TypeError("values() only valid for dict roots")
+
+    # -------------------------------- path ops --------------------------------
+
+    def get_path(self, path: str, default: Any = None) -> Any:
+        current: Any = self
+        for token in parse_path_tokens(path):
+            try:
+                current = (
+                    getattr(current, token.group("name"))
+                    if token.group("name")
+                    else current[int(token.group("index"))]
+                )
+            except Exception:
+                return default
+        return current
+
+    def set_path(self, path: str, value: Any, *, create_parents: bool = True) -> "JSONObjectMapper":
+        if self.__readonly:
+            raise AttributeError("Mapper is read-only")
+        tokens = parse_path_tokens(path)
+        if not tokens:
+            raise ValueError("Empty path")
+        current = self.__json
+        for index, token in enumerate(tokens):
+            if is_last(index, tokens):
+                assign_at(current, token, value, create_parents, path)
+                return self
+            current = ensure_next(
+                current, token, peek_is_index(tokens, index), create_parents, path
+            )
+        return self
+
+    def del_path(self, path: str, *, raise_on_missing: bool = False) -> "JSONObjectMapper":
+        if self.__readonly:
+            raise AttributeError("Mapper is read-only")
+        tokens = parse_path_tokens(path)
+        if not tokens:
+            raise ValueError("Empty path")
+        parent = traverse_parent(self.__json, tokens, path, raise_on_missing)
+        if parent is None:
+            return self
+        delete_on_parent(parent, tokens[-1], raise_on_missing)
+        return self
+
+    # --------------------------------- merge ----------------------------------
+
+    def merge(self, other: Mapping[str, Any]) -> "JSONObjectMapper":
+        if self.__readonly:
+            raise AttributeError("Mapper is read-only")
+        if not isinstance(self.__json, dict):
+            raise TypeError("merge() requires a dict root")
+        for key, value in other.items():
+            self.__json[key] = value
+        return self

json_object_mapper/exceptions.py

@@ -0,0 +1,2 @@
+class JSONAccessError(AttributeError):
+    """Raised when an attribute-style access fails."""

json_object_mapper/helpers.py

@@ -0,0 +1,143 @@
+import re
+from typing import Any, Callable, List, Optional
+
+
+def is_identifier(key: str) -> bool:
+    return bool(re.match(r"^[A-Za-z_][A-Za-z0-9_]*$", key))
+
+
+PATH_TOKEN = re.compile(
+    r"""
+    (?P<name>[A-Za-z_][A-Za-z0-9_]*)     # identifier
+    | \[ (?P<index>\d+) \]               # [index]
+""",
+    re.VERBOSE,
+)
+
+
+def ensure_list_length(lst: List[Any], index: int) -> None:
+    if index >= len(lst):
+        lst.extend([None] * (index + 1 - len(lst)))
+
+
+def parse_path_tokens(path: str):
+    return list(PATH_TOKEN.finditer(path.replace(".", " ")))
+
+
+def is_last(current_index: int, tokens: List[Any]) -> bool:
+    return current_index == len(tokens) - 1
+
+
+def peek_is_index(tokens: List[Any], current_index: int) -> bool:
+    return tokens[current_index + 1].group("index") is not None
+
+
+def expect_dict(obj: Any, context: str):
+    if not isinstance(obj, dict):
+        raise TypeError(f"Expected dict {context}")
+
+
+def expect_list(obj: Any, context: str):
+    if not isinstance(obj, list):
+        raise TypeError(f"Expected list {context}")
+
+
+def get_token_value(container: Any, token):
+    name, index = token.group("name"), token.group("index")
+    if name is not None:
+        expect_dict(container, f"before '{name}'")
+        return container[name]
+    expect_list(container, f"before index [{index}]")
+    return container[int(index)]
+
+
+def assign_at(container: Any, token, value: Any, create_parents: bool, path: str):
+    name, index = token.group("name"), token.group("index")
+    if name is not None:
+        expect_dict(container, f"in '{path}'")
+        container[name] = value
+        return
+    expect_list(container, f"in '{path}'")
+    index_int = int(index)
+    if index_int >= len(container) and not create_parents:
+        raise IndexError(f"Index {index_int} out of range in '{path}'")
+    ensure_list_length(container, index_int)
+    container[index_int] = value
+
+
+def ensure_next(container: Any, token, next_is_index: bool, create_parents: bool, path: str):
+    name, index = token.group("name"), token.group("index")
+    if name is not None:
+        expect_dict(container, f"in '{path}'")
+        next_value = container.get(name)
+        if next_value is None:
+            if not create_parents:
+                raise KeyError(f"Missing key '{name}' in '{path}'")
+            container[name] = [] if next_is_index else {}
+            next_value = container[name]
+        return next_value
+    expect_list(container, f"in '{path}'")
+    index_int = int(index)
+    if index_int >= len(container):
+        if not create_parents:
+            raise IndexError(f"Index {index_int} out of range in '{path}'")
+        ensure_list_length(container, index_int)
+        container[index_int] = [] if next_is_index else {}
+    return container[index_int]
+
+
+def traverse_parent(root: Any, tokens: List[Any], path: str, strict: bool):
+    current = root
+    for _, token in enumerate(tokens[:-1]):
+        try:
+            current = get_token_value(current, token)
+        except Exception:
+            if strict:
+                segment = token.group("name") or f"[{token.group('index')}]"
+                raise KeyError(f"Missing segment before end at '{segment}' in '{path}'") from None
+            return None
+    return current
+
+
+def delete_on_parent(parent: Any, last_token, strict: bool):
+    name, index = last_token.group("name"), last_token.group("index")
+    if name is not None:
+        expect_dict(parent, "for deletion")
+        if name in parent:
+            del parent[name]
+        elif strict:
+            raise KeyError(f"Missing key '{name}'")
+        return
+    expect_list(parent, "for deletion")
+    index_int = int(index)
+    if 0 <= index_int < len(parent):
+        parent.pop(index_int)
+    elif strict:
+        raise IndexError(f"Index {index_int} out of range")
+
+
+def wrap_value(
+    value: Any,
+    readonly: bool,
+    default_factory: Optional[Callable[[], Any]],
+    autocreate_missing: bool,
+    factory_object: type,
+) -> Any:
+    if isinstance(value, dict):
+        return factory_object(
+            value,
+            readonly=readonly,
+            default_factory=default_factory,
+            autocreate_missing=autocreate_missing,
+            _no_copy=True,
+        )
+    if isinstance(value, list):
+        return [
+            (
+                wrap_value(item, readonly, default_factory, autocreate_missing, factory_object)
+                if isinstance(item, (dict, list))
+                else item
+            )
+            for item in value
+        ]
+    return value

json_object_mapper-2.0.0.dist-info/METADATA

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: json-object-mapper
+Version: 2.0.0
+Summary: Attribute-style access wrapper for JSON-like data with dot-path set/delete and safe defaults
+Author-email: Kobby Owen <dev@kobbyowen.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kobbyowen/json2obj
+Project-URL: Repository, https://github.com/kobbyowen/json2obj
+Project-URL: Issues, https://github.com/kobbyowen/json2obj/issues
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# json-object-mapper
+
+**`json-object-mapper`** is a lightweight Python library that lets you interact with JSON data using **attribute-style access** instead of dictionary keys.
+
+The PyPI distribution is published as `json-object-mapper`.
+
+It turns JSON objects into `JSONObjectMapper` instances that feel natural to use in Python code, while preserving full JSON compatibility.
+
+```python
+from json_object_mapper import JSONObjectMapper
+
+data = {
+    "user": {"name": "Kobby", "age": 29, "skills": ["python", "aws", "forex"]}
+}
+obj = JSONObjectMapper(data)
+print(obj.user.name)        # "Kobby"
+print(obj.user.skills[0])   # "python"
+print(obj.to_json(indent=2))
+```
+
+## ✨ Features
+
+- Attribute-style access (`obj.key`) for dict keys
+- Recursive wrapping for nested dicts and lists
+- Read-only mode (immutability enforced)
+- Dot/bracket path lookups (`obj.get_path("a.b[0].c")`)
+- **New:** `set_path()` / `del_path()` for dot paths
+- **New:** `default_factory` + `autocreate_missing` for safe defaults
+- Utility methods: `to_dict`, `to_json`, `from_json`, `merge`
+
+## Install
+
+```bash
+pip install json-object-mapper
+```
+
+## Usage
+
+```python
+from json_object_mapper import JSONObjectMapper, JSONAccessError
+
+# 1) Wrap & read (basic)
+obj = JSONObjectMapper({"user": {"name": "Kobby", "age": 29}})
+assert obj.user.name == "Kobby"
+assert obj.user.age == 29
+
+# 2) Write with dot notation
+obj.user.country = "GH"
+assert obj.user.country == "GH"
+
+# 3) Lists of dicts (read & write via attribute access)
+obj.services = [{}]  # start with a list containing one dict
+obj.services[0].name = "auth"  # item is wrapped → dot works
+obj.services[0].enabled = True
+assert obj.services[0].name == "auth"
+assert obj.services[0].enabled is True
+
+# 4) Non-identifier keys (use mapping-style access)
+# Keys like "first-name" can't be attributes; use get()/[] instead
+obj.meta = {"first-name": "Kobby"}
+assert obj.meta.get("first-name") == "Kobby"
+assert obj.meta["first-name"] == "Kobby"
+# getattr(obj.meta, "first-name") would raise JSONAccessError
+
+# 5) Safe defaults + auto-create (no extra helpers required)
+# Missing attributes produce defaults; with autocreate they persist.
+cfg = JSONObjectMapper({}, default_factory=dict, autocreate_missing=True)
+cfg.profile.settings.theme = "dark"  # on-demand creation of nested dicts
+assert cfg.profile.settings.theme == "dark"
+
+# 6) Merge convenience (shallow merge into root dict)
+cfg.merge({"features": {"beta": True}})
+assert cfg.features.beta is True
+
+# 7) Read-only wrappers (safe reads; writes raise)
+ro = JSONObjectMapper({"debug": True}, readonly=True)
+assert ro.debug is True
+try:
+    ro.debug = False
+    raise AssertionError("should not be able to write in readonly mode")
+except AttributeError:
+    pass
+```
+
+## Tests
+
+```bash
+python -m pip install -e .
+python -m unittest discover -s tests -v
+```
+
+## Publishing
+
+Publishing is automated with GitHub Actions using PyPI trusted publishing. Create a GitHub release after configuring the `pypi` environment in the repository settings.
+
+MIT License.

json_object_mapper-2.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+json_object_mapper/__init__.py,sha256=4vcntXOGWh_GdDMLvaMIcEApPCTEoyrNxZhgUAXzcEU,170
+json_object_mapper/core.py,sha256=OQJYNAws71cMroocNODJu4LZI6TTk6RM_hYLPnKQdNQ,8342
+json_object_mapper/exceptions.py,sha256=6faK1dOrGhkMlZAlc5gd3gBrEpODrYgspondKDYvFT4,94
+json_object_mapper/helpers.py,sha256=-VvK8iset75HJROpAU_midZuzQhwa5LqhU9-AtoqiMM,4534
+json_object_mapper-2.0.0.dist-info/licenses/LICENSE,sha256=EF8lAlbQKq7IseJB5rYXmRO-LrSAnZdUcE_hMClzRt8,26
+json_object_mapper-2.0.0.dist-info/METADATA,sha256=-CQ1onvVQ0z2YLuE7I2181Dfc9VM7MTHUdYU-MtdnPs,3617
+json_object_mapper-2.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+json_object_mapper-2.0.0.dist-info/top_level.txt,sha256=JDsp0plGU8Ih89aeVsGyptwQR-vVxtz-TRs7K9KI354,19
+json_object_mapper-2.0.0.dist-info/RECORD,,

json_object_mapper-2.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

json_object_mapper-2.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c)

json_object_mapper-2.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+json_object_mapper