欢迎查看Django Piston文档¶
当前稳定版本为0.2.2 <http://bitbucket.org/jespern/django-piston/downloads/django-piston-0.2.2.tar.gz>`_.
NEW: 讨论组托管于 Google Groups.
生产版本¶
当前开发版版本为 0.3dev ,该文档正是根据此版本而建。
用于Django中创建RESTful API的轻型框架¶
Piston是一个相对轻型的Django应用,用于为网站创建应用编程接口(API)。
Piston有如下特点:
- 与Django原生机制相互结合
- 支持OAuth,同时也支持 Basic/Digest 和自定义认证
- 无须与models绑定,支持任何资源
- 支持JSON, YAML, Python Pickle & XML (和 HATEOAS.)
- 自带一组易用性好,重用性强的Python类库
- 推崇正确地使用HTTP (还有状态码, ...)
- 内置表单验证 (可选,由Django本身实现),对客户端请求进行限制等功能
- 支持流输出 streaming, 只占用很少的内存
- 不影响用户原来的开发方式。
NB: Piston内置OAuth,但并不要求用户必须使用OAuth。 Piston附带了一些关于如何使用OAuth简单的例子,开发者可以做为参考。(consumer/token models,urls等等)
社区知识库¶
通过社区知识库,开发者能够为Piston的发展提供新鲜空气,创建更多活跃的讨论。
安装¶
官方稳定版是 0.2.2 ,主干代码托管在bitbucket上,由于本文档所描述的版本是开发版而非稳定版,因此在使用Piston时留意当前版本信息。
Jesper Noehr 另外创建了一个分支 : django-piston-oauth2 该分支对oauth2提供了支持,同样也托管在 Github
文档¶
- Django Piston’s 文档
- 开始
- 资源(Resources)
- 发射器(Emitters)
- URL映射(Mapping URLs)
- 使用Models(Working with Models)
- 配置Handlers(Configuring Handlers)
- 认证(Authentication)
- 表单验证(Form Validation)
- 辅助方法,工具类 & 装饰器(Helpers, utils & @decorators)
- 限制客户端请求(Throttling)
- 生成文档(Generating Documentation)
- 测试(Tests)
- 接收数据(Receiving data)
- 流(Streaming)
- 配置项(Configuration variables)
完整的例子¶
例子比文档更有说服力:
urls.py:
#!python from django.conf.urls.defaults import * from piston.resource import Resource from piston.authentication import HttpBasicAuthentication from myapp.handlers import BlogPostHandler, ArbitraryDataHandler auth = HttpBasicAuthentication(realm="My Realm") ad = { 'authentication': auth } blogpost_resource = Resource(handler=BlogPostHandler, **ad) arbitrary_resource = Resource(handler=ArbitraryDataHandler, **ad) urlpatterns += patterns('', url(r'^posts/(?P<post_slug>[^/]+)/$', blogpost_resource), url(r'^other/(?P<username>[^/]+)/(?P<data>.+)/$', arbitrary_resource), )与之对应的 handlers.py:
#!python import re from piston.handler import BaseHandler from piston.utils import rc, throttle from myapp.models import Blogpost class BlogPostHandler(BaseHandler): allowed_methods = ('GET', 'PUT', 'DELETE') fields = ('title', 'content', ('author', ('username', 'first_name')), 'content_size') exclude = ('id', re.compile(r'^private_')) model = Blogpost @classmethod def content_size(self, blogpost): return len(blogpost.content) def read(self, request, post_slug): post = Blogpost.objects.get(slug=post_slug) return post @throttle(5, 10*60) # allow 5 times in 10 minutes def update(self, request, post_slug): post = Blogpost.objects.get(slug=post_slug) post.title = request.PUT.get('title') post.save() return post def delete(self, request, post_slug): post = Blogpost.objects.get(slug=post_slug) if not request.user == post.author: return rc.FORBIDDEN # returns HTTP 401 post.delete() return rc.DELETED # returns HTTP 204 class ArbitraryDataHandler(BaseHandler): methods_allowed = ('GET',) def read(self, request, username, data): user = User.objects.get(username=username) return { 'user': user, 'data_length': len(data) }
以上就是一个完整例子。
寻求帮助¶
Piston拥有良好的文档(wrongway吐槽:我看未必)以及一个正在不断完善的FAQ(wrongway再吐:没多少内容)。当您发现有用信息时请添加到FAQ中。
开始阅读 Django Piston’s 文档
内容¶
- Django Piston’s 文档
- 开始
- 资源(Resources)
- 发射器(Emitters)
- URL映射(Mapping URLs)
- 使用Models(Working with Models)
- 配置Handlers(Configuring Handlers)
- 认证(Authentication)
- 表单验证(Form Validation)
- 辅助方法,工具类 & 装饰器(Helpers, utils & @decorators)
- 限制客户端请求(Throttling)
- 生成文档(Generating Documentation)
- 测试(Tests)
- 接收数据(Receiving data)
- 流(Streaming)
- 配置项(Configuration variables)
- FAQ