Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/skulltech/ormvana

A minimalist ORM for the power user — Releases you from the sufferings of the traditional ORM world.
https://github.com/skulltech/ormvana

database mysql orm python python3 sql sqlite3

Last synced: 6 days ago
JSON representation

A minimalist ORM for the power user — Releases you from the sufferings of the traditional ORM world.

Awesome Lists containing this project

README 

        
# ormvana

A minimalist ORM for the power user — Releases you from the sufferings of the traditional ORM world.



[![PyPI version](https://badge.fury.io/py/ormvana.svg)](https://badge.fury.io/py/ormvana)



## Usage



Using `ormvana` is as simple as:

```python

from ormvana import Model



class User(Model):

    name = 'user'

    fields = dict()

    for field in ['email', 'first_name', 'last_name']:

        fields[field] = {'type': str}

    fields['active'] = {

        'type': int,

        'value': 0

    }

    

john = User(email='[email protected]', first_name='John', last_name='Doe')

john.save()

john.email = '[email protected]'

john.save()

```



## Features



- Model based ORM, similar to most popular framework, so nonexistent learning curve.

- Create, modify and fetch records easily using built-in implementations.

- Complete freedom over database schema — it lets you create the schema yourself.

- Complete freedom over writing custom SQL queries.



## Installation



Install it using pip

```console

$ pip3 install ormvana

```



## Documentation



Documentation is available at https://ormvana.readthedocs.io/



## Tutorial



I'm going to demonstrate the usage of this module using a blog application, containing two tables: users and posts. You 

can find the complete example [here](https://github.com/SkullTech/ormvana/tree/master/example/).



### Defining the models



To get started, all you need to do is —

- Create class(es) describing the `Model` // `Table`(s).

- Provide a function which 

returns a connection to a database. 



For example

```sql

CREATE TABLE IF NOT EXISTS user (

 id INTEGER PRIMARY KEY,

 email TEXT NOT NULL,

 first_name TEXT NOT NULL,

 last_name INTEGER NOT NULL,

 active INTEGER NOT NULL DEFAULT '0'

);

```



For the above database `Table` definition, you should create a `Model` class like the following —



```python

from ormvana import Model



class User(Model):

    name = 'user'

    fields = dict()

    for field in ['email', 'first_name', 'last_name']:

        fields[field] = {'type': str}

    fields['active'] = {

        'type': int,

        'value': 0

    }

```



Notice that all we're really doing is:

- Specifying the name of the `Table` using the `name` class variable.

- Specifying the columns // `Field`s of the database using the `fields` class variable. `fields` is a dict, where the 

keys are the _field names_ and the values are dicts. These dicts necessarily contain a key named `type` which can either take 

`str` or `int` as values, and optionally contain another key named `value`, which can be used to provide a default 

value of the given field.



You also would need to provide a `connection` function to `ormvana`, which would return a connection to the database, 

along with a bool that indicates whether to `close` the connection after every query.



Check the following example:

```python

import sqlite3

import ormvana



def connection():

    conn = sqlite3.connect('blog.db')

    conn.row_factory = sqlite3.Row

    return True, conn



ormvana.connection = connection

```



For retrieving records // objects, _ormvana_ provides you with three built-in class functions — 

1. `get`: For retrieving record by `id`. 

2. `get_by`: For retrieving records(s) having given value for given field.

3. `get_all`: For retrieving all the records of the table.



For everything else, you have to write a method for your class that returns a valid SQL query, and decorate that with 

either the `fetch_single` or `fetch_multiple` decorator accordingly. For example, look at the following:



```sql

DROP TABLE IF EXISTS `post`;

CREATE TABLE IF NOT EXISTS post (

  id INTEGER PRIMARY KEY,

  title TEXT NOT NULL,

  body TEXT NOT NULL,

  author INTEGER NOT NULL

);

```



```python

from ormvana import Model



class Post(Model):

    name = 'post'

    fields = dict()

    for field in ['title', 'body']:

        fields[field] = {'type': str}

    fields['author'] = {'type': int}



    @classmethod

    @Model.fetch_multiple

    def users_posts(cls, email):

        return '''SELECT * FROM `{0}` WHERE `author`=(SELECT id from `user` WHERE email='{1}');'''.format(cls.name,

                                                                                                          email)

```



Now that we have defined our models, let's look at how we could use them in our application.



### Creating records



```pycon

>>> from models import User, Post

>>> john = User(email='[email protected]', first_name='John', last_name='Doe')

>>> john.save()

[*] Query: INSERT INTO `user` (`active`, `email`, `first_name`, `last_name`) VALUES (0, '[email protected]', 'John', 'Doe');

1

>>> john.email = '[email protected]'

>>> john.save()

[*] Query: UPDATE `user` set `active` = 0, `email` = '[email protected]', `first_name` = 'John', `last_name` = 'Doe' WHERE id=1;

1

>>> jane = User(email='[email protected]', first_name='Jane', last_name='Doe', active=1)

>>> jane.save()

[*] Query: INSERT INTO `user` (`active`, `email`, `first_name`, `last_name`) VALUES (1, '[email protected]', 'Jane', 'Doe');

2

>>> post = Post(title='Hello world!', body='This is my first post!', author=1)

>>> post

{'id': '', 'cnx': , 'title': 'Hello world!', 'body': 'This is my first post!', 'author': 1}

>>> post.save()

[*] Query: INSERT INTO `post` (`title`, `body`, `author`) VALUES ('Hello world!', 'This is my first post!', 1);

1

```



### Updating records



```pycon

>>> john.email = '[email protected]'

>>> john.save()

[*] Query: UPDATE `user` set `active` = 0, `email` = '[email protected]', `first_name` = 'John', `last_name` = 'Doe' WHERE id=1;

1

```



### Retrieving records



```pycon

>>> from models import User, Post

>>> users = User.get_all()

[*] Query: SELECT * FROM `user`;

>>> users

[{'id': 1, 'cnx': , 'email': '[email protected]', 'first_name': 'John', 'last_name': 'Doe', 'active': 0}, {'id': 2, 'cnx': , 'email': '[email protected]', 'first_name': 'Jane', 'last_name': 'Doe', 'active': 1}]

>>> users[0].first_name

'John'

>>> jane = User.get(2)

[*] Query: SELECT * FROM `user` WHERE id='2';

>>> jane

{'id': 2, 'cnx': , 'email': '[email protected]', 'first_name': 'Jane', 'last_name': 'Doe', 'active': 1}

>>> results = User.get_by('first_name', 'John')

[*] Query: SELECT * FROM `user` WHERE first_name='John';

>>> results

[{'id': 1, 'cnx': , 'email': '[email protected]', 'first_name': 'John', 'last_name': 'Doe', 'active': 0}]

>>> Post.users_posts('[email protected]')

[*] Query: SELECT * FROM `post` WHERE `author`=(SELECT id from `user` WHERE email='[email protected]');

[{'id': 1, 'cnx': , 'title': 'Hello world!', 'body': 'This is my first post!', 'author': 1}]

```



## Contribute



All kinds of contribution are welcome.



- Issue Tracker — https://github.com/ormvana/issues

- Source Code — https://github.com/ormvana



## License



This project is licensed under the MIT license.