Skip to content

Commit

Permalink
updated README to be djangonauts-ready! 👍
Browse files Browse the repository at this point in the history
  • Loading branch information
@nemesifier
nemesifier committed Jan 3, 2014
1 parent ead1030 commit 1906069
Showing 1 changed file with 164 additions and 127 deletions.
291 changes: 164 additions & 127 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,160 +1,186 @@
django-rest-framework-gis
=========================

[![Build Status](https://travis-ci.org/dmeehan/django-rest-framework-gis.png?branch=master)](https://travis-ci.org/dmeehan/django-rest-framework-gis)
[![Coverage Status](https://coveralls.io/repos/dmeehan/django-rest-framework-gis/badge.png)](https://coveralls.io/r/dmeehan/django-rest-framework-gis)
[![Build Status](https://travis-ci.org/djangonauts/django-rest-framework-gis.png?branch=master)](https://travis-ci.org/djangonauts/django-rest-framework-gis)
[![Coverage Status](https://coveralls.io/repos/djangonauts/django-rest-framework-gis/badge.png)](https://coveralls.io/r/djangonauts/django-rest-framework-gis)
[![PyPI version](https://badge.fury.io/py/djangorestframework-gis.png)](http://badge.fury.io/py/djangorestframework-gis)

Geographic add-ons for Django Rest Framework - [Mailing List](https://groups.google.com/forum/#!forum/django-rest-framework-gis).


Install
-------

```bash
pip install djangorestframework-gis
```

Geographic add-ons for Django Rest Framework

Fields
------

Provides a GeometryField, which is a subclass of DRF WritableField.
This field handles GeoDjango geometry fields, providing custom to_native
and from_native methods for GeoJSON input/output.
Provides a GeometryField, which is a subclass of Django Rest Framework (from now on **DRF**) `WritableField`.
This field handles GeoDjango geometry fields, providing custom `to_native`
and `from_native` methods for GeoJSON input/output.

Serializers
-----------

__GeoModelSerializer__
### GeoModelSerializer

Provides a GeoModelSerializer, which is a sublass of DRF ModelSerializer.
Provides a `GeoModelSerializer`, which is a sublass of DRF `ModelSerializer`.
This serializer updates the field_mapping dictionary to include
field mapping of GeoDjango geometry fields to the above GeometryField.
field mapping of GeoDjango geometry fields to the above `GeometryField`.

For example, the following model:

class Location(models.Model):
"""
A model which holds information about a particular location
"""
address = models.Charfield(max_length=255)
city = models.CharField(max_length=100)
state = models.CharField(max_length=100)
point = models.PointField()
```python
class Location(models.Model):
"""
A model which holds information about a particular location
"""
address = models.Charfield(max_length=255)
city = models.CharField(max_length=100)
state = models.CharField(max_length=100)
point = models.PointField()
```

By default, the DRF ModelSerializer will output::

{
"id": 1,
"address": "742 Evergreen Terrace",
"city": "Springfield",
"state": "Oregon",
"point": "POINT(-123.0208 44.0464)"
```javascript
{
"id": 1,
"address": "742 Evergreen Terrace",
"city": "Springfield",
"state": "Oregon",
"point": "POINT(-123.0208 44.0464)"
}
```

In contrast, the `GeoModelSerizalizer` will output::

```javascript
{
"id": 1,
"address": "742 Evergreen Terrace",
"city": "Springfield",
"state": "Oregon",
"point": {
"type": "Point",
"coordinates": [-123.0208, 44.0464],
}
}
```

In contrast, the GeoModelSerizalizer will output::
### GeoFeatureModelSerializer

{
"id": 1,
"address": "742 Evergreen Terrace",
"city": "Springfield",
"state": "Oregon",
`GeoFeatureModelSerializer` is a subclass of `GeoModelSerializer` which will output data in a format that is **GeoJSON**
compatible. Using the above example, the `GeoFeatureModelSerializer` will output:

```javascript
{
"id": 1,
"type": "Feature",
"geometry": {
"point": {
"type": "Point",
"coordinates": [-123.0208, 44.0464],
},
},
"properties": {
"address": "742 Evergreen Terrace",
"city": "Springfield",
"state": "Oregon"
}


__GeoFeatureModelSerializer__
}
```

GeoFeatureModelSerializer is a subclass of GeoModelSerializer which will output data in a format that is GeoJSON
compatible. Using the above example, the GeoFeatureModelSerializer will output:
If you are serializing an object list, `GeoFeatureModelSerializer` will create a `FeatureCollection`:

{
"id": 1,
(**NOTE:** This currenty does not work with the default pagination serializer)

```javascript
{
"type": "FeatureCollection",
"features": [
{
"id": 1
"type": "Feature",
"geometry": {
"point": {
"type": "Point",
"coordinates": [-123.0208, 44.0464],
},
}
},
"properties": {
"address": "742 Evergreen Terrace",
"city": "Springfield",
"state": "Oregon"
"address": "742 Evergreen Terrace",
"city": "Springfield",
"state": "Oregon",
}
}

If you are serializing an object list, GeoFeatureModelSerializer will create a FeatureCollection:

[ NOTE: This currenty does not work with the default pagination serializer ]

{
"type": "FeatureCollection",
"features": [
{
"id": 1
"type": "Feature",
"geometry": {
"point": {
"type": "Point",
"coordinates": [-123.0208, 44.0464],
}
},
"properties": {
"address": "742 Evergreen Terrace",
"city": "Springfield",
"state": "Oregon",
}
}
{
"id": 2,
"type": "Feature",
"geometry": {
"point": {
"type": "Point",
"coordinates": [-123.0208, 44.0489],
},
{
"id": 2,
"type": "Feature",
"geometry": {
"point": {
"type": "Point",
"coordinates": [-123.0208, 44.0489],
},
"properties": {
"address": "744 Evergreen Terrace",
"city": "Springfield",
"state": "Oregon"
}
},
"properties": {
"address": "744 Evergreen Terrace",
"city": "Springfield",
"state": "Oregon"
}
}

GeoFeatureModelSerializer requires you to define a "geo_field" to be serialized as the "geometry". For example:

class LocationSerializer(GeoFeatureModelSerializer):
""" A class to serialize locations as GeoJSON compatible data """
class Meta:
model = Location
geo_field = "point"
# you can also explicitly declare which fields you want to include
# as with a ModelSerializer.
fields = ('id', 'address', 'city', 'state')
}
```

`GeoFeatureModelSerializer` requires you to define a **`geo_field`** to be serialized as the "geometry".
For example:

```python
class LocationSerializer(GeoFeatureModelSerializer):
""" A class to serialize locations as GeoJSON compatible data """

class Meta:
model = Location
geo_field = "point"

# you can also explicitly declare which fields you want to include
# as with a ModelSerializer.
fields = ('id', 'address', 'city', 'state')
```

The primary key of the model (usually the "id" attribute) is automatically put outside
the "properties" object (before "type") unless "id_field" is set to False:

class LocationSerializer(GeoFeatureModelSerializer):
class Meta:
model = Location
geo_field = "point"
id_field = False
fields = ('id', 'address', 'city', 'state')

You could also set the id_field to some other unique field in your model, like "slug":

class LocationSerializer(GeoFeatureModelSerializer):
class Meta:
model = Location
geo_field = "point"
id_field = "slug"
fields = ('slug', 'address', 'city', 'state')
the "properties" object (before "type") unless **`id_field`** is set to False:

```python
class LocationSerializer(GeoFeatureModelSerializer):

class Meta:
model = Location
geo_field = "point"
id_field = False
fields = ('id', 'address', 'city', 'state')
```

You could also set the **`id_field`** to some other unique field in your model, like **"slug"**:

```python
class LocationSerializer(GeoFeatureModelSerializer):

class Meta:
model = Location
geo_field = "point"
id_field = "slug"
fields = ('slug', 'address', 'city', 'state')
```

Filters
-------

Provides a InBBOXFilter, which is a subclass of DRF BaseFilterBackend.
Provides a `InBBOXFilter`, which is a subclass of DRF `BaseFilterBackend`.
Filters a queryset to only those instances within a certain bounding box.


Expand All @@ -164,25 +190,36 @@ Running the tests
Assuming one has the dependencies installed (restframework and restframework_gis),
and one of the **Spatial Database server supported by GeoDjango**: https://docs.djangoproject.com/en/dev/ref/contrib/gis/db-api/#module-django.contrib.gis.db.backends is up and running::

python setup.py test
```bash
python setup.py test
```

You might need to tweak the DB settings according to your DB configuration.
You can copy the file local_settings.example.py to **local_settings.py** and change
the DATABASES and/or INSTALLED_APPS directive there.

**Warning**: tests are still a work in progress.

Contributing to the tests
-------------------------
You can copy the file `local_settings.example.py` to `local_settings.py` and change
the `DATABASES` and/or `INSTALLED_APPS` directives there.

If you want to contribute you need to install the test app in a proper development environment.

These steps should do:
* create a spatial database named "django_restframework_gis"
* create local_settings.py, eg: `cp local_settings.example.py local_settings.py`
* tweak the DATABASES configuration directive according to your DB
* optionally install olwidget (pip install olwidget)
* uncomment INSTALLED_APPS (remove olwidget if you did not install it)
* run `python manage.py syncdb`
* run `python manage.py collectstatic`
* run `python manage.py runserver`
These steps should do the trick:

* create a spatial database named "django_restframework_gis"
* create `local_settings.py`, eg: ``cp local_settings.example.py local_settings.py``
* tweak the `DATABASES` configuration directive according to your DB settings
* optionally install `olwidget` with `pip install olwidget`
* uncomment `INSTALLED_APPS` (remove olwidget if you did not install it)
* run `python manage.py syncdb`
* run `python manage.py collectstatic`
* run `python manage.py runserver`

Contributing
------------

1. Join the [Django REST Framework GIS Mailing List](https://groups.google.com/forum/#!forum/django-rest-framework-gis) and announce your intentions
2. Follow the [PEP8 Style Guide for Python Code](http://www.python.org/dev/peps/pep-0008/)
3. Fork this repo
4. Write code
5. Write tests for your code
6. Ensure all tests pass
7. Ensure test coverage is not under 90%
8. Document your changes
9. Send pull request

0 comments on commit 1906069

Please sign in to comment.