PersistentObjects 0.1.6__tar.gz → 0.2.0__tar.gz

persistentobjects-0.2.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: PersistentObjects
+Version: 0.2.0
+Summary: JSON-backed attribute-persistent object with namespace support
+Author: Tornado300
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# PersistentObjects
+
+A simple Python library that provides the `PersistentObject` class, which automatically saves all its attributes to a JSON file. Attributes are saved as soon as they are set.
+
+> [!IMPORTANT]
+> In-place mutations like `.append()`, `.insert()`, `.extend()`, etc. will **not** automatically save!
+> Create a temp variable, mutate it, then reassign it back:
+> ```python
+> temp = pobject.my_list
+> temp.append("new item")
+> pobject.my_list = temp  # triggers save
+> ```
+
+## Installation
+
+```bash
+pip install PersistentObjects
+```
+
+## Usage
+
+```python
+from PersistentObjects import PersistentObject
+
+pobject = PersistentObject("save.json")
+
+# attributes are saved to the json file immediately
+pobject.first_value = 10
+pobject.second_value = "foo"
+
+# namespaces create sub-dicts in the json file
+pobject.namespace("test_namespace")
+pobject.test_namespace.third_value = [10, 5]
+
+# or save the namespace to a variable
+namespace = pobject.namespace("other_namespace")
+namespace.value = 42
+
+# suffix with '_' to make an attribute non-persistent (normal python attribute)
+pobject.temp_ = True
+
+# delete a persistent attribute
+del pobject.first_value
+```
+
+## Namespaces
+
+Use `namespace()` to create a named section within the JSON file. After calling `namespace()`, you can access it via dot notation. Namespaces can be nested arbitrarily deep.
+
+```python
+# create and access via dot notation
+pobject.namespace("ui")
+pobject.ui.theme = "dark"
+pobject.ui.font_size = 14
+
+# nested namespaces
+pobject.namespace("ui").namespace("colors")
+pobject.ui.colors.primary = "#ff0000"
+pobject.ui.colors.accent = "#0000ff"
+
+# or chain it
+colors = pobject.namespace("ui").namespace("colors")
+colors.primary = "#ff0000"
+```
+
+> [!NOTE]
+> You must call `.namespace()` at least once before using dot-access. This is by design — without it, accessing a nonexistent attribute like `pobject.typo` would silently create an empty namespace instead of raising an `AttributeError`.
+
+## Supported types
+
+Beyond the standard JSON types (`str`, `int`, `float`, `bool`, `list`, `dict`, `None`), the following Python types are automatically encoded and decoded:
+
+| Type | JSON representation |
+|---|---|
+| `tuple` | `{"__type__": "tuple", "__value__": [...]}` |
+| `set` | `{"__type__": "set", "__value__": [...]}` |
+| `frozenset` | `{"__type__": "frozenset", "__value__": [...]}` |
+| `bytes` | `{"__type__": "bytes", "__value__": "<base64>"}` |
+| `datetime` | `{"__type__": "datetime", "__value__": "<isoformat>"}` |
+| `date` | `{"__type__": "date", "__value__": "<isoformat>"}` |
+| `time` | `{"__type__": "time", "__value__": "<isoformat>"}` |
+
+Nested structures work too (e.g. a list of tuples, a set of tuples).
+
+```python
+from datetime import datetime
+
+pobject.my_set = {1, 2, 3}
+pobject.my_tuple = ("a", "b", "c")
+pobject.my_bytes = b"hello"
+pobject.my_datetime = datetime(2025, 6, 15, 12, 30)
+```
+
+## Type enforcement
+
+Use `settype()` to register a type constraint on an attribute. Assigning a value of the wrong type raises a `TypeError`.
+
+```python
+from typing import Any
+
+pobject.settype("count", int)
+pobject.count = 5       # ok
+pobject.count = "five"  # TypeError
+
+# union types (Python 3.10+)
+pobject.settype("value", int | None)
+pobject.value = None    # ok
+
+# tuple of types
+pobject.settype("multi", (int, str))
+
+# Any removes the constraint
+pobject.settype("count", Any)
+
+# also works on namespaces
+namespace.settype("volume", int | float)
+```
+
+## Defaults
+
+Use `setdefault()` to set a value only if the attribute doesn't already exist. It also registers the value for `reset()`. An optional `type` parameter combines setting a default with type enforcement.
+
+```python
+pobject.setdefault("name", "default_name")
+pobject.setdefault("count", 0, type=int)  # sets default and enforces type
+
+pobject.count = 99
+pobject.reset("count")   # back to 0
+pobject.reset()          # resets all attributes that have a registered default
+```

persistentobjects-0.2.0/PersistentObjects/core.py

@@ -0,0 +1,383 @@
+import base64, json, os, threading, types
+from datetime import datetime, date, time as time_
+from typing import Any
+
+_TYPE_TAG = "__type__"
+_VALUE_TAG = "__value__"
+_TAGGED_TYPES = {"tuple", "set", "frozenset", "bytes", "datetime", "date", "time"}
+
+
+def _encode(value):
+    """Recursively convert non-JSON-serializable types into tagged dicts."""
+    if isinstance(value, dict):
+        return {k: _encode(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_encode(x) for x in value]
+    if isinstance(value, tuple):
+        return {_TYPE_TAG: "tuple", _VALUE_TAG: [_encode(x) for x in value]}
+    if isinstance(value, set):
+        return {_TYPE_TAG: "set", _VALUE_TAG: [_encode(x) for x in value]}
+    if isinstance(value, frozenset):
+        return {_TYPE_TAG: "frozenset", _VALUE_TAG: [_encode(x) for x in value]}
+    if isinstance(value, bytes):
+        return {_TYPE_TAG: "bytes", _VALUE_TAG: base64.b64encode(value).decode("ascii")}
+    if isinstance(value, datetime):  # must be before date (datetime is subclass of date)
+        return {_TYPE_TAG: "datetime", _VALUE_TAG: value.isoformat()}
+    if isinstance(value, date):
+        return {_TYPE_TAG: "date", _VALUE_TAG: value.isoformat()}
+    if isinstance(value, time_):
+        return {_TYPE_TAG: "time", _VALUE_TAG: value.isoformat()}
+    return value
+
+
+def _decode_hook(obj):
+    """json.load object_hook: convert tagged dicts back to Python types."""
+    if len(obj) == 2 and obj.get(_TYPE_TAG) in _TAGGED_TYPES and _VALUE_TAG in obj:
+        t, v = obj[_TYPE_TAG], obj[_VALUE_TAG]
+        if t == "tuple":
+            return tuple(v)
+        if t == "set":
+            return set(v)
+        if t == "frozenset":
+            return frozenset(v)
+        if t == "bytes":
+            return base64.b64decode(v)
+        if t == "datetime":
+            return datetime.fromisoformat(v)
+        if t == "date":
+            return date.fromisoformat(v)
+        if t == "time":
+            return time_.fromisoformat(v)
+    return obj
+
+
+class _PersistentState:
+    _instances = {}
+
+    def __new__(cls, path):
+        path = os.path.abspath(path)
+
+        if path in cls._instances:
+            return cls._instances[path]
+
+        instance = super().__new__(cls)
+        cls._instances[path] = instance
+        return instance
+
+    def __init__(self, path: str) -> None:
+        # Prevent re-initialization when __new__ returns an existing instance
+        if hasattr(self, "_initialized"):
+            return
+
+        self._initialized = True
+        self._path = os.path.abspath(path)
+        self._lock = threading.Lock()
+        self._data = {}
+        self._defaults = {}
+        self._types = {}
+        self._load()
+
+    def _load(self) -> None:
+        if os.path.exists(self._path):
+            try:
+                with open(self._path, "r", encoding="utf-8") as f:
+                    self._data = json.load(f, object_hook=_decode_hook)
+            except Exception:
+                self._data = {}
+
+    def _save(self) -> None:
+        tmp = self._path + ".tmp"
+        with open(tmp, "w", encoding="utf-8") as f:
+            json.dump(_encode(self._data), f, indent=2)
+        os.replace(tmp, self._path)
+
+    def __getattr__(self, name) -> "Any | _Namespace":
+        if name.startswith("_"):
+            raise AttributeError(f"Cannot access private attribute '{name}'")
+        if name.endswith("_"):
+            try:
+                return super().__getattribute__(name[:-1])
+            except AttributeError:
+                raise AttributeError(
+                    f"'{self.__class__.__name__}' object has no attribute '{name}'.\n Notice: Attribute '{name}' is not persistent!"
+                )
+        try:
+            value = self._data[name]
+            # If it's a dict, return it as a namespace
+            if isinstance(value, dict):
+                return _Namespace(self, name)
+            return value
+        except KeyError:
+            raise AttributeError(
+                f"'{type(self).__name__}' object has no attribute '{name}'"
+            )
+
+    @staticmethod
+    def _check_type(name: str, value: Any, expected: Any) -> None:
+        if expected is None:
+            expected = type(None)
+        elif isinstance(expected, tuple):
+            expected = tuple(type(None) if t is None else t for t in expected)
+        if not isinstance(value, expected):
+            if isinstance(expected, types.UnionType):
+                type_name = str(expected)
+            elif isinstance(expected, tuple):
+                type_name = " | ".join(t.__name__ for t in expected)
+            else:
+                type_name = expected.__name__
+            raise TypeError(
+                f"Attribute '{name}' expected type '{type_name}', got '{type(value).__name__}'"
+            )
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        if name.startswith("_"):
+            super().__setattr__(name, value)
+            return
+
+        if name.endswith("_"):
+            super().__setattr__(name[:-1], value)
+            return
+
+        if name in self._types:
+            self._check_type(name, value, self._types[name])
+
+        with self._lock:
+            self._data[name] = value
+            self._save()
+
+    def __delattr__(self, name: str) -> None:
+        if name.startswith("_"):
+            super().__delattr__(name)
+            return
+        if name.endswith("_"):
+            super().__delattr__(name[:-1])
+            return
+        with self._lock:
+            if name not in self._data:
+                raise AttributeError(
+                    f"'{type(self).__name__}' object has no attribute '{name}'"
+                )
+            del self._data[name]
+            self._types.pop(name, None)
+            self._defaults.pop(name, None)
+            self._save()
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self._path!r}, {self._data})"
+
+
+class _Namespace:
+    _instances: dict = {}
+
+    def __new__(cls, root: _PersistentState, *path: str) -> "_Namespace":
+        instance_key = (id(root), path)
+
+        if instance_key in cls._instances:
+            return cls._instances[instance_key]
+
+        instance = super().__new__(cls)
+        cls._instances[instance_key] = instance
+        return instance
+
+    def __init__(self, root: _PersistentState, *path: str) -> None:
+        if hasattr(self, "_initialized"):
+            return
+
+        self._initialized = True
+        self._root = root
+        self._path = path
+        self._defaults: dict = {}
+        self._types: dict = {}
+
+    def _get_bucket(self, create: bool = False) -> dict:
+        """Navigate the path into root._data, returning the nested dict."""
+        data = self._root._data
+        for key in self._path:
+            if create:
+                data = data.setdefault(key, {})
+            else:
+                data = data[key]
+        return data
+
+    def __getattr__(self, name: str) -> "Any | _Namespace":
+        if name.startswith("_"):
+            raise AttributeError(name)
+        if name.endswith("_"):
+            try:
+                return super().__getattribute__(name[:-1])
+            except AttributeError:
+                raise AttributeError(
+                    f"'{self.__class__.__name__}' object has no attribute '{name}'.\n Notice: Attribute '{name}' is not persistent!"
+                )
+        try:
+            value = self._get_bucket()[name]
+            if isinstance(value, dict):
+                return _Namespace(self._root, *self._path, name)
+            return value
+        except KeyError:
+            raise AttributeError(name)
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        if name.startswith("_"):
+            super().__setattr__(name, value)
+            return
+
+        if name.endswith("_"):
+            super().__setattr__(name[:-1], value)
+            return
+
+        if name in self._types:
+            _PersistentState._check_type(name, value, self._types[name])
+
+        with self._root._lock:
+            bucket = self._get_bucket(create=True)
+            bucket[name] = value
+            self._root._save()
+
+    def __delattr__(self, name: str) -> None:
+        if name.startswith("_"):
+            super().__delattr__(name)
+            return
+        if name.endswith("_"):
+            super().__delattr__(name[:-1])
+            return
+        with self._root._lock:
+            try:
+                bucket = self._get_bucket()
+            except KeyError:
+                raise AttributeError(
+                    f"'{type(self).__name__}' object has no attribute '{name}'"
+                )
+            if name not in bucket:
+                raise AttributeError(
+                    f"'{type(self).__name__}' object has no attribute '{name}'"
+                )
+            del bucket[name]
+            self._types.pop(name, None)
+            self._defaults.pop(name, None)
+            self._root._save()
+
+    def __repr__(self) -> str:
+        try:
+            data = self._get_bucket()
+        except KeyError:
+            data = {}
+        path = ".".join(self._path)
+        return f"Namespace({path!r}, {data})"
+
+    def namespace(self, name: str) -> "_Namespace":
+        """Return a nested sub-namespace."""
+        with self._root._lock:
+            bucket = self._get_bucket(create=True)
+            if name not in bucket:
+                bucket[name] = {}
+                self._root._save()
+        return _Namespace(self._root, *self._path, name)
+
+    def settype(self, name: str, type_hint: Any) -> None:
+        """Register a type constraint for an attribute.
+
+        Accepted: a type, tuple of types, union type (int | str), None (means NoneType), or Any (removes constraint).
+        If the attribute already has a value, it is validated immediately.
+        """
+        if type_hint is Any:
+            self._types.pop(name, None)
+            return
+        self._types[name] = type_hint
+        try:
+            bucket = self._get_bucket()
+            if name in bucket:
+                _PersistentState._check_type(name, bucket[name], type_hint)
+        except KeyError:
+            pass
+
+    def setdefault(self, name: str, value: Any, type: Any = None) -> Any:
+        """Set a value only if the key doesn't already exist. Registers the value as the default for reset().
+
+        If type is provided, also registers a type constraint via settype().
+        """
+        if type is not None:
+            self.settype(name, type)
+            _PersistentState._check_type(name, value, type if type is not Any else value.__class__)
+        self._defaults[name] = value
+        with self._root._lock:
+            bucket = self._get_bucket(create=True)
+            if name not in bucket:
+                bucket[name] = value
+                self._root._save()
+        return self._get_bucket()[name]
+
+    def reset(self, name: str | None = None) -> None:
+        """Reset a key to its default value, or all keys if no name is given.
+
+        Raises KeyError if the key has no registered default.
+        """
+        with self._root._lock:
+            bucket = self._get_bucket(create=True)
+            if name is not None:
+                if name not in self._defaults:
+                    raise KeyError(
+                        f"No default registered for '{name}'. Use setdefault() first."
+                    )
+                bucket[name] = self._defaults[name]
+            else:
+                for key, value in self._defaults.items():
+                    bucket[key] = value
+            self._root._save()
+
+
+class PersistentObject(_PersistentState):
+    def namespace(self, name: str) -> _Namespace:
+        with self._lock:
+            if name not in self._data:
+                self._data[name] = {}
+                self._save()
+        return _Namespace(self, name)
+
+    def settype(self, name: str, type_hint: Any) -> None:
+        """Register a type constraint for an attribute.
+
+        Accepted: a type, tuple of types, union type (int | str), None (means NoneType), or Any (removes constraint).
+        If the attribute already has a value, it is validated immediately.
+        """
+        if type_hint is Any:
+            self._types.pop(name, None)
+            return
+        self._types[name] = type_hint
+        if name in self._data:
+            self._check_type(name, self._data[name], type_hint)
+
+    def setdefault(self, name: str, value: Any, type: Any = None) -> Any:
+        """Set a value only if the key doesn't already exist. Registers the value as the default for reset().
+
+        If type is provided, also registers a type constraint via settype().
+        """
+        if type is not None:
+            self.settype(name, type)
+            self._check_type(name, value, type if type is not Any else value.__class__)
+        self._defaults[name] = value
+        with self._lock:
+            if name not in self._data:
+                self._data[name] = value
+                self._save()
+        return self._data[name]
+
+    def reset(self, name: str | None = None) -> None:
+        """Reset a key to its default value, or all keys if no name is given.
+
+        Raises KeyError if the key has no registered default.
+        """
+        with self._lock:
+            if name is not None:
+                if name not in self._defaults:
+                    raise KeyError(
+                        f"No default registered for '{name}'. Use setdefault() first."
+                    )
+                self._data[name] = self._defaults[name]
+            else:
+                for key, value in self._defaults.items():
+                    self._data[key] = value
+            self._save()
+
+
+__all__ = ["PersistentObject"]

