Metadata-Version: 2.0
Name: orderby
Version: 0.0.2
Summary: Python key functions for multi-field ordering
Home-page: https://github.com/jvtm/python-orderby
Author: Jyrki Muukkonen
Author-email: jvtm@kruu.org
License: Apache 2.0
Keywords: sort order orderby development
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5

orderby
=======

Python key functions for multi-field ordering in SQL ORDER BY fashion

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

Meant to be used with built-in ``sorted()`` *key function*.

Supports also ``list.sort()`` doing *in-place sorting*.

Implementation uses ``operator.itemgetter()`` + some internal helper classes to allow descending sorting order.

So far this is tested and used on *lists of dictionaries*. Adding support for named tuples and others would
be possible (using ``operator.attrgetter()``).


Usage
-----

- SQL-like: ``orderby('foo ASC, bar DESC')``
- chained: ``asc('foo').desc('bar')`` usage
- multiple fields at once: ``asc('foo', 'bar')``


Examples
--------

``orderby()`` string syntax:

.. code-block:: python

    >>> from orderby import orderby
    >>> import json
    >>> files = [
    ...   {'size': 1234, 'path': 'foo/bar.txt'},
    ...   {'size': 0, 'path': '/dev/null'},
    ...   {'size': 1234, 'path': 'foo/abc.bin'},
    ... ]
    >>> print(json.dumps(sorted(files, key=orderby('size DESC, path')), indent=2))
    [
      {
        "size": 1234,
        "path": "foo/abc.bin"
      },
      {
        "size": 1234,
        "path": "foo/bar.txt"
      },
      {
        "size": 0,
        "path": "/dev/null"
      }
    ]


Chained `asc()` and `desc()` usage:

.. code-block:: python

    >>> from orderby import asc, desc
    >>> print(json.dumps(sorted(files, key=desc('size').asc('path')), indent=2))
    [
      {
        "size": 1234,
        "path": "foo/abc.bin"
      },
      {
        "size": 1234,
        "path": "foo/bar.txt"
      },
      {
        "size": 0,
        "path": "/dev/null"
      }
    ]


In-place sorting of a list:

.. code-block:: python

    >>> files.sort(key=desc('path'))
    >>> print(json.dumps(files, indent=2))
    [
      {
        "size": 1234,
        "path": "foo/bar.txt"
      },
      {
        "size": 1234,
        "path": "foo/abc.bin"
      },
      {
        "size": 0,
        "path": "/dev/null"
      }
    ]
    >>> files.sort(key=desc('size').asc('path'))
    >>> print(json.dumps(files, indent=2))
    [
      {
        "size": 1234,
        "path": "foo/abc.bin"
      },
      {
        "size": 1234,
        "path": "foo/bar.txt"
      },
      {
        "size": 0,
        "path": "/dev/null"
      }
    ]

Internals
---------

To be explained here later...


