Welcome to TastyTopping’s documentation!¶
So, you’ve done all that hard work creating your REST API using Tastypie on the server-side - why would you want to have to do it all again on the client-side?
TastyTopping creates objects that behave similarly to django models, using your self-documenting TastyPie REST API to create the object’s attributes and behaviour, in addition to retrieving the data. TastyTopping only needs 2 things from you: The URL of the API, and the resource name.
As a brief example:
>>> factory = ResourceFactory('http://localhost/app_name/api/v1')
>>> ex = factory.example(field1='name', field2=10)
>>> ex.field3 = datetime.now()
>>> print ex.field4
1.234
Contents¶
Requirements¶
The following needs to be installed locally to run TastyTopping:
- Python 2.7+ or Python 3.3+
- requests >= 1.2.3
Tested with / against:
- django >= 1.5.0
- django-tastypie >= 0.9.14
- requests >= 1.2.3
(see the tox.ini file for more information).
Justification¶
Why another one? There are some other packages around that do something similar, but none are the complete package:
- ORM. A lot of other packages use a C-style API, which involves passing a dict with your data to their functions. TastyTopping wraps it all up in an ORM-style object, which is more OO, more elegant, and more pythonic.
- Python3 support.
- Support for authentication.
- Support for nested resources.
- QuerySets!
- A thorough set of unit tests.
- Development has stagnated (none of them have released in close to a year, whereas tastypie has been releasing thick and fast).
- Creating this was FUN!
Examples¶
The examples shown here relate to the following TastyPie Resources:
class UserResource(ModelResource):
class Meta:
resource_name = 'user'
queryset = User.objects.all()
allowed_methods = ['get']
authorization = Authorization()
filtering = {
'username': ALL,
'id': ALL,
}
class ExampleResource(models.ModelResource):
created_by = fields.ForeignKey(UserResource, 'created_by', null=True)
class Meta:
resource_name = 'example'
queryset = Example.objects.all()
list_allowed_methods = ['get', 'post']
detail_allowed_methods = ['get', 'post', 'put', 'delete']
authentication = ApiKeyAuthentication()
authorization = Authorization()
filtering = {
'title': ALL,
'rating': ALL,
'date': ALL,
'created_by': ALL_WITH_RELATIONS,
}
ordering = ['rating', 'date']
The following example shows basic usage of the ORM, that will use GET, PUT,
POST, and DELETE methods on the API, using the
ResourceFactory
from datetime import datetime
from tastytopping import ResourceFactory, HTTPApiKeyAuth
if __name__ == "__main__":
factory = ResourceFactory('http://example.api.com:666/test/api/v1/')
auth = HTTPApiKeyAuth('username', '35632435657adf786c876e097f')
factory.example.auth = auth
new_resource = factory.example(title='A Title', rating=50)
new_resource.date = datetime.now()
new_resource.save()
# Get any user from the list of users and set it to created_by:
user = factory.user.all().first()
new_resource.created_by = user
# Get the new resource by its title:
another_resource = factory.example.get(title='A Title')
# Delete the new resource:
new_resource.delete()
# This will raise an exception since it's been deleted.
print another_resource.date
Running The Tests¶
To install tastytopping:
git clone https://github.com/cboelsen/tastytopping
cd tastytopping
virtualenv env
. env/bin/activate # Or, on windows, env/Scripts/activate
pip install -U -r requirements.txt
And to run the tests:
# Continued from above
pip install tox
tox
The tests are run against several environments with different versions of the same packages, and are meant to pass all the tests at all times. If they aren’t passing, it’s a bug! The tests aren’t run against every combination of requests, django, and tastypie supported, though, so there’s a small chance a bug might slip in unnoticed.