From e061d2576692f2c333a35c3a4f7bb154e1e818f2 Mon Sep 17 00:00:00 2001 From: Daniel Lindsley Date: Mon, 8 Nov 2010 21:22:50 -0600 Subject: [PATCH] Reverted the doc changes by acdha. Couldn't ever get them built properly and I'm about to overhaul the docs by hand. Sorry Chris. :( --- docs/conf.py | 7 +---- docs/cookbook.rst | 19 ----------- docs/filtering_sorting.rst | 52 ------------------------------- docs/index.rst | 1 - docs/reference/api.rst | 5 --- docs/reference/authentication.rst | 5 --- docs/reference/authorization.rst | 5 --- docs/reference/bundle.rst | 5 --- docs/reference/cache.rst | 5 --- docs/reference/constants.rst | 6 ---- docs/reference/exceptions.rst | 5 --- docs/reference/fields.rst | 5 --- docs/reference/http.rst | 5 --- docs/reference/index.rst | 20 ------------ docs/reference/models.rst | 5 --- docs/reference/paginator.rst | 5 --- docs/reference/resources.rst | 5 --- docs/reference/serializers.rst | 5 --- docs/reference/throttle.rst | 5 --- docs/tutorial.rst | 39 +++++++++++------------ tastypie/constants.py | 3 +- 21 files changed, 21 insertions(+), 191 deletions(-) delete mode 100644 docs/reference/api.rst delete mode 100644 docs/reference/authentication.rst delete mode 100644 docs/reference/authorization.rst delete mode 100644 docs/reference/bundle.rst delete mode 100644 docs/reference/cache.rst delete mode 100644 docs/reference/constants.rst delete mode 100644 docs/reference/exceptions.rst delete mode 100644 docs/reference/fields.rst delete mode 100644 docs/reference/http.rst delete mode 100644 docs/reference/index.rst delete mode 100644 docs/reference/models.rst delete mode 100644 docs/reference/paginator.rst delete mode 100644 docs/reference/resources.rst delete mode 100644 docs/reference/serializers.rst delete mode 100644 docs/reference/throttle.rst diff --git a/docs/conf.py b/docs/conf.py index a0e66bf6c..58c15cdfe 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -22,7 +22,7 @@ # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx'] +extensions = [] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -192,8 +192,3 @@ # If false, no module index is generated. #latex_use_modindex = True - -intersphinx_mapping = { - 'py': ('http://docs.python.org/2.6', None), - 'django': ('http://docs.djangoproject.com/en/1.2', 'http://docs.djangoproject.com/en/1.2/_objects/'), - } diff --git a/docs/cookbook.rst b/docs/cookbook.rst index 3e0c42094..4c099ad49 100644 --- a/docs/cookbook.rst +++ b/docs/cookbook.rst @@ -4,22 +4,3 @@ Tastypie Cookbook ================= - -Adding Custom Values --------------------- - -You might encounter cases where you wish to include additional data in a -response which is not obtained from a field or method on your model. You can -easily extend the :meth:`~tastypie.resources.Resource.dehydrate` method to -provide additional values:: - - class MyModelResource(Resource): - class Meta: - qs = MyModel.objects.all() - - def dehydrate(self, bundle): - bundle.data['custom_field'] = "Whatever you want" - return bundle - - - diff --git a/docs/filtering_sorting.rst b/docs/filtering_sorting.rst index 526ed4f09..9011c1ca3 100644 --- a/docs/filtering_sorting.rst +++ b/docs/filtering_sorting.rst @@ -4,55 +4,3 @@ Filtering And Sorting ===================== -Basic Filtering ---------------- - -:class:`~tastypie.resources.ModelResource` provides a basic Django ORM filter -interface. Simply list the resource fields which you'd like to filter on and -the allowed expression in a `filtering` property of your resource's Meta -class:: - - from tastypie.constants import ALL, ALL_WITH_RELATIONS - - class MyResource(ModelResource): - class Meta: - filtering = { - "slug": ('exact', 'startswith',), - "title": ALL, - } - -Valid filtering values are: Django ORM filters (e.g. ``startswith``, -``exact``, ``lte``, etc. or the ``ALL`` or ``ALL_WITH_RELATIONS`` constants -defined in :mod:`tastypie.constants`. - -These filters will be extracted from URL query strings using the same -double-underscore syntax as the Django ORM:: - - /api/v1/myresource/?slug=myslug - /api/v1/myresource/?slug__startswith=test - -Advanced Filtering ------------------- - -If you need to filter things other than ORM resources or wish to apply -additional constraints (e.g. text filtering using `django-haystack -` rather than simple database queries) your -:class:`~tastypie.resources.Resource` may define a custom -:meth:`~tastypie.resource.Resource.build_filters` method which allows you to -filter the queryset before processing a request:: - - from haystack.query import SearchQuerySet - - class MyResource(Resource): - def build_filters(self, filters=None): - if filters is None: - filters = {} - - orm_filters = super(MyResource, self).build_filters(filters) - - if "q" in filters: - sqs = SearchQuerySet().auto_query(filters['q']) - - orm_filters = {"pk__in": [ i.pk for i in sqs ]} - - return orm_filters diff --git a/docs/index.rst b/docs/index.rst index c7107e758..419755c31 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,4 +10,3 @@ interfaces. tutorial settings - reference/index.rst diff --git a/docs/reference/api.rst b/docs/reference/api.rst deleted file mode 100644 index 0e5326d53..000000000 --- a/docs/reference/api.rst +++ /dev/null @@ -1,5 +0,0 @@ -API -=== - -.. automodule:: tastypie.api - :members: diff --git a/docs/reference/authentication.rst b/docs/reference/authentication.rst deleted file mode 100644 index 20dbce100..000000000 --- a/docs/reference/authentication.rst +++ /dev/null @@ -1,5 +0,0 @@ -Authentication -============== - -.. automodule:: tastypie.authentication - :members: diff --git a/docs/reference/authorization.rst b/docs/reference/authorization.rst deleted file mode 100644 index 4c1250ffb..000000000 --- a/docs/reference/authorization.rst +++ /dev/null @@ -1,5 +0,0 @@ -Authorization -============= - -.. automodule:: tastypie.authorization - :members: diff --git a/docs/reference/bundle.rst b/docs/reference/bundle.rst deleted file mode 100644 index 9e9118989..000000000 --- a/docs/reference/bundle.rst +++ /dev/null @@ -1,5 +0,0 @@ -Bundle -====== - -.. automodule:: tastypie.bundle - :members: diff --git a/docs/reference/cache.rst b/docs/reference/cache.rst deleted file mode 100644 index 112cfecd2..000000000 --- a/docs/reference/cache.rst +++ /dev/null @@ -1,5 +0,0 @@ -Cache -===== - -.. automodule:: tastypie.cache - :members: diff --git a/docs/reference/constants.rst b/docs/reference/constants.rst deleted file mode 100644 index 58b6e0b3a..000000000 --- a/docs/reference/constants.rst +++ /dev/null @@ -1,6 +0,0 @@ -Constants -========= - -.. automodule:: tastypie.constants - :members: - :undoc-members: \ No newline at end of file diff --git a/docs/reference/exceptions.rst b/docs/reference/exceptions.rst deleted file mode 100644 index 154398b55..000000000 --- a/docs/reference/exceptions.rst +++ /dev/null @@ -1,5 +0,0 @@ -Exceptions -========== - -.. automodule:: tastypie.exceptions - :members: diff --git a/docs/reference/fields.rst b/docs/reference/fields.rst deleted file mode 100644 index 3dd76ca83..000000000 --- a/docs/reference/fields.rst +++ /dev/null @@ -1,5 +0,0 @@ -Fields -====== - -.. automodule:: tastypie.fields - :members: diff --git a/docs/reference/http.rst b/docs/reference/http.rst deleted file mode 100644 index 71d6c2e71..000000000 --- a/docs/reference/http.rst +++ /dev/null @@ -1,5 +0,0 @@ -HTTP -==== - -.. automodule:: tastypie.http - :members: diff --git a/docs/reference/index.rst b/docs/reference/index.rst deleted file mode 100644 index 04b0926c0..000000000 --- a/docs/reference/index.rst +++ /dev/null @@ -1,20 +0,0 @@ -Tastypie Module Reference -========================= - -.. toctree:: - :maxdepth: 2 - - api.rst - authentication.rst - authorization.rst - bundle.rst - cache.rst - constants.rst - exceptions.rst - fields.rst - http.rst - models.rst - paginator.rst - resources.rst - serializers.rst - throttle.rst diff --git a/docs/reference/models.rst b/docs/reference/models.rst deleted file mode 100644 index fb0190c76..000000000 --- a/docs/reference/models.rst +++ /dev/null @@ -1,5 +0,0 @@ -Modles -====== - -.. automodule:: tastypie.models - :members: diff --git a/docs/reference/paginator.rst b/docs/reference/paginator.rst deleted file mode 100644 index c66f2ae22..000000000 --- a/docs/reference/paginator.rst +++ /dev/null @@ -1,5 +0,0 @@ -Paginator -========= - -.. automodule:: tastypie.paginator - :members: diff --git a/docs/reference/resources.rst b/docs/reference/resources.rst deleted file mode 100644 index 9e3e5e8e2..000000000 --- a/docs/reference/resources.rst +++ /dev/null @@ -1,5 +0,0 @@ -Resources -========= - -.. automodule:: tastypie.resources - :members: diff --git a/docs/reference/serializers.rst b/docs/reference/serializers.rst deleted file mode 100644 index f1f053bfc..000000000 --- a/docs/reference/serializers.rst +++ /dev/null @@ -1,5 +0,0 @@ -Serializers -=========== - -.. automodule:: tastypie.serializers - :members: diff --git a/docs/reference/throttle.rst b/docs/reference/throttle.rst deleted file mode 100644 index 2cd17cb3d..000000000 --- a/docs/reference/throttle.rst +++ /dev/null @@ -1,5 +0,0 @@ -Throttle -======== - -.. automodule:: tastypie.throttle - :members: diff --git a/docs/tutorial.rst b/docs/tutorial.rst index e5254a4e4..aedf5fd26 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -4,9 +4,9 @@ Getting Started with Tastypie ============================= -Tastypie is a reusable app (that is, it relies only on it's own code and -focuses on providing just a REST-style API) and is suitable for providing an -API to any application without having to modify the sources of that app. +Tastypie is a reusable app (that is, it relies only on it's own code and focuses +on providing just a REST-style API) and is suitable for providing an API to +any application without having to modify the sources of that app. Not everyone's needs are the same, so Tastypie goes out of it's way to provide plenty of hooks for overridding or extending how it works. @@ -101,9 +101,9 @@ Creating Resources ================== REST-style architecture talks about resources, so unsurprisingly integrating -with Tastypie involves creating :class:`~tastypie.resources.Resource` classes. -For our simple application, we'll create a file for these in ``myapp/api.py``, -though they can live anywhere in your application:: +with Tastypie involves creating ``Resource`` classes. For our simple +application, we'll create a file for these in ``myapp/api.py``, though they can +live anywhere in your application:: # myapp/api.py from tastypie.resources import ModelResource @@ -115,16 +115,16 @@ though they can live anywhere in your application:: queryset = Entry.objects.all() resource_name = 'entry' -This class, by virtue of being a :class:`~tastypie.resources.ModelResource` -subclass, will introspect all non-relational fields on the ``Entry`` model and -create it's own :mod:`ApiFields ` that map to those fields, -much like the way Django's ``ModelForm`` class introspects. +This class, by virtue of being a ``ModelResource`` subclass, will introspect +all non-relational fields on the ``Entry`` model and create it's own +``ApiFields`` that map to those fields, much like the way Django's ``ModelForm`` +class introspects. .. note:: The ``resource_name`` within the ``Meta`` class is optional. If not provided, it is automatically generated off the classname, removing any - instances of :class:`~tastypie.resources.Resource` and lowercasing the string. So + instances of ``Resource`` and lowercasing the string. So ``EntryResource`` would become just ``entry``. It's included in this example for clarity, especially when looking at @@ -217,9 +217,9 @@ In order to handle our ``user`` relation, we'll need to create a queryset = Entry.objects.all() resource_name = 'entry' -We simply created a new :class:`~tastypie.resources.ModelResource` subclass -called ``UserResource``. Then we added a field to ``EntryResource`` that -specified that the ``user`` field points to a ``UserResource`` for that data. +We simply created a new ``ModelResource`` subclass called ``UserResource``. +Then we added a field to ``EntryResource`` that specified that the ``user`` +field points to a ``UserResource`` for that data. Now we should be able to get all of the fields back in our response. But since we have another full, working resource on our hands, we should hook that up @@ -229,9 +229,8 @@ to our API as well. And there's a better way to do it. Adding To The Api ================= -Tastypie ships with an :class:`~tastypie.api.Api` class, which lets you bind -multiple :class:`Resources ` together to form a -coherent API. Adding it to the mix is simple. +Tastypie ships with an ``Api`` class, which lets you bind multiple ``Resources`` +together to form a coherent API. Adding it to the mix is simple. We'll go back to our URLconf (``urls.py``) and change it to match the following:: @@ -251,9 +250,9 @@ following:: (r'^api/', include(v1_api.urls)), ) -Note that we're now creating an :class:`~tastypie.api.Api` instance, -registering our ``EntryResource`` and ``UserResource`` instances with it and -that we've modified the urls to now point to ``v1_api.urls``. +Note that we're now creating an ``Api`` instance, registering our +``EntryResource`` and ``UserResource`` instances with it and that we've +modified the urls to now point to ``v1_api.urls``. This makes even more data accessible, so if we start up the ``runserver`` again, the following URLs should work: diff --git a/tastypie/constants.py b/tastypie/constants.py index dbaa88b7c..599503228 100644 --- a/tastypie/constants.py +++ b/tastypie/constants.py @@ -1,4 +1,3 @@ -#: Enable all basic ORM filters but do not allow filtering across relationships +# For filtering... ALL = 1 -#: Enable all ORM filters, including across relationships ALL_WITH_RELATIONS = 2