Metadata-Version: 2.1
Name: datalink
Version: 0.1.1
Summary: Create simple interfaces to SQL that make working with data as simple as working with dictionaries.
Home-page: https://github.com/hypernormalisation/datalink
Author: Stephen Ogilvy
Author-email: sogilvy@protonmail.com
License: UNKNOWN
Description: <!--[![PyPI version fury.io](https://badge.fury.io/py/ansicolortags.svg)](https://pypi.python.org/pypi/ansicolortags/)-->
        <!--[![PyPI license](https://img.shields.io/pypi/l/ansicolortags.svg)](https://pypi.python.org/pypi/ansicolortags/)-->
        
        # `datalink`
        `datalink` is a python module that lets you interact with entries of SQL
        data as if you were simply using dictionaries.
        
        The module is built on top of `sqlalchemy` and `dataset`, and all SQL
        schemas supported in `sqlalchemy` are supported in `datalink`.
        
        Using `datalink.factory`, the user creates a new class, each instance of
        which is linked to a single entry of data stored in an SQL database.
        Pushing changes to this SQL entry is as simple as modifying the
        instance's attributes.
        
        Loading, saving, unique identification, and database management all
        take place behind the scenes, so the user doesn't need to worry about
        databases at all.
        
        # Installation
        `datalink` is available on the Python Package Index.
        ```
        pip install datalink
        ```
        
        # Tutorial
        A full tutorial is avaiable
        [here](https://github.com/hypernormalisation/datalink/blob/master/doc/tutorial.md).
        
        ## Creating datalinks
        If you've ever used `NameTuple` from the `collections` module, you know
        how to use `datalink`.
        
        Let's make a template for our data and an instance of that template,
        backed up to a file-based `sqlite` database.
        
        Our SQL table will have the columns `a`, `b`, and `c` with the defaults
        set in `my_data_fields`.
        
        
        ```python
        import datalink
        my_data_fields = {'a': 0, 'b': 'a string', 'c': []}  # default entries
        MyClass = datalink.factory('MyClass', 'my_table', my_data_fields,
                                   database='/tmp/my.db')
                                   
        A = MyClass()    
        ```
            INFO | db created at: sqlite:////tmp/my.db
            INFO | created table my_table
            DEBUG | Creating new database entry with id ce267917-6c2e-46d1-bacc-c52affba2d2d.
        
        
        We can also instantiate data in the instance declaration.
        We can then use the `data` property to expose a dict containing a map of
        the column name to value to make sure it has been correctly set.
        
        
        ```python
        B = MyClass(a=100, b='a new string')
        B.data
        ```
        
            DEBUG | Creating new database entry with id e2bd9f8c-af49-4188-96c2-b6f4ea771188.
        
            {'a': 100,
             'b': 'a new string',
             'c': [],
             'id': 'e2bd9f8c-af49-4188-96c2-b6f4ea771188'}
        
        
        
        ## Modifying data
        Now let's modify some elements and see what happens. They are accessible
        as properties in `A` as determined by the defaults we gave the factory.
        
        
        
        ```python
        A.a = 5
        A.c.append(None)
        print(A.a, A.c)
        ```
        
            DEBUG | Updating existing database entry for id ce267917-6c2e-46d1-bacc-c52affba2d2d.
            DEBUG | Updating existing database entry for id ce267917-6c2e-46d1-bacc-c52affba2d2d.
            5 [None]
        
        
        Multiple updates can be pushed to the SQL database at once with the
        `update` method.
        
        
        
        ```python
        A.update(a=1000, c=[1,2,3])
        A.data
        ```
            DEBUG | Updating existing database entry for id ce267917-6c2e-46d1-bacc-c52affba2d2d.
        
            {'a': 1000,
             'b': 'a string',
             'c': [1, 2, 3],
             'id': 'ce267917-6c2e-46d1-bacc-c52affba2d2d'}
        
        ## Loading data
        As we can see, each new instance of `MyClass` receives a Unique
        Universal Identifier (UUID), that can be used to easily fetch rows from
        the database as a positional argument.
        
        
        
        ```python
        print(A.id)
        id_to_load = A.id
        del A
        C = MyClass(id_to_load)
        C.data
        ```
            'ce267917-6c2e-46d1-bacc-c52affba2d2d'
        
            DEBUG | Loaded data corresponding to ID: ce267917-6c2e-46d1-bacc-c52affba2d2d
        
            {'a': 1000,
             'b': 'a string',
             'c': [1, 2, 3],
             'id': 'ce267917-6c2e-46d1-bacc-c52affba2d2d'}
        
        
        
        ## User-specified identification
        Users can also specify their own identifiers in the construction of new
        instances of MyClass to replace the uuid.
        
        This can be useful in design patterns that want to store easily
        accessible configuration or metadata.
        
        
        ```python
        D = MyClass('myid', a=200, b='some other string', c=[4,5,6])
        ```
        
            DEBUG | Creating new database entry with id myid.
        
        
Keywords: development database sql
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Database :: Front-Ends
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3.7
Requires-Python: >=3.3
Description-Content-Type: text/markdown
