Welcome to asyncorm’s documentation!

Contents:

asyncOrm

Pypi package Python versions build status Code quality Coverage Packages status Build status Documentation Status Code style

A fully asynchronous python ORM

Features

WARNING: version prebeta !!

WARNING: Work In Progress !!

AsyncORM is a fully async ORM inspired by the fantastic django orm

AsyncORM currently only supports postgres, but its developed to be “easy” to plug a number of different database interfaces.

It is designed to be used with any async library, but with sanic in mind.

To do

A number of things are needed to be able to release asyncOrm as a production ready ORM:

  • better the documentation!
  • migration support (forward migration at least)
  • other databases interfaces ( mysql / mariaDb first priority)
  • prefetch_related functionality
  • Missing Field types: OneToOneField

Dependencies

AsyncOrm currently only depends on AsyncPg and netaddr.

asyncpg, is a database interface library designed specifically for PostgreSQL and Python/asyncio.

netaddr, A network address manipulation library for Python

Credits

This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.

Installation

Development(current) release

To install asyncorm, run this command in your terminal:

$ pip install asyncorm

This is the preferred method to install asyncorm, as it will always install the most recent stable release.

If you don’t have pip installed, this Python installation guide can guide you through the process.

From sources

The sources for asyncorm can be downloaded from the Github repo.

You can either clone the public repository:

$ git clone git://github.com/monobot/asyncorm

Or download the tarball:

$ curl  -OL https://github.com/monobot/asyncorm/tarball/pypi_version

Once you have a copy of the source, you can install it with:

$ python setup.py install

Usage

configure

To be able to use asyncOrm you have to provide database, the loop and the modules where the models are defined. For that we provide a configure_orm function that will return the already configured orm you will use on the whole application

Asyncorm can be configured like this, using a simple dictionary and so passing forward the data needed.

from asyncorm import configure_orm

db_config = {
    'database': 'sanic_example',
    'host': 'localhost',
    'port': '5432',
    'user': 'ormdbuser',
    'password': 'ormDbPass',
}

configure_orm({
    'loop': loop,  # always use the whole application loop!
    'db_config': db_config,
    'apps': ['library', ],  # list of apps
})

But it is recomended to use the .ini approach, so if you dont pass the configuration as a dictionary it will expect it to be the absolute path to the .ini file that contents that data, the reason for that .ini file. If None is provided then will default to same directory and “asyncorm.ini”.

from asyncorm import configure_orm

configure_orm('/path/to/asyncorm.ini')

AsyncOrm should be configured once and only once in every project, and preferibly before everything really starts. Also make sure that the async loop is be the same your application uses.

Thats all! As you can see its very simple to configure asyncOrm, as long as you provide the needed information, asyncOrm will take care of inspecting the modules and detect all the models declared inside them. So you can then retrieve them both with direct imports or using the provided convenience get_model function (recomended):

from asyncorm import get_model

Book = get_model('Book')
# or
Author = get_model('app.Author')

Understand that all the magic on the ORM is made behind scenes, in fact that function is just a wrapper around the method existent in the ORM. Most of the times you will not need to act on the ORM after the basic configuration.

Please find the full example for sanic that you will find in the repository, so you can see how easy it is to work with asyncOrm.

create tables

Once asyncOrm is configured you can create all the tables for the defined models in different apps declared in the configuration.

We are planing to create a migration system so its possible to migrate the different database states.

To create all the tables:

# use the orm_app obtained in the previous configure_orm command
orm_app.sync_db()

Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions

Report Bugs

Report bugs at https://github.com/monobot/asyncorm/issues.

If you are reporting a bug, please include:

  • Your operating system name and version.
  • Any details about your local setup that might be helpful in troubleshooting.
  • Detailed steps to reproduce the bug.

Fix Bugs

Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wants to implement it.

Implement Features

Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open to whoever wants to implement it.

Write Documentation

asyncorm could always use more documentation, whether as part of the official asyncorm docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback

The best way to send feedback is to file an issue at https://github.com/monobot/asyncorm/issues.

