<commit_before>django-pgjson documentation
===========================
<NAME>, <<EMAIL>>
0.1.0, 2014-04-17

:toc:
:numbered:


Introduction
------------

_django-pgjson_ is a little library that add a bridge for PostgreSQL json field to Django.

Is a little brother of link:https://github.com/djangonauts/django-hstore[django-hstore]

Project Maturity
----------------

Since _django-pgjson_ is a young project there can be some API breakage.

Install
-------

This section covers a installing _django-pgjson_ and its requirements.

Requirements
~~~~~~~~~~~~

- Python 2.7 or 3.3+
- Django 1.6 and 1.7
- psycopg2 2.5.0+
- PostgreSQL 9.2+

Limitations
~~~~~~~~~~~

- Only supports PostgreSQL >= 9.2
- Can not be used with other backends, it explictly use psycopg2 extensions system for
  handling with json.
- Only handles python dicts at this momment (should be improved in future releases).
- No custom lookups for django 1.7 (should be improved in future releases).

Stable
~~~~~~

[source, bash]
----
pip install django-pgjson
----

Development
~~~~~~~~~~~

[source, bash]
----
pip install -e git+git://github.com/niwibe/django-pgjson#egg=django-pgjson
----

Setup
-----

No additional steps are required, just use a field.


Note to South users
~~~~~~~~~~~~~~~~~~~

If you keep getting errors like There is no South database module 'south.db.None'
for your database., add the following to settings.py:

[source, python]
----
SOUTH_DATABASE_ADAPTERS = {'default': 'south.db.postgresql_psycopg2'}
----

Usage
-----

The library provides this class:

- `django_pgjson.fields.JsonField` +
  An ORM field which stores python dict in an json type column.


Model setup
~~~~~~~~~~~

.Model definition is straightforward:
[source, python]
----
from django.db import models
from django_pgjson.fields import JsonField

class Something(models.Model):
    name = models.CharField(max_length=32)
    data = JsonField()  # can pass attributes like null, blank, ecc.
----

Now `data` attribute works like python standard dictionary.

WARNING: PostgreSQL json field also can store arrays and any json valid value
but, django_pgjson at this momment only handles python dict.


Querying
~~~~~~~~

At this momment, no custom lookups are implemented for json field and PostgreSQL 9.3
(the current stable release) does not have much operators for json field. On PostgreSQL 9.4
json type is improved a lot and much other operators are added.

.Simple query using *extra*
[source, python]
----
# Lookup by "name" field on json object
Something.objects.extra(where=["data->>'name' = %s"], params=["foo"])
----


Developers
----------

Running tests
~~~~~~~~~~~~~

Assuming one has the dependencies installed, and a PostgreSQL 9.0+ server up and running:<commit_msg>Minor documentation change.<commit_after>django-pgjson documentation
===========================
<NAME>, <<EMAIL>>
0.1.2, 2014-04-17

:toc:
:numbered:


Introduction
------------

_django-pgjson_ is a little library that add a bridge for PostgreSQL json field to Django.

Is a little brother of link:https://github.com/djangonauts/django-hstore[django-hstore]

Project Maturity
----------------

Since _django-pgjson_ is a young project there can be some API breakage.

Install
-------

This section covers a installing _django-pgjson_ and its requirements.

Requirements
~~~~~~~~~~~~

- Python 2.7 or 3.3+
- Django 1.6 and 1.7
- psycopg2 2.5.0+
- PostgreSQL 9.2+

Supports
~~~~~~~~

- All json types. Including simple strings, floats, integers, booleans and null's.
- Works well with python serialization.

Limitations
~~~~~~~~~~~

- Only supports PostgreSQL >= 9.2
- No django admin support at this momment.
- No custom lookups for django 1.7 (should be improved in future releases).

Stable
~~~~~~

[source, bash]
----
pip install django-pgjson
----

Development
~~~~~~~~~~~

[source, bash]
----
pip install -e git+git://github.com/niwibe/django-pgjson#egg=django-pgjson
----

Setup
-----

No additional steps are required, just use a field.


Note to South users
~~~~~~~~~~~~~~~~~~~

If you keep getting errors like There is no South database module 'south.db.None'
for your database., add the following to settings.py:

[source, python]
----
SOUTH_DATABASE_ADAPTERS = {'default': 'south.db.postgresql_psycopg2'}
----

Usage
-----

The library provides this class:

- `django_pgjson.fields.JsonField` +
  An ORM field which stores python dict in an json type column.


Model setup
~~~~~~~~~~~

.Model definition is straightforward:
[source, python]
----
from django.db import models
from django_pgjson.fields import JsonField

class Something(models.Model):
    name = models.CharField(max_length=32)
    data = JsonField()  # can pass attributes like null, blank, ecc.
----

Now `data` attribute works like python standard dictionary.

WARNING: PostgreSQL json field also can store arrays and any json valid value
but, django_pgjson at this momment only handles python dict.


Querying
~~~~~~~~

At this momment with postgresql 9.3 as last stable version it has very limited set
of native operators for json type (with 9.4 much other operators will added).

If you are using django 1.7, you can use index or key lookup for filtering:

[source, pycon]
----
>>> Something.object.bulk_create([
...     Something(data={"name": "foo"}),
...     Something(data={"name": "bar"})
... ])
>>> Something.objects.filter(data__at_name="foo").count()
1
----

It also works for array indexes:

[source, pycon]
----
>>> Something.object.bulk_create([
...     Something(data=[1,2,3,4]),
...     Something(data=[4,5,6,7])
... ])
>>> Something.objects.filter(data__at_0=4).count()
1
----

In other case, you can execute queries using postgresql operators thaks tu
django's queryset `.extra()` method:

[source, python]
----
>>> Something.objects.extra(where=["data->>'name' = %s"], params=["foo"]).count()
1
----

NOTE: when postgresql 9.4 is released, more lookups will be added.


Developers
----------

Running tests
~~~~~~~~~~~~~

Assuming one has the dependencies installed, and a PostgreSQL 9.0+ server up and running:
{'fraction_non_alphanumeric': 0.15672997522708507, 'fraction_numerical': 0.015524360033030553, 'mean_word_length': 3.669236700077101, 'pattern_counts': {'":': 2, '<': 9, '<?xml version=': 0, '>': 30, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3777612', 'n_tokens_mistral': 1909, 'n_tokens_neox': 1796, 'n_words': 676}