django-smalluuid
================

.. image:: https://img.shields.io/pypi/v/django-smalluuid.svg
    :target: https://pypi.python.org/pypi/django-smalluuid/

.. image:: https://img.shields.io/pypi/dm/django-smalluuid.svg
    :target: https://pypi.python.org/pypi/django-smalluuid/

.. image:: https://img.shields.io/github/license/adamcharnock/django-smalluuid.svg
    :target: https://pypi.python.org/pypi/django-smalluuid/

.. image:: https://img.shields.io/travis/adamcharnock/django-smalluuid.svg
    :target: https://travis-ci.org/adamcharnock/django-smalluuid/

.. image:: https://coveralls.io/repos/adamcharnock/django-smalluuid/badge.svg?branch=master
    :target: https://coveralls.io/r/adamcharnock/django-smalluuid?branch=master



Installation
------------

Installation using pip::

    pip install django-smalluuid

Basic Usage
-----------

To get started use the ``SmallUUIDField`` field in your model definitions:

.. code-block:: python

    from django.db import models
    from django_smalluuid.models import SmallUUIDField, uuid_default

    class ExampleModel(models.Model):
        uuid = SmallUUIDField(default=uuid_default())

The field provides values as instances of ``SmallUUID`` (see smalluuid_):

.. code-block:: python

    >>> obj = ExampleModel.objects.create()

    # The initial UUID has been auto-generated by uuid_default()
    >>> obj.uuid
    SmallUUID('T1q_P6HcQNSyW6tpqJTxww')

    # It is still available in the groupex hex form (if needed)
    >>> obj.hex_grouped
    '4f5abf3f-a1dc-40d4-b25b-ab69a894f1c3'

    # Filtering is done on the shortened UUIDs
    >>> ExampleModel.objects.filter(uuid='T1q_P6HcQNSyW6tpqJTxww')
    [<ExampleModel: ExampleModel object>]


Typed Usage
-----------

``django-smalluuid`` also supports the Typed UUID's as provided by smalluuid_. This
allows for the object's type to be stored within the UUID.

Updating the above example:

.. code-block:: python

    from django.db import models
    from django_smalluuid.models import SmallUUIDField, uuid_typed_default

    class TypedExampleModel(models.Model):
        uuid = SmallUUIDField(default=uuid_typed_default(type=42))

Which can be interacted with as follows:

.. code-block:: python

    >>> obj = TypedExampleModel.objects.create()
    >>> obj.uuid
    TypedSmallUUID('qvyk8nzbQfu8zAnTPQweyw')
    >>> obj.uuid.type
    42


Credits
-------

django-smalluuid is packaged using seed_ and relies upon smalluuid_.

.. _seed: https://github.com/adamcharnock/seed/
.. _smalluuid: https://github.com/adamcharnock/smalluuid