persistentobjects-0.2.0/PersistentObjects.egg-info/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: PersistentObjects
+Version: 0.2.0
+Summary: JSON-backed attribute-persistent object with namespace support
+Author: Tornado300
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# PersistentObjects
+
+A simple Python library that provides the `PersistentObject` class, which automatically saves all its attributes to a JSON file. Attributes are saved as soon as they are set.
+
+> [!IMPORTANT]
+> In-place mutations like `.append()`, `.insert()`, `.extend()`, etc. will **not** automatically save!
+> Create a temp variable, mutate it, then reassign it back:
+> ```python
+> temp = pobject.my_list
+> temp.append("new item")
+> pobject.my_list = temp  # triggers save
+> ```
+
+## Installation
+
+```bash
+pip install PersistentObjects
+```
+
+## Usage
+
+```python
+from PersistentObjects import PersistentObject
+
+pobject = PersistentObject("save.json")
+
+# attributes are saved to the json file immediately
+pobject.first_value = 10
+pobject.second_value = "foo"
+
+# namespaces create sub-dicts in the json file
+pobject.namespace("test_namespace")
+pobject.test_namespace.third_value = [10, 5]
+
+# or save the namespace to a variable
+namespace = pobject.namespace("other_namespace")
+namespace.value = 42
+
+# suffix with '_' to make an attribute non-persistent (normal python attribute)
+pobject.temp_ = True
+
+# delete a persistent attribute
+del pobject.first_value
+```
+
+## Namespaces
+
+Use `namespace()` to create a named section within the JSON file. After calling `namespace()`, you can access it via dot notation. Namespaces can be nested arbitrarily deep.
+
+```python
+# create and access via dot notation
+pobject.namespace("ui")
+pobject.ui.theme = "dark"
+pobject.ui.font_size = 14
+
+# nested namespaces
+pobject.namespace("ui").namespace("colors")
+pobject.ui.colors.primary = "#ff0000"
+pobject.ui.colors.accent = "#0000ff"
+
+# or chain it
+colors = pobject.namespace("ui").namespace("colors")
+colors.primary = "#ff0000"
+```
+
+> [!NOTE]
+> You must call `.namespace()` at least once before using dot-access. This is by design — without it, accessing a nonexistent attribute like `pobject.typo` would silently create an empty namespace instead of raising an `AttributeError`.
+
+## Supported types
+
+Beyond the standard JSON types (`str`, `int`, `float`, `bool`, `list`, `dict`, `None`), the following Python types are automatically encoded and decoded:
+
+| Type | JSON representation |
+|---|---|
+| `tuple` | `{"__type__": "tuple", "__value__": [...]}` |
+| `set` | `{"__type__": "set", "__value__": [...]}` |
+| `frozenset` | `{"__type__": "frozenset", "__value__": [...]}` |
+| `bytes` | `{"__type__": "bytes", "__value__": "<base64>"}` |
+| `datetime` | `{"__type__": "datetime", "__value__": "<isoformat>"}` |
+| `date` | `{"__type__": "date", "__value__": "<isoformat>"}` |
+| `time` | `{"__type__": "time", "__value__": "<isoformat>"}` |
+
+Nested structures work too (e.g. a list of tuples, a set of tuples).
+
+```python
+from datetime import datetime
+
+pobject.my_set = {1, 2, 3}
+pobject.my_tuple = ("a", "b", "c")
+pobject.my_bytes = b"hello"
+pobject.my_datetime = datetime(2025, 6, 15, 12, 30)
+```
+
+## Type enforcement
+
+Use `settype()` to register a type constraint on an attribute. Assigning a value of the wrong type raises a `TypeError`.
+
+```python
+from typing import Any
+
+pobject.settype("count", int)
+pobject.count = 5       # ok
+pobject.count = "five"  # TypeError
+
+# union types (Python 3.10+)
+pobject.settype("value", int | None)
+pobject.value = None    # ok
+
+# tuple of types
+pobject.settype("multi", (int, str))
+
+# Any removes the constraint
+pobject.settype("count", Any)
+
+# also works on namespaces
+namespace.settype("volume", int | float)
+```
+
+## Defaults
+
+Use `setdefault()` to set a value only if the attribute doesn't already exist. It also registers the value for `reset()`. An optional `type` parameter combines setting a default with type enforcement.
+
+```python
+pobject.setdefault("name", "default_name")
+pobject.setdefault("count", 0, type=int)  # sets default and enforces type
+
+pobject.count = 99
+pobject.reset("count")   # back to 0
+pobject.reset()          # resets all attributes that have a registered default
+```

persistentobjects-0.2.0/README.md

@@ -0,0 +1,130 @@
+# PersistentObjects
+
+A simple Python library that provides the `PersistentObject` class, which automatically saves all its attributes to a JSON file. Attributes are saved as soon as they are set.
+
+> [!IMPORTANT]
+> In-place mutations like `.append()`, `.insert()`, `.extend()`, etc. will **not** automatically save!
+> Create a temp variable, mutate it, then reassign it back:
+> ```python
+> temp = pobject.my_list
+> temp.append("new item")
+> pobject.my_list = temp  # triggers save
+> ```
+
+## Installation
+
+```bash
+pip install PersistentObjects
+```
+
+## Usage
+
+```python
+from PersistentObjects import PersistentObject
+
+pobject = PersistentObject("save.json")
+
+# attributes are saved to the json file immediately
+pobject.first_value = 10
+pobject.second_value = "foo"
+
+# namespaces create sub-dicts in the json file
+pobject.namespace("test_namespace")
+pobject.test_namespace.third_value = [10, 5]
+
+# or save the namespace to a variable
+namespace = pobject.namespace("other_namespace")
+namespace.value = 42
+
+# suffix with '_' to make an attribute non-persistent (normal python attribute)
+pobject.temp_ = True
+
+# delete a persistent attribute
+del pobject.first_value
+```
+
+## Namespaces
+
+Use `namespace()` to create a named section within the JSON file. After calling `namespace()`, you can access it via dot notation. Namespaces can be nested arbitrarily deep.
+
+```python
+# create and access via dot notation
+pobject.namespace("ui")
+pobject.ui.theme = "dark"
+pobject.ui.font_size = 14
+
+# nested namespaces
+pobject.namespace("ui").namespace("colors")
+pobject.ui.colors.primary = "#ff0000"
+pobject.ui.colors.accent = "#0000ff"
+
+# or chain it
+colors = pobject.namespace("ui").namespace("colors")
+colors.primary = "#ff0000"
+```
+
+> [!NOTE]
+> You must call `.namespace()` at least once before using dot-access. This is by design — without it, accessing a nonexistent attribute like `pobject.typo` would silently create an empty namespace instead of raising an `AttributeError`.
+
+## Supported types
+
+Beyond the standard JSON types (`str`, `int`, `float`, `bool`, `list`, `dict`, `None`), the following Python types are automatically encoded and decoded:
+
+| Type | JSON representation |
+|---|---|
+| `tuple` | `{"__type__": "tuple", "__value__": [...]}` |
+| `set` | `{"__type__": "set", "__value__": [...]}` |
+| `frozenset` | `{"__type__": "frozenset", "__value__": [...]}` |
+| `bytes` | `{"__type__": "bytes", "__value__": "<base64>"}` |
+| `datetime` | `{"__type__": "datetime", "__value__": "<isoformat>"}` |
+| `date` | `{"__type__": "date", "__value__": "<isoformat>"}` |
+| `time` | `{"__type__": "time", "__value__": "<isoformat>"}` |
+
+Nested structures work too (e.g. a list of tuples, a set of tuples).
+
+```python
+from datetime import datetime
+
+pobject.my_set = {1, 2, 3}
+pobject.my_tuple = ("a", "b", "c")
+pobject.my_bytes = b"hello"
+pobject.my_datetime = datetime(2025, 6, 15, 12, 30)
+```
+
+## Type enforcement
+
+Use `settype()` to register a type constraint on an attribute. Assigning a value of the wrong type raises a `TypeError`.
+
+```python
+from typing import Any
+
+pobject.settype("count", int)
+pobject.count = 5       # ok
+pobject.count = "five"  # TypeError
+
+# union types (Python 3.10+)
+pobject.settype("value", int | None)
+pobject.value = None    # ok
+
+# tuple of types
+pobject.settype("multi", (int, str))
+
+# Any removes the constraint
+pobject.settype("count", Any)
+
+# also works on namespaces
+namespace.settype("volume", int | float)
+```
+
+## Defaults
+
+Use `setdefault()` to set a value only if the attribute doesn't already exist. It also registers the value for `reset()`. An optional `type` parameter combines setting a default with type enforcement.
+
+```python
+pobject.setdefault("name", "default_name")
+pobject.setdefault("count", 0, type=int)  # sets default and enforces type
+
+pobject.count = 99
+pobject.reset("count")   # back to 0
+pobject.reset()          # resets all attributes that have a registered default
+```

