python-jsonstore 1.3.3__py3-none-any.whl

jsonstore.py

@@ -0,0 +1,201 @@
+#!/usr/bin/env python
+# -*- encoding: UTF-8 -*-
+"""
+Provides a Python class that maps values to/from a JSON file
+"""
+from __future__ import absolute_import
+import json
+import os.path
+import sys
+from collections import OrderedDict
+from copy import deepcopy
+
+__all__ = ["JsonStore"]
+
+STRING_TYPES = (str,)
+INT_TYPES = (int,)
+if sys.version_info < (3,):
+    STRING_TYPES += (unicode,)
+    INT_TYPES += (long,)
+VALUE_TYPES = (bool, int, float, type(None)) + INT_TYPES
+
+
+class JsonStore(object):
+    """A class to provide object based access to a JSON file"""
+
+    def __enter__(self):
+        current_state = self.__dict__["_data"]
+        self.__dict__["_states"].append(current_state)
+        self.__dict__["_data"] = deepcopy(current_state)
+        return self
+
+    def __exit__(self, *args):
+        previous_state = self.__dict__["_states"].pop()
+        if any(args):
+            self.__dict__["_data"] = previous_state
+        elif not self.__dict__["_states"]:
+            self._save()
+
+    def _do_auto_commit(self):
+        if self._auto_commit and not self.__dict__["_states"]:
+            self._save()
+
+    def _load(self):
+        if not os.path.exists(self._path):
+            with open(self._path, "w+b") as store:
+                store.write("{}".encode("utf-8"))
+        with open(self._path, "r+b") as store:
+            raw_data = store.read().decode("utf-8")
+        if not raw_data:
+            data = OrderedDict()
+        else:
+            data = json.loads(raw_data, object_pairs_hook=OrderedDict)
+
+        if not isinstance(data, dict):
+            raise ValueError("Root element is not an object")
+        self.__dict__["_data"] = data
+
+    def _save(self):
+        temp = self._path + "~"
+        with open(temp, "wb") as store:
+            output = json.dumps(self._data, indent=self._indent)
+            store.write(output.encode("utf-8"))
+        
+        if sys.version_info >= (3, 3):
+            os.replace(temp, self._path)
+        elif os.name == "windows":
+            os.remove(self._path)
+            os.rename(temp, self._path)
+        else:
+            os.rename(temp, self._path)
+
+    def __init__(self, path, indent=2, auto_commit=True):
+        self.__dict__.update(
+            {
+                "_auto_commit": auto_commit,
+                "_data": None,
+                "_path": path,
+                "_indent": indent,
+                "_states": [],
+            }
+        )
+        self._load()
+
+    def __getattr__(self, key):
+        if key in self._data:
+            return deepcopy(self._data[key])
+        else:
+            raise AttributeError(key)
+
+    @classmethod
+    def _verify_object(cls, obj, parents=None):
+        """
+        Raise an exception if the object is not suitable for assignment.
+
+        """
+        # pylint: disable=unicode-builtin,long-builtin
+        if isinstance(obj, (dict, list)):
+            if parents is None:
+                parents = []
+            elif any(o is obj for o in parents):
+                raise ValueError("Cycle detected in list/dictionary")
+            parents.append(obj)
+
+        if isinstance(obj, dict):
+            for k, v in obj.items():
+                if not cls._valid_string(k):
+                    # this is necessary because of the JSON serialisation
+                    raise TypeError("a dict has non-string keys")
+                cls._verify_object(v, parents)
+        elif isinstance(obj, (list, tuple)):
+            for o in obj:
+                cls._verify_object(o, parents)
+        else:
+            return cls._valid_value(obj)
+
+    @classmethod
+    def _valid_value(cls, value):
+        if isinstance(value, VALUE_TYPES):
+            return True
+        else:
+            return cls._valid_string(value)
+
+    @classmethod
+    def _valid_string(cls, value):
+        if isinstance(value, STRING_TYPES):
+            return True
+        else:
+            return False
+
+    @classmethod
+    def _canonical_key(cls, key):
+        """Convert a set/get/del key into the canonical form."""
+        if cls._valid_string(key):
+            return tuple(key.split("."))
+
+        if isinstance(key, (tuple, list)):
+            key = tuple(key)
+            if not key:
+                raise TypeError("key must be a string or non-empty tuple/list")
+            return key
+
+        raise TypeError("key must be a string or non-empty tuple/list")
+
+    def __setattr__(self, attr, value):
+        self._verify_object(value)
+        self._data[attr] = deepcopy(value)
+        self._do_auto_commit()
+
+    def __delattr__(self, attr):
+        del self._data[attr]
+
+    def __get_obj(self, steps):
+        """Returns the object which is under the given path."""
+        path = []
+        obj = self._data
+        for step in steps:
+            if isinstance(obj, dict) and not self._valid_string(step):
+                # this is necessary because of the JSON serialisation
+                raise TypeError("%s is a dict and %s is not a string" % (path, step))
+            try:
+                obj = obj[step]
+            except (KeyError, IndexError, TypeError) as e:
+                raise type(e)("unable to get %s from %s: %s" % (step, path, e))
+            path.append(step)
+        return obj
+
+    def __setitem__(self, key, value):
+        steps = self._canonical_key(key)
+        path, step = steps[:-1], steps[-1]
+        self._verify_object(value)
+        container = self.__get_obj(path)
+        if isinstance(container, dict) and not self._valid_string(step):
+            raise TypeError("%s is a dict and %s is not a string" % (path, step))
+        try:
+            container[step] = deepcopy(value)
+        except (IndexError, TypeError) as e:
+            raise type(e)("unable to set %s from %s: %s" % (step, path, e))
+        self._do_auto_commit()
+
+    def __getitem__(self, key):
+        steps = self._canonical_key(key)
+        obj = self.__get_obj(steps)
+        return deepcopy(obj)
+
+    def __delitem__(self, key):
+        steps = self._canonical_key(key)
+        path, step = steps[:-1], steps[-1]
+        obj = self.__get_obj(path)
+        try:
+            del obj[step]
+        except (KeyError, IndexError, TypeError) as e:
+            raise type(e)("unable to delete %s from %s: %s" % (step, path, e))
+
+    def __contains__(self, key):
+        steps = self._canonical_key(key)
+        try:
+            self.__get_obj(steps)
+            return True
+        except (KeyError, IndexError, TypeError):
+            # this is rather permissive as the types are dynamic
+            return False

