.. TastyTopping documentation master file, created by sphinx-quickstart on Wed Dec 18 15:03:05 2013. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. 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 ^^^^^^^^ .. toctree:: :maxdepth: 1 tutorial auth query nested optimization cookbook tastytopping 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 :py:class:`~tastytopping.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. Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search`