Metadata-Version: 2.1
Name: django-ulid
Version: 0.0.2
Summary: Universally Unique Lexicographically Sortable Identifier (ULID) support in Django
Home-page: https://github.com/ahawker/django-ulid
Author: Andrew Hawker
Author-email: andrew.r.hawker@gmail.com
License: Apache 2.0
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Django
Classifier: Framework :: Django :: 1.11
Classifier: Framework :: Django :: 2.1
Classifier: Framework :: Django :: 2.2
Classifier: Framework :: Django :: 3.0
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.5
Requires-Dist: Django (>=2.1)
Requires-Dist: ulid-py (>=0.0.9)

django-ulid
===========

`Universally Unique Lexicographically Sortable Identifier
(ULID) <https://github.com/alizain/ulid>`__ support in
`Django <https://www.djangoproject.com/>`__.

Status
~~~~~~

This project is actively maintained.

Installation
~~~~~~~~~~~~

To install django-ulid from `pip <https://pypi.python.org/pypi/pip>`__:

.. code:: bash

       $ pip install django-ulid

To install ulid from source:

.. code:: bash

       $ git clone git@github.com:ahawker/django-ulid.git
       $ cd django-ulid && python setup.py install

Usage
~~~~~

Adding a ULID field to your Django models is straightforward. It can be
a normal field or a primary key.

.. code:: python

   from django.db import models
   from django_ulid.models import default, ULIDField

   class Person(models.Model):
       id = ULIDField(default=default, primary_key=True, editable=False)

Passing in ``default`` to the ``ULIDField`` will automatically create a
default value using the
`ulid.new <https://ulid.readthedocs.io/en/latest/api.html#ulid.api.new>`__
function. If you do not want a default value, ``None`` by default, feel
free to omit it.

.. code:: python

   from django.db import models
   from django_ulid.models import ULIDField

   class Person(models.Model):
       optional_id = ULIDField()

Adding a ULID field to your `Django REST
Framework <https://www.django-rest-framework.org/>`__ serializers is
also straightforward.

Simply importing the ``django_ulid.serializers`` module will
automatically register the ``ULIDField`` serializer by overriding the
`serializer_field_mapping <https://www.django-rest-framework.org/api-guide/serializers/#customizing-field-mappings>`__
on the default
`ModelSerializer <https://www.django-rest-framework.org/api-guide/serializers/#modelserializer>`__.

.. code:: python

   from django_ulid import serializers

If you are using a ULID as a primary key on a model, you need to create
a custom
`PrimaryKeyRelatedField <https://www.django-rest-framework.org/api-guide/relations/#primarykeyrelatedfield>`__
to automatically serialize the instance through the foreign key.

.. code:: python

   import functools
   from django_ulid.serializers import ULIDField
   from rest_framework import serializers

   PersonPrimaryKeyRelatedField = functools.partial(serializers.PrimaryKeyRelatedField,
                                                    allow_null=True,
                                                    allow_empty=True,
                                                    pk_field=ULIDField(),
                                                    queryset=Person.objects.all())

   class OrganizationSerializer(serializers.ModelSerializer):
       owner = PersonPrimaryKeyRelatedField()

Contributing
~~~~~~~~~~~~

If you would like to contribute, simply fork the repository, push your
changes and send a pull request. Pull requests will be brought into the
``master`` branch via a rebase and fast-forward merge with the goal of
having a linear branch history with no merge commits.

License
~~~~~~~

`Apache 2.0 <LICENSE>`__

Dependencies
~~~~~~~~~~~~

-  `Django <https://github.com/django/django>`__
-  `ulid-py <https://github.com/ahawker/ulid>`__


