helo

==== helo

🌎 [English </README.rst>] ∙ [简体中文 </README.CN.rst>]

.. image:: https://img.shields.io/pypi/v/helo.svg :target: https://pypi.python.org/pypi/helo

.. image:: https://travis-ci.org/at7h/helo.svg?branch=master :target: https://travis-ci.org/at7h/helo

.. image:: https://coveralls.io/repos/github/at7h/helo/badge.svg?branch=master :target: https://coveralls.io/github/at7h/helo?branch=master

.. image:: https://app.codacy.com/project/badge/Grade/c68578653eb546488fadddd95f19939c :target: https://www.codacy.com/manual/at7h_/helo?utm_source=github.com&utm_medium=referral&utm_content=at7h/helo&utm_campaign=Badge_Grade

.. image:: https://img.shields.io/pypi/pyversions/helo :target: https://img.shields.io/pypi/pyversions/helo :alt: PyPI - Python Version

Helo is a simple and small low-level asynchronous ORM using Python asyncio_. It is very intuitive and easy to use.

Helo can help you easily build expressive common SQL statements in your asynchronous applications. You only need to use friendly object-oriented APIs to manipulate data without caring about the details of SQL statement writing and data processing.

• Requires: Python 3.7+

• Now only supports MySQL, and the version is 5.7+

• Integration with web Framework:

  • quart_, see with quart <#with-quart>_

• Not supports table relationship

Quickstart

See the wiki_ page for more information and quickstart_ documentation.

Installation

.. code-block:: bash

$ pip install helo

See the installation_ wiki page for more options.

Basic Examples

First, you should to import helo and instantiate a global variable with helo.G

.. code-block:: python

import helo

db = helo.G()

Defining models is simple:

.. code-block:: python

class Author(helo.Model):
    id = helo.BigAuto()
    name = helo.VarChar(length=45, null=False)
    email = helo.Email(default='')
    password = helo.VarChar(length=100, null=False)
    create_at = helo.Timestamp(default=helo.ON_CREATE)


class Post(helo.Model):
    id = helo.Auto()
    title = helo.VarChar(length=100)
    author = helo.Int(default=0)
    content = helo.Text(encoding=helo.ENCODING.UTF8MB4)
    create_at = helo.Timestamp(default=helo.ON_CREATE)
    update_at = helo.Timestamp(default=helo.ON_UPDATE)

Show some basic examples:

.. code-block:: python

import asyncio
import datetime


async def show_case():
    # Binding the database(creating a connection pool)
    await db.bind('mysql://user:password@host:port/db')
    # Creating tables
    await db.create_tables([Author, Post])

    # Inserting few rows:

    author = Author(name='at7h', password='1111')
    author_id = await author.save()
    print(author_id)  # 1

    authors = await Author.get(author_id)
    print(author.id, author.name)  # 1, at7h

    await Author.update(email='[e-mail]').where(Author.id == author_id).do()

    ret = await Author.insert(name='pope', password='2222').do()
    posts = [
        {'title': 'Python', 'author': 1},
        {'title': 'Golang', 'author': 2},
    ]
    ret = await Post.minsert(posts).do()
    print(ret)  # (2, 1)

    # Supports expressive and composable queries:

    count = await Author.select().count()
    print(count) # 2

    # Last gmail author
    author = await Author.select().where(
        Author.email.endswith('gmail.com')
    ).order_by(
        Author.create_at.desc()
    ).first()
    print(author) # [<Author object at 1>]

    # Using `helo.adict`
    authors = await Author.select(
        Author.id, Author.name
    ).where(
        Author.id < 2
    ).all(wrap=False)
    print(author)  # [{'id': 1, 'name': 'at7h'}]

    # Paginate get authors who wrote Python posts this year
    authors = await Author.select().where(
        Author.id.in_(
            Post.select(Post.author).where(
                Post.update_at > datetime.datetime(2019, 1, 1),
                Post.title.contains('Python')
            ).order_by(
                Post.update_at.desc()
            )
        )
    ).paginate(1, 10)
    print(authors) # [<Author object at 1>]

    # How many posts each author wrote?
    author_posts = await Author.select(
        Author.name, helo.F.COUNT(helo.SQL('1')).as_('posts')
    ).join(
        Post, helo.JOINTYPE.LEFT, on=(Author.id == Post.author)
    ).group_by(
        Author.name
    ).rows(100)

asyncio.run(show_case())

With Quart

If you're using quart_ , a minimum application example should be:

.. code-block:: python

import quart
import helo

app = quart.Quart(__name__)
app.config["HELO_DATABASE_URL"] = "mysql://user:password@127.0.0.1:3306/db"

db = helo.G(app)


@app.route('/api/authors')
async def authors():
    await Author.insert(
        name='at7h', email='[e-mail]', password='xxxx'
    ).do()
    author_list = await Author.select().all(False)
    return quart.jsonify(author_list)


app.run()

Start it:

.. code-block:: bash

$ curl http://127.0.0.1:5000/api/authors
[{"email":"[e-mail]","id":1,"name":"at7h","password":"xxxx"}]

👉 See more examples </examples>_

Contributing 👏

I hope those who are interested can join in and work together.

Any kind of contribution is expected: report a bug 🐞, give a advice or create a pull request 🙋‍♂️.

Thanks 🤝

• Special thanks to projects aiomysql_ and peewee_, helo uses aiomysql_ (as the MySQL connection driver), and referenced peewee_ in program design.
• Please feel free to ⭐️ this repository if this project helped you 😉 !

.. _wiki: https://github.com/at7h/helo/wiki .. _quart: https://github.com/pgjones/quart .. _quickstart: https://github.com/at7h/helo/wiki#quickstart .. _installation: https://github.com/at7h/helo/wiki#installation .. _asyncio: https://docs.python.org/3.7/library/asyncio.html .. _aiomysql: https://github.com/aio-libs/aiomysql .. _peewee: https://github.com/coleifer/peewee