{persistentobjects-0.1.6 → persistentobjects-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "PersistentObjects"
-version = "0.1.6"
+version = "0.2.0"
 description = "JSON-backed attribute-persistent object with namespace support"
 authors = [
     { name="Tornado300" }

persistentobjects-0.1.6/PKG-INFO

@@ -1,41 +0,0 @@
-Metadata-Version: 2.4
-Name: PersistentObjects
-Version: 0.1.6
-Summary: JSON-backed attribute-persistent object with namespace support
-Author: Tornado300
-License-Expression: MIT
-Classifier: Programming Language :: Python :: 3
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Dynamic: license-file
-
-This is a very simple lib that provides the PersistantObject class, which saves all its attributes to the given json file. Exceptions are attributes suffixed with '_'.
-Attributes are saved as soon as they are set.
-
-[!IMPORTANT]
-> morphing actions like appending, inserting, extending, etc. will not automaticly save!
-> so its recomended to create a temp var, then append to it and at the end set the PersistantObject attr to the temp var.
-
-with namespace(NAME) seperate sub namespaces can be created inside the object. 
-
-
-## Usage example:
-```python
-
-from PersistantObject import PersistantObject
-
-pobject = PersistantObject("save.json")
-
-pobject.first_value = 10
-pobject.second_value = "foo"
-
-namespace = pobject.namespace("test_namespace") # creates a new namespace (new subdict in json)
-namespace.third_value = [10, 5]
-
-
-print(pobject.test_namespace.third_value) # alternate way to access namespaces
-
-pobject.temp_ = True # suffixed with '_' so it will not be saved and behaves like a normal attribute.
-```

persistentobjects-0.1.6/PersistentObjects/core.py

@@ -1,135 +0,0 @@
-import json, os, threading
-
-
-class _PersistentState:
-    _instances = {}
-
-    def __new__(cls, path):
-        path = os.path.abspath(path)
-
-        if path in cls._instances:
-            return cls._instances[path]
-
-        instance = super().__new__(cls)
-        cls._instances[path] = instance
-        return instance
-
-    def __init__(self, path):
-        # Prevent re-initialization when __new__ returns an existing instance
-        if hasattr(self, "_initialized"):
-            return
-
-        self._initialized = True
-        self._path = os.path.abspath(path)
-        self._lock = threading.Lock()
-        self._data = {}
-        self._load()
-
-    def _load(self):
-        if os.path.exists(self._path):
-            try:
-                with open(self._path, "r", encoding="utf-8") as f:
-                    self._data = json.load(f)
-            except Exception:
-                self._data = {}
-
-    def _save(self):
-        tmp = self._path + ".tmp"
-        with open(tmp, "w", encoding="utf-8") as f:
-            json.dump(self._data, f, indent=2)
-        os.replace(tmp, self._path)
-
-    def __getattr__(self, name):
-        if name.startswith("_"):
-            raise AttributeError(f"Cannot access private attribute '{name}'")
-        if name.endswith("_"):
-            try:
-                return super().__getattribute__(name[:-1])
-            except AttributeError:
-                raise AttributeError(
-                    f"'{self.__class__.__name__}' object has no attribute '{name}'.\n Notice: Attribute '{name}' is not persistent!"
-                )
-        try:
-            value = self._data[name]
-            # If it's a dict, return it as a namespace
-            if isinstance(value, dict):
-                return _Namespace(self, name)
-            return value
-        except KeyError:
-            raise AttributeError(
-                f"'{type(self).__name__}' object has no attribute '{name}'"
-            )
-
-    def __setattr__(self, name, value):
-        if name.startswith("_"):
-            super().__setattr__(name, value)
-            return
-
-        if name.endswith("_"):
-            super().__setattr__(name[:-1], value)
-            return
-
-        with self._lock:
-            self._data[name] = value
-            self._save()
-
-
-class _Namespace:
-    _instances = {}
-
-    def __new__(cls, root, key):
-        # Create unique identifier for this namespace
-        instance_key = (id(root), key)
-
-        if instance_key in cls._instances:
-            return cls._instances[instance_key]
-
-        instance = super().__new__(cls)
-        cls._instances[instance_key] = instance
-        return instance
-
-    def __init__(self, root, key):
-        # Prevent re-initialization
-        if hasattr(self, "_initialized"):
-            return
-
-        self._initialized = True
-        self._root = root
-        self._key = key
-
-    def __getattr__(self, name):
-        if name.startswith("_"):
-            raise AttributeError(name)
-        if name.endswith("_"):
-            try:
-                return super().__getattribute__(name[:-1])
-            except AttributeError:
-                raise AttributeError(
-                    f"'{self.__class__.__name__}' object has no attribute '{name}'.\n Notice: Attribute '{name}' is not persistent!"
-                )
-        try:
-            return self._root._data[self._key][name]
-        except KeyError:
-            raise AttributeError(name)
-
-    def __setattr__(self, name, value):
-        if name.startswith("_"):
-            super().__setattr__(name, value)
-            return
-
-        if name.endswith("_"):
-            super().__setattr__(name[:-1], value)
-            return
-
-        with self._root._lock:
-            bucket = self._root._data.setdefault(self._key, {})
-            bucket[name] = value
-            self._root._save()
-
-
-class PersistentObject(_PersistentState):
-    def namespace(self, name) -> _Namespace:
-        return _Namespace(self, name)
-
-
-__all__ = ["PersistentObject"]

persistentobjects-0.1.6/PersistentObjects.egg-info/PKG-INFO

@@ -1,41 +0,0 @@
-Metadata-Version: 2.4
-Name: PersistentObjects
-Version: 0.1.6
-Summary: JSON-backed attribute-persistent object with namespace support
-Author: Tornado300
-License-Expression: MIT
-Classifier: Programming Language :: Python :: 3
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Dynamic: license-file
-
-This is a very simple lib that provides the PersistantObject class, which saves all its attributes to the given json file. Exceptions are attributes suffixed with '_'.
-Attributes are saved as soon as they are set.
-
-[!IMPORTANT]
-> morphing actions like appending, inserting, extending, etc. will not automaticly save!
-> so its recomended to create a temp var, then append to it and at the end set the PersistantObject attr to the temp var.
-
-with namespace(NAME) seperate sub namespaces can be created inside the object. 
-
-
-## Usage example:
-```python
-
-from PersistantObject import PersistantObject
-
-pobject = PersistantObject("save.json")
-
-pobject.first_value = 10
-pobject.second_value = "foo"
-
-namespace = pobject.namespace("test_namespace") # creates a new namespace (new subdict in json)
-namespace.third_value = [10, 5]
-
-
-print(pobject.test_namespace.third_value) # alternate way to access namespaces
-
-pobject.temp_ = True # suffixed with '_' so it will not be saved and behaves like a normal attribute.
-```

persistentobjects-0.1.6/README.md

@@ -1,28 +0,0 @@
-This is a very simple lib that provides the PersistantObject class, which saves all its attributes to the given json file. Exceptions are attributes suffixed with '_'.
-Attributes are saved as soon as they are set.
-
-[!IMPORTANT]
-> morphing actions like appending, inserting, extending, etc. will not automaticly save!
-> so its recomended to create a temp var, then append to it and at the end set the PersistantObject attr to the temp var.
-
-with namespace(NAME) seperate sub namespaces can be created inside the object. 
-
-
-## Usage example:
-```python
-
-from PersistantObject import PersistantObject
-
-pobject = PersistantObject("save.json")
-
-pobject.first_value = 10
-pobject.second_value = "foo"
-
-namespace = pobject.namespace("test_namespace") # creates a new namespace (new subdict in json)
-namespace.third_value = [10, 5]
-
-
-print(pobject.test_namespace.third_value) # alternate way to access namespaces
-
-pobject.temp_ = True # suffixed with '_' so it will not be saved and behaves like a normal attribute.
-```