Metadata-Version: 2.1
Name: dol
Version: 0.1.26
Summary: Base builtin tools make and transform data object layers (dols).
Home-page: https://github.com/i2mint/dol
Author: OtoSense
Author-email: thorwhalen1@gmail.com
License: mit
Description: # dol
        Base builtin tools make and transform data object layers (dols).
        
        The package is light-weight: Pure python; not third-party dependencies.
        
        Why the name?
        - because it's short
        - because it's cute
        - because it reminds one of "russian dolls" (one way to think of wrappers)
        - because we can come up with an acronym the contains "Data Object" in it. 
        
        To install:	```pip install dol```
        
        # Examples
        
        By store we mean key-value store. This could be files in a filesystem, objects in s3, or a database. Where and
        how the content is stored should be specified, but StoreInterface offers a dict-like interface to this.
        
            __getitem__ calls: _id_of_key			                    _obj_of_data
            __setitem__ calls: _id_of_key		        _data_of_obj
            __delitem__ calls: _id_of_key
            __iter__    calls:	            _key_of_id
        
        ```pydocstring
        >>> from dol import Store
        ```
        
        A Store can be instantiated with no arguments. By default it will make a dict and wrap that.
        
        ```pydocstring
        >>> # Default store: no key or value conversion ################################################
        >>> s = Store()
        >>> s['foo'] = 33
        >>> s['bar'] = 65
        >>> assert list(s.items()) == [('foo', 33), ('bar', 65)]
        >>> assert list(s.store.items()) == [('foo', 33), ('bar', 65)]  # see that the store contains the same thing
        ```
        
        Now let's make stores that have a key and value conversion layer 
        input keys will be upper cased, and output keys lower cased 
        input values (assumed int) will be converted to ascii string, and visa versa 
        
        ```pydocstring
        >>>
        >>> def test_store(s):
        ...     s['foo'] = 33  # write 33 to 'foo'
        ...     assert 'foo' in s  # __contains__ works
        ...     assert 'no_such_key' not in s  # __nin__ works
        ...     s['bar'] = 65  # write 65 to 'bar'
        ...     assert len(s) == 2  # there are indeed two elements
        ...     assert list(s) == ['foo', 'bar']  # these are the keys
        ...     assert list(s.keys()) == ['foo', 'bar']  # the keys() method works!
        ...     assert list(s.values()) == [33, 65]  # the values() method works!
        ...     assert list(s.items()) == [('foo', 33), ('bar', 65)]  # these are the items
        ...     assert list(s.store.items()) == [('FOO', '!'), ('BAR', 'A')]  # but note the internal representation
        ...     assert s.get('foo') == 33  # the get method works
        ...     assert s.get('no_such_key', 'something') == 'something'  # return a default value
        ...     del(s['foo'])  # you can delete an item given its key
        ...     assert len(s) == 1  # see, only one item left!
        ...     assert list(s.items()) == [('bar', 65)]  # here it is
        >>>
        ```
        
        We can introduce this conversion layer in several ways. 
        
        Here are few... 
        
        ## by subclassing
        ```pydocstring
        >>> # by subclassing ###############################################################################
        >>> class MyStore(Store):
        ...     def _id_of_key(self, k):
        ...         return k.upper()
        ...     def _key_of_id(self, _id):
        ...         return _id.lower()
        ...     def _data_of_obj(self, obj):
        ...         return chr(obj)
        ...     def _obj_of_data(self, data):
        ...         return ord(data)
        >>> s = MyStore(store=dict())  # note that you don't need to specify dict(), since it's the default
        >>> test_store(s)
        >>>
        ```
        
        ## by assigning functions to converters
        
        ```pydocstring
        >>> # by assigning functions to converters ##########################################################
        >>> class MyStore(Store):
        ...     def __init__(self, store, _id_of_key, _key_of_id, _data_of_obj, _obj_of_data):
        ...         super().__init__(store)
        ...         self._id_of_key = _id_of_key
        ...         self._key_of_id = _key_of_id
        ...         self._data_of_obj = _data_of_obj
        ...         self._obj_of_data = _obj_of_data
        ...
        >>> s = MyStore(dict(),
        ...             _id_of_key=lambda k: k.upper(),
        ...             _key_of_id=lambda _id: _id.lower(),
        ...             _data_of_obj=lambda obj: chr(obj),
        ...             _obj_of_data=lambda data: ord(data))
        >>> test_store(s)
        >>>
        ```
        
        ## using a Mixin class
        
        ```pydocstring
        >>> # using a Mixin class #############################################################################
        >>> class Mixin:
        ...     def _id_of_key(self, k):
        ...         return k.upper()
        ...     def _key_of_id(self, _id):
        ...         return _id.lower()
        ...     def _data_of_obj(self, obj):
        ...         return chr(obj)
        ...     def _obj_of_data(self, data):
        ...         return ord(data)
        ...
        >>> class MyStore(Mixin, Store):  # note that the Mixin must come before Store in the mro
        ...     pass
        ...
        >>> s = MyStore()  # no dict()? No, because default anyway
        >>> test_store(s)
        ```
        
        ## adding wrapper methods to an already made Store instance
        
        ```pydocstring
        >>> # adding wrapper methods to an already made Store instance #########################################
        >>> s = Store(dict())
        >>> s._id_of_key=lambda k: k.upper()
        >>> s._key_of_id=lambda _id: _id.lower()
        >>> s._data_of_obj=lambda obj: chr(obj)
        >>> s._obj_of_data=lambda data: ord(data)
        >>> test_store(s)
        ```
        
Keywords: storage,interface
Platform: any
Description-Content-Type: text/markdown
