===================
django-pgfields 1.0
===================

Welcome to django-pgfields 1.0!

Overview
--------

This release is considered the first true, stable release of
django-pgfields. It adds sufficient support for tools within the Django
ecosystem (gis, south) to be usable, and all documented aspects of the
module should not change at this point, except to accomodate a substantial
change in Django itself.

This release of django-pgfields contains the following major features:

Features
--------

* Added `GeoDjango support <#geodjango-support>`_.
* Added an `improved repr <#improved-repr>`_ implementation to Model.


GeoDjango Support
-----------------

django-pgfields 1.0 resolves a previously-existing conflict between
django-pgfields and GeoDjango (``django.contrib.gis``).

Because both django-pgfields and GeoDjango implement their additional features
by subclassing several classes within Django itself, it wasn't possible
to use both of them.

django-pgfields 1.0 removes this limitation by introspecting your database
backend setting and assigning to models an appropriate Manager class. So,
if you are using the ``django.contrib.gis.db.backends.postgis`` backend,
you'll get our GeoManager subclass (without having to specify anything!), while
if you're using the vanilla Django PostgreSQL backend, you'll get our
Manager subclass.

This functionality is provided across-the-board. However, if our introspection
gets it wrong, you can define a ``DJANGOPG_DEFAULT_MANAGER`` setting,
which will be applied to all models in lieu of django-pgfields' introspection.
This is easier than manually assigning a manager to every model.


Improved Repr
-------------

django-pgfields 1.0 provides an improved ``__repr__`` implementation on
the base Model, from which your models inherit.

As this is not the core mission of django-pgfields, this functionality is
provided on an opt-in basis, and will only be activated if you set a particular setting.

For more information, see the
`improved repr documentation <../misc.html#improved-repr>`_.


Minor Improvements
------------------

* If ``auto_add=True`` is set on a UUID field, it now implies
  ``editable=False``. This makes it behave as much like AutoField as possible,
  since a primary key replacement is one of the most likely reasons to use
  ``auto_add`` at all.
* When using an ``ArrayField``, any item that is added to the list
  is automatically coerced to the sub-field's format.
* When a value for a ``CompositeField`` subclass is being coerced to the
  appropriate Python type, all sub-items are coerced as well.
* When using a ``CompositeField``, any item that is added to a key of the
  field is automatically coerced to that key's format.