Metadata-Version: 1.1
Name: django-group-by
Version: 0.3.1
Summary: Group by arbitrary model fields
Home-page: https://github.com/kako-nawao/django-group-by
Author: Claudio Omar Melendrez Baeza
Author-email: claudio.melendrez@gmail.com
License: MIT
Description: ==============
        Django GroupBy
        ==============
        
        .. image:: https://img.shields.io/github/license/kako-nawao/django-group-by.svg
            :target: http://www.opensource.org/licenses/MIT
        
        .. image:: https://img.shields.io/pypi/pyversions/django-group-by.svg
            :target: https://pypi.python.org/pypi/django-group-by
        .. image:: https://img.shields.io/pypi/v/django-group-by.svg
            :target: https://pypi.python.org/pypi/django-group-by
        
        .. image:: https://img.shields.io/travis/kako-nawao/django-group-by.svg
            :target: https://travis-ci.org/kako-nawao/django-group-by
        .. image:: https://img.shields.io/codecov/c/github/kako-nawao/django-group-by.svg
            :target: https://codecov.io/gh/kako-nawao/django-group-by
        
        This package provides a mixin for Django QuerySets that adds a method ``group_by`` that
        behaves mostly like the ``values`` method, but with one difference: its iterator does not
        return dictionaries, but a *model-like object with model instances for related values*.
        
        Installation
        ============
        
        Install from PyPI::
        
            pip install django-group-by
        
        Compatibility
        ~~~~~~~~~~~~~
        
        This package is compatible with Django 1.8, 1.9 and 1.10, and Python versions 2.7, 3.4, 3.5 and 3.6.
        Probably others, but those 12 combinations are the ones against which we build (by Travis CI).
        
        
        Usage
        =====
        
        Create a QuerySet subclass with the ``GroupByMixin`` to use in a model's manager::
        
            # models.py
        
            from django.db import models
            from django.db.models.query import QuerySet
            from django_group_by import GroupByMixin
        
            class BookQuerySet(QuerySet, GroupByMixin):
                pass
        
            class Book(Model):
                objects = BookQuerySet.as_manager()
        
                title = models.CharField(max_length=100)
                author = models.ForeignKey('another_app.Author')
                publication_date = models.DateField()
            ...
        
        Then use it just like ``values``, and you'll get a similar query set::
        
            >>> some_rows = Book.objects.group_by('title', 'author', 'author__nationality').distinct()
            >>> some_rows.count()
            4
        
        The difference is that every row is not a dictionary but an AggregatedGroup instance, with only the grouped fields::
        
            >>> row = some_rows[0]
            >>> row
            <AggregatedGroup for Book>
            >>> row.title
            The Colour of Magic
            >>> row.publication_date
            *** AttributeError: 'AggregatedGroup' object has no attribute 'publication_date'
        
        But of course the main advantage is that you also get related model instances, as far as you want::
        
            >>> row.author
            <Author: Terry Pratchett>
            >>> row.author_nationality
            <Nation: Great Britain>
        
        
        Related Model ID Only
        ~~~~~~~~~~~~~~~~~~~~~
        
        The previous example shows a difference in behaviour from Django's ``values``: we're grouping by the foreign key
        *author*, but instead of getting only the ID we get the full instance. Why? Because it's more useful, and I
        think that getting *{'author': 5}* as a result is just weird.
        
        If you just want the ID you can specify it::
        
            >>> some_rows = Book.objects.group_by('title', 'author_id', 'author__nationality_id').distinct()
        
        
Keywords: django grouping values models
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Plugins
Classifier: Framework :: Django :: 1.8
Classifier: Framework :: Django :: 1.9
Classifier: Framework :: Django :: 1.10
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: Software Development