python_jsonstore-1.3.3.dist-info/METADATA

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: python-jsonstore
+Version: 1.3.3
+Summary: Map JSON files onto Python attributes for simple configuration storage
+Author-email: Oliver Bristow <github+pypi@oliverbristow.co.uk>
+License: MIT
+Project-URL: Homepage, https://github.com/Code0x58/python-jsonstore/
+Keywords: json,key,value,store
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 2
+Classifier: Programming Language :: Python :: 2.7
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.3
+Classifier: Programming Language :: Python :: 3.4
+Classifier: Programming Language :: Python :: 3.5
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development
+Requires-Python: >=2.7
+Description-Content-Type: text/x-rst
+License-File: LICENCE.md
+Dynamic: license-file
+
+|PyPI| |Build Status| |Coverage Report|
+
+jsonstore
+=========
+
+This module provides a class that maps keys and values from a JSON file
+onto its attributes.
+
+The goal was to provide a convenient way of loading and saving
+configuration in a familiar human readable format. This is a bit more
+flexible than the
+`configparser <https://docs.python.org/3/library/configparser.html>`__
+module which is included with Python.
+
+This works is tested and working on Python 2.7 and Python 3.6+. It will
+not work on 2.6 or lower. The tests are also executed on PyPy.
+
+Examples
+--------
+
+Basics
+~~~~~~
+
+.. code:: python
+
+    # by default JsonStore commits on every change unless in a transaction
+    store = JsonStore('config.json')
+    store.a_string = "something"
+    store.a_list = [1, 2, 3]
+    store.a_dictionary = {
+      'dict-list': [{}],
+      'ln(2)': 0.69314718056,
+      'for-you': u"💐",
+    }
+
+    # you can use […] to set/get/delete string keys
+    store['some_key'] = "a value"
+    # the key is split on '.'s and works on dictionaries
+    del store['a_dictionary.dict-list']
+    store['a_dictionary.new_value'] = "old value"
+    #  you can also use the syntactic sugar for tuple keys (explicit lists work too)
+    assert store['a_dictionary', 'new_value'] == "old value"
+    # you can traverse lists too
+    assert store['a_list', -1] == 3
+    # you can use slices in lists
+    assert len(store['a_list', 1:]) == 2
+    del store['a_list', :2]
+    assert store.a_list == [3]
+
+    # deep copies are made when assigning values
+    my_list = ['fun']
+    store.a_list = my_list
+    assert store.a_list is not my_list
+    assert 'a_list' in store
+
+    # deep copies are also returned to avoid unsanitary changes being made
+    store.a_dictionary['new_value'] = "new value"  # won't update the store!
+    assert store.a_dictionary['new_value'] == "old value"
+    assert store.a_dictionary is not store.a_dictionary
+
+    # Appending to, extending a list
+    >>> store.list = [1, 2, 3]
+
+    # Because of the fact that .append won't modify the list in the actual file,
+    # but only a copy...
+    >>> store.list.append(4)
+    >>> store.list
+    [1, 2, 3]
+
+    # ... we need to rather use the += operator to append to a list.
+    >>> store.list += [4]
+    >>> store.list
+    [1, 2, 3, 4]
+
+    # Similarly, we can extend the list
+    >>> store.list += [5, 6]
+    >>> store.list
+    [1, 2, 3, 4, 5, 6]
+
+Transactions
+~~~~~~~~~~~~
+
+``JsonStore`` objects can be used as `context
+managers <https://www.python.org/dev/peps/pep-0343/>`__ to provide
+transactions which are rolled back in the event of an exception. The
+transaction model is primitive; you can only nest transactions.
+
+While a store is put into a transaction, it will not save changes to
+file until all of the transactions have been closed.
+
+.. code:: python
+
+    from jsonstore import JsonStore
+
+    # even with auto_commit=True, the file won't be saved until the last contexts has been closed
+    with JsonStore('config.json', indent=None, auto_commit=False) as store:
+      self.value = 1
+
+    # the context manager will roll back changes made if an exception is raised
+    store = JsonStore('config.json', indent=None)
+    try:
+      with store:
+        store.value = "new"
+        raise Exception
+    except Exception:
+      pass
+    # here we see the value that was saved previously
+    assert store.value == 1
+
+
+.. |Build Status| image:: https://github.com/Code0x58/python-jsonstore/actions/workflows/ci.yml/badge.svg
+   :target: https://github.com/Code0x58/python-jsonstore/actions/workflows/ci.yml
+.. |PyPI| image:: https://img.shields.io/pypi/v/python-jsonstore.svg
+   :target: https://pypi.org/project/python-jsonstore/
+.. |Coverage Report| image:: https://codecov.io/gh/Code0x58/python-jsonstore/branch/master/graph/badge.svg
+   :target: https://codecov.io/gh/Code0x58/python-jsonstore

python_jsonstore-1.3.3.dist-info/RECORD

@@ -0,0 +1,6 @@
+jsonstore.py,sha256=YGCPCsjTnklMHR_neqgbcV6ltQh5A5QKW4rbOQzzXJk,6511
+python_jsonstore-1.3.3.dist-info/licenses/LICENCE.md,sha256=CYFsxv7F0RTimJ83xSWkMtR8audySdDV_z9XzTr2EP0,1071
+python_jsonstore-1.3.3.dist-info/METADATA,sha256=yxS-sej7Mi05NMnx9Zrz3gkLVtIlA8uXpPVBD1Dpbpc,5434
+python_jsonstore-1.3.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+python_jsonstore-1.3.3.dist-info/top_level.txt,sha256=5Lr-ZZ_07h17JRcT8M4FAt5aEkwAMHNGZuVHNC7yZ5w,10
+python_jsonstore-1.3.3.dist-info/RECORD,,

python_jsonstore-1.3.3.dist-info/WHEEL

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

python_jsonstore-1.3.3.dist-info/licenses/LICENCE.md

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

python_jsonstore-1.3.3.dist-info/top_level.txt

@@ -0,0 +1 @@
+jsonstore