If you are proposing a feature:

  • Explain in detail how it would work.
  • Keep the scope as narrow as possible, to make it easier to implement.
  • Remember that this is a volunteer-driven project, and that contributions are welcome :)

Get Started!

Ready to contribute? Here’s how to set up asyncorm for local development.

  1. Fork the asyncorm repo on GitHub.

  2. Clone your fork locally:

    $ git clone git@github.com:your_name_here/asyncorm.git

  3. The recomended install form is with pipenv:

    $ cd asyncorm/
$ pipenv install --dev

  4. As alternative, you can also install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:

    $ mkvirtualenv asyncorm
$ cd asyncorm/
$ python setup.py develop

  5. Create a branch for local development:

    $ git checkout -b name-of-your-bugfix-or-feature

    Now you can make your changes locally.

  6. When you’re done making changes, check that your changes pass al existing tests, including testing other Python versions with tox:

    $ python -m tests

  7. Make sure that your code style is black compliant:

    check with $ black –check –verbose .

    or let black make it for you $ black .

  8. Commit your changes and push your branch to GitHub:

    $ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature

  9. Submit a pull request through the GitHub website.

Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

  1. The pull request should include tests.
  2. If the pull request adds functionality, the docs should be updated.
  3. The pull request should work for both Python 3.5 and 3.6. Check https://travis-ci.org/monobot/asyncorm/pull_requests and make sure that the tests pass for all supported Python versions.

Credits

Development Lead

Contributors

Many thanks to all the contributors that give me the illusion of keep on working.

1 https://github.com/kejkz
  • Added support for array and text Fields
2 https://github.com/Kylmakalle
  • SQL queries rework
3 https://github.com/kitlycol
  • added FloatField

History

0.4.6 (2019-3-3) * Mismatched versions fixed.

0.4.5 (2019-3-3) * enrich docstrings, better documentation, clean up Makefiles.

0.4.4 (2019-1-13) * requirements update

0.4.3 (2019-1-13) * requirements update, uploaded to PyPi

0.4.2 (2019-1-13) * pipenv support, uploaded to PyPi

0.4.1 (2018-7-31) * uploaded to PyPi

0.4.0 (2018-7-29) * added python3.7 support, added CI tools

0.3.9 (2018-1-10) * remove python3.8 mistake

0.3.8 (2018-1-10) * heavy works in migrations, basic setup completed

0.3.7 (2018-1-10) * minor release because of change in parsing the asyncorm.ini

0.3.6 (2018-1-2) * external import fix

0.3.5 (2017-12-27) * GenericIPAddressField, MACAdressField included

0.3.4 (2017-12-27) * ArrayField, TextField, also allow db_index for any kind of fields

0.3.3 (2017-06-25) * DateField, DateTimeField, TimeField, UuidField and more work on migrations

0.3.2 (2017-06-16) * setup process drafted

0.3.1 (2017-06-15) * setup process drafted

0.3.0 (2017-06-14) * solving package problem

0.2.9 (2017-06-14) * solving package problem

0.2.8 (2017-06-14) * solving package problem

0.2.7 (2017-06-14) * solving package problem

0.2.6 (2017-06-14) * Remove log from distribution package

0.2.5 (2017-06-14) * Many changes, paving the migration system, modify configure to allow .ini files

0.2.0 (2017-05-28) * new module setup unit tests using AAA, select_related functional, working on migrations

0.1.1 (2017-05-19) * increase the number of lookups, database lookup calculation, better queryset setup

0.1.0 (2017-05-19) * more solid state, added coverage

0.0.10 (2017-05-13) * querysets, slices and indices implemented

0.0.9 (2017-05-11) * lazy requests for querysets

0.0.8 (2017-04-03) * everything more mature including jsonfield

0.0.7 (2017-03-27) * ordering on all db requests, sanic example updated

0.0.6 (2017-03-26) * sanic example working

0.0.5 (2017-03-24) * sanic example working, get, post, delete working, missing patch, and put

0.0.4 (2017-03-23) * wrong manifest corrected

0.0.3 (2017-03-23) * config implemented

0.0.2 (2017-03-02) * Small update, include log

0.0.1 (2017-03-02) * First release on PyPi.

Indices and tables