This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
Project Description
# hstore-field

hstore-field is a library which integrates the
[`hstore`](http://www.postgresql.org/docs/9.0/interactive/hstore.html)
extension of PostgreSQL into Django, assuming one is using Django 1.3+,
PostgreSQL 9.0+, and Psycopg 2.3+.

hstore-field draws some inspiration from
[jordanm/django-hstore](http://github.com/jordanm/django-hstore) and
[niwibe/django-orm-extensions](https://github.com/niwibe/django-orm-extensions)
but it uses a completely different mechanism for extending Django, which has the
following advantages:

1. Does not require a custom database backend (at the cost of not supporting
indexes on hstore fields)
1. Does not require a custom QuerySet class, making it fully compatible with
GeoDjango or any other extension that does subclass QuerySet
1. Supports range lookup types in queries (i.e., `__lt`, `__gt`, etc...)
1. Mostly compatible with South (see limitations below for specifics)

## Limitations

- Because we're not using a custom database backend, hstore-field does not
support indexes on hstore fields.
- Only numbers, strings, and dates may be stored in an hstore dictionary.
Hstore-field will convert numbers and dates to strings for you when you write
to the field, but it *will not convert them back* into their original types when
the hstore dictionary is retrieved from the database. You can make a custom
class serialize to hstore by giving it a `to_hstore` method, which must return
a string.
- Hstore-field will automatically try to install configure hstore on any
database you connect to, using the `connection_created` signal. If you connect
to multiple databases, this could present a problem.
- Adding an HStoreField with `null=False` to an existing model using South is
problematic, because South cannot emit the correct SQL for the default. One
workaround is to add the column by putting the SQL directly in the migration

```python
def forwards(self, orm):
db.execute('ALTER TABLE "[table]" ADD COLUMN "[column]" hstore NOT NULL DEFAULT hstore(array[]::varchar[]);')
```

Another alternative is to add the field with `null=True`, populate the field,
then set `null=False`. This is actually considered good practice in general,
because default values can cause unexpected problems.

## Running the tests

```
$ python manage.py test test_hstore_field
```

For this to work
1. hstore must be installed in your PostgreSQL contrib folder
1. If you are running PostgreSQL 9.0, the directory containing `pg_config`
must be on your `PATH`

## Usage

Model definition is straightforward:

```python
from django.db import models
from hstore_field import fields

class Item (models.Model):
name = models.CharField(max_length=64)
data = fields.HStoreField()
```

You then treat the `data` field as a dictionary of string pairs:

```python
instance = Item.objects.create(name='something', data={'a': '1', 'b': '2'})
assert instance.data['a'] == '1'

empty = Item.objects.create(name='empty')
assert empty.data == {}

empty.data['a'] = '1'
empty.save()
assert Item.objects.get(name='something').data['a'] == '1'
```

You can issue queries against hstore keys using the `HQ` class (similar to the `Q` class)

```python
from hstore_field.query import HQ

# return only objects whose dictionary contains a given key...
Item.objects.filter(HQ(data__contains='a'))

# ...or that contain all keys in a given list (or tuple)
Item.objects.filter(HQ(data__contains=['a', 'b']))
```

You can also query against hstore values:

```python
# find by exact value
Item.objects.filter(HQ(data__a='1'])) # equivalent to Item.objects.filter(HQ(data__a__exact='1']))

# subset by list of values
Item.objects.filter(HQ(data__a__in=['1', '2']))

# subset by range query using integer
Item.objects.filter(HQ(data__a__lt=1))

# subset by range query using float
Item.objects.filter(HQ(data__a__gt=1.1))

# subset by range query as timestamp
Item.objects.filter(HQ(data__a__lte=datetime.datetime(2012, 1, 1, 0, 15)))

# subset by range query as date
Item.objects.filter(HQ(data__a__gte=datetime.date(2012, 1, 1)))

# subset by range query as time
Item.objects.filter(HQ(data__a__lte=datetime.time(7, 15)))
```

Note that, when issuing a range query against an hstore key using a non-string
type, any non-null values for that key that cannot be cast to the appropriate
type will cause the query to fail.

`HQ` objects may be combined using `&`, `|`, and `~`, just like `Q` objects. But
they may only be combined with other `HQ` objects, and not with any `Q` objects.
To combine an `HQ` object with a `Q` object, you must first wrap the `HQ` object
in a `Q` object. For example:

```python
Item.objects.filter(HQ(data__a__lt=10) & HQ(data__b__lt=20)) # YES!

Item.objects.filter(Q(HQ(data__a__lt=10)) & Q(data__name="foo")) # YES!

Item.objects.filter(HQ(data__a__lt=10) & Q(data__name="foo")) # NO!
```

Range queries are not especially fast, because they require a table scan and for
every record's hstore->key to be cast from string to another type. However,
it is much faster than shipping the entire table to the application layer as
Django model objects and filtering them there (3-6 times faster in limited testing).

Support for indexing hstore values as numbers and/or dates is planned for a
future release.
Release History

Release History

1.0.2

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

TODO: Brief introduction on what you do with files - including link to relevant help section.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
hstore-field-caseinsensitive-1.0.2.tar.gz (8.6 kB) Copy SHA256 Checksum SHA256 Source Jun 6, 2013

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS HPE HPE Development Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting