Metadata-Version: 2.1
Name: django-ormex
Version: 0.2.1
Summary: Django ORM extensions
Home-page: https://github.com/barseghyanartur/django-ormex/
Author: Artur Barseghyan
Author-email: artur.barseghyan@gmail.com
License: GPL-2.0-only OR LGPL-2.1-or-later
Keywords: django,ORM
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Environment :: Web Environment
Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
Classifier: License :: OSI Approved :: GNU Lesser General Public License v2 or later (LGPLv2+)
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Requires-Dist: six (>=1.9)
Requires-Dist: django-nine (>=0.2.2)

============
django-ormex
============
Django ORM extensions.

.. image:: https://img.shields.io/pypi/v/django-ormex.svg
   :target: https://pypi.python.org/pypi/django-ormex
   :alt: PyPI Version

.. image:: https://img.shields.io/pypi/pyversions/django-ormex.svg
    :target: https://pypi.python.org/pypi/django-ormex/
    :alt: Supported Python versions

.. image:: https://img.shields.io/travis/barseghyanartur/django-ormex/master.svg
   :target: http://travis-ci.org/barseghyanartur/django-ormex
   :alt: Build Status

.. image:: https://img.shields.io/badge/license-GPL--2.0--only%20OR%20LGPL--2.1--or--later-blue.svg
   :target: https://github.com/barseghyanartur/django-ormex/#License
   :alt: GPL-2.0-only OR LGPL-2.1-or-later

.. image:: https://coveralls.io/repos/github/barseghyanartur/django-ormex/badge.svg?branch=master&service=github
    :target: https://coveralls.io/github/barseghyanartur/django-ormex?branch=master
    :alt: Coverage

Prerequisites
=============
- Django 1.11, 2.2 and 3.0.
- Python 2.7, 3.5, 3.6, 3.7 and 3.8

Supported databases
===================
PostgreSQL, MySQL, SQLite

Installation
============
Install in your virtual environment.

Latest stable version from PyPI:

.. code-block:: sh

    pip install django-ormex

Latest stable version from GitHub:

.. code-block:: sh

    pip install https://github.com/barseghyanartur/django-ormex/archive/stable.tar.gz

Usage
=====
Common usage examples.

Aggregations
------------
Contains various modules for aggregations.

GroupConcat
~~~~~~~~~~~
Works like Concat, but for concatenating field values of related ManyToMany
model. For instance, you may use it if you have an ``Author`` model as
ManyToMany relation in the ``Book`` model
(``Book.authors = ManyToManyField(Author)``) and you want to have concatenated
list of all authors coupled to a given book.

Given the following models:

.. code-block:: python

    class Publisher(models.Model):
        """Publisher."""

        name = models.CharField(max_length=255)
        address = models.CharField(max_length=255)
        city = models.CharField(max_length=255)
        state_province = models.CharField(max_length=255)
        country = models.CharField(max_length=255)
        website = models.URLField(max_length=255)


    class Author(models.Model):
        """Author."""

        salutation = models.CharField(max_length=255)
        name = models.CharField(max_length=255)
        email = models.EmailField(max_length=255)
        headshot = models.ImageField(upload_to='authors', null=True, blank=True)


    class Book(models.Model):
        """Book."""

        title = models.CharField(max_length=255)
        authors = models.ManyToManyField('books.Author', related_name='books')
        publisher = models.ForeignKey(Publisher, related_name='books')
        publication_date = models.DateField()
        isbn = models.CharField(max_length=255, unique=True)
        price = models.DecimalField(max_digits=10, decimal_places=2)
        pages = models.PositiveIntegerField(default=200)
        stock_count = models.PositiveIntegerField(default=30)

We could use GroupConcat as follows:

.. code-block:: python

    from ormex.aggregations import GroupConcat

    book = Book.objects.all() \
            .values('id',
                    'title',
                    'pages',
                    'price',
                    'publisher__id',
                    'publisher__name') \
            .annotate(
                authors__name=GroupConcat('authors__name', separator=', ')
            ) \
            .first()

Output would look as follows:

.. code-block:: python

    {
        'authors__name': 'Finn Janssen, Dan Dijkman, Merel Wolf, Evy de Jong',
        'id': 14,
        'pages': 83,
        'price': Decimal('62.13'),
        'publisher__id': 19,
        'publisher__name': 'Rijn, de Bruyn and Verharen',
        'title': 'Laboriosam officia temporibus facere omnis odit.'
    }

``GroupConcat`` accepts an optional argument ``order_by`` which can be used
for tuning the sorting order of the resulted list of strings. In case if
``self`` is given as value, sorted by the same field. In order to sort the
list of authors by name from the example above, do:

.. code-block:: python

    book = Book.objects.all() \
            .values('id',
                    'title',
                    'pages',
                    'price',
                    'publisher__id',
                    'publisher__name') \
            .annotate(
                authors__name=GroupConcat('authors__name',
                                          separator=', ',
                                          order_by='self')
            ) \
            .first()


Output would look as follows:

.. code-block:: python

    {
        'authors__name': 'Dan Dijkman, Evy de Jong, Finn Janssen, Merel Wolf',
        'id': 14,
        'pages': 83,
        'price': Decimal('62.13'),
        'publisher__id': 19,
        'publisher__name': 'Rijn, de Bruyn and Verharen',
        'title': 'Laboriosam officia temporibus facere omnis odit.'
    }

Demo
====
Run demo locally
----------------
In order to be able to quickly evaluate the `django-ormex`, a demo
app (with a quick installer) has been created (works on Ubuntu/Debian, may
work on other Linux systems as well, although not guaranteed). Follow the
instructions below to have the demo running within a minute.

Grab the latest ``ormex_demo_installer.sh``:

.. code-block:: sh

    wget -O - https://raw.github.com/barseghyanartur/django-ormex/stable/examples/ormex_demo_installer.sh | bash

Open your browser and test the app.

- URL: http://127.0.0.1:8001/

If quick installer doesn't work for you, see the manual steps on running the
`example project
<https://github.com/barseghyanartur/django-ormex/tree/stable/examples>`_.

Testing
=======
Simply type:

.. code-block:: sh

    ./runtests.py

or use tox:

.. code-block:: sh

    tox

or use tox to check specific env:

.. code-block:: sh

    tox -e py35

or run Django tests:

.. code-block:: sh

    ./manage.py test ormex --settings=settings.testing

License
=======
GPL-2.0-only OR LGPL-2.1-or-later

Support
=======
For any issues contact me at the e-mail given in the `Author`_ section.

Author
======
Artur Barseghyan <artur.barseghyan@gmail.com>


