douban / douban-client

Python client library for Douban APIs (OAuth 2.0)

douban-client

douban-client 是对豆瓣 API v2 接口进行了一个简单封装，主要包括了 OAuth 2.0 认证、图片上传以及接口方面的调用。

目前已完成的接口有：

* 用户 User
* 广播 Miniblog
* 豆邮 Doumail
* 日记 Note
* 相册 Album
* 图片 Photo
* 读书 Book
* 电影 Movie
* 音乐 Music
* 线上活动 Online
* 同城活动 Event
* 论坛 Discussion
* 回复 Comment

安装

pip install douban-client

或

easy_install douban-client

使用说明

OAuth 2.0 认证

from douban_client import DoubanClient

API_KEY = 'your api key'
API_SECRET = 'your api secret'

# 在 OAuth 2.0 中，
# 获取权限需要指定相应的 scope，请注意!!
# scope 权限可以在申请应用的 "API 权限" 查看。

SCOPE = 'douban_basic_common,shuo_basic_r,shuo_basic_w'

client = DoubanClient(API_KEY, API_SECRET, your_redirect_uri, SCOPE)

# 以下方式 2 选 1:
# 1. 引导用户授权
print 'Go to the following link in your browser:' 
print client.authorize_url
code = raw_input('Enter the verification code:')
client.auth_with_code(code)

# 2. 如果有之前有 token，则可以
client.auth_with_token(token)

# Token Code
token_code = client.token_code

# Refresh Token
# 请注意：`refresh_token_code` 值仅可在授权完成时获取(即在 `auth_with_code`, `auth_with_password` 之后)
refresh_token_code = client.refresh_token_code
client.refresh_token(refresh_token_code) # refresh token

至此，已经完成 OAuth 2.0 授权。

Douban API v2 说明

1. 豆瓣Api V2认证统一使用OAuth2
2. 数据返回格式统一使用json，GData不再使用
3. 需要授权的Api，需要加access_token的Header，并且使用https协议，限制具体见OAuth2文档
4. 不需要授权公开api可以使用http，参数里面如果不包含apikey的话，限制单ip每分钟10次
5. Api里面的通配符，:id代表纯数字， :name代表由数字+字母+[-_.]这些特殊字符
6. 使用HTTP Status Code表示状态
7. 列表参数使用start和count
8. POST/PUT 时中文使用UTF-8编码
9. 时间格式：yyyy-MM-dd HH:mm:ss, 如"2007-06-28 11:16:11"

接口说明

默认参数（参考豆瓣官方文档）:

start: 0
count: 20

所有返回数据以豆瓣官方文档为准，各接口末尾处均有相应链接入口。

用户 User

# 以下 id 指用户数字 id
当前用户 client.user.me
指定用户 client.user.get(id) 
搜索用户 client.user.search(q)       # q: 搜索的关键词

# 此处是将广播关系接口放置到用户
关注用户 client.user.follow(id)
取消关注 client.user.unfollow(id)
粉丝信息 client.user.followers(id, start, count)
关注信息 client.user.following(id, start, count) 
加入黑名单 client.user.block(id)

http://developers.douban.com/wiki/?title=user_v2

http://developers.douban.com/wiki/?title=community_1_shuo#user_info

广播 Miniblog

# 以下 id 指广播数字 id
当前用户Timeline client.miniblog.home_timeline(count)
指定用户Timeline client.miniblog.user_timeline(user_id, count)

获取一条广播 client.miniblog.get(id)
新写一条广播 client.miniblog.new(text)
新写图片广播 client.miniblog.new(text, image=open('/path/pic.png'))
删除一条广播 client.miniblog.delete(id)

推荐网址 client.miniglog.rec(title='', url='', desc='', image='http://url.jpg')

获取某广播回复列表 client.miniblog.comments(id)
回复某条广播       client.miniblog.comment.new(id, text)
获取某条广播回复   client.miniblog.comment.get(comment_id)
删除某条广播回复   client.miniblog.comment.delete(comment_id)

赞广播 client.miniblog.like(id)
取消赞 client.miniblog.unlike(id)
赞某广播用户列表 client.miniblog.likers(id)

转发广播 client.miniblog.reshare(id)
转发某广播的用户列表 client.miniblog.resharers(id)

http://developers.douban.com/wiki/?title=community_1_shuo

豆邮 Doumail

# 以下 id 指豆邮数字 id
# 豆邮发送过多会需要验证，请注意
获取一封豆邮 client.doumail.get(id)
新写一封豆邮 client.doumail.new(title, content, receiver_id)

标记一封豆邮 client.doumail.read(id)
批量标记豆邮 client.doumail.reads(ids) # ids 为 list

删除一封豆邮 client.doumail.delete(id)
批量删除豆邮 client.doumail.deletes(ids) # ids: [id, id, id]

豆邮收件箱列表 client.doumail.inbox(start, count)
豆邮发件箱列表 client.doumail.outbox(start, count)
未读豆邮列表   client.doumail.unread(start, count)

http://developers.douban.com/wiki/?title=doumail_v2

日记 Note

# 以下 id 指日记数字 id
# format: html_full, html_short, abstract, text，默认为text
获取一篇日记 client.note.get(id, format='text')
新写一篇日记 client.note.new(title, content)
更新一篇日记 client.note.update(title, content)
删除一篇日记 client.note.delete(id)

喜欢一篇日记     client.note.like(id)
取消喜欢一篇日记 client.note.unlike(id)

获取用户日记列表       client.note.list(user_id, start, count)
获取用户喜欢的日记列表 client.note.liked_list(user_id, start, count)

获取回复列表  client.note.comments(id, start, count)
新加一条回复  client.note.comment.new(id, content)
获取一条回复  client.note.comment.get(comment_id)
删除一条回复  client.note.comment.delete(comment_id)

http://developers.douban.com/wiki/?title=note_v2

相册 Album

# 以下 id 指相册数字 id
# desc 描述文字
获取一个相册 client.album.get(id)
新建一个相册 client.album.new(title, desc)
更新一个相册 client.album.update(id, title, desc)
删除一个相册 client.album.delete(id)

获取用户相册列表 client.album.list(user_id, start, count)
用户喜欢相册列表 client.album.liked_list(user_id, start, count)
获取相册图片列表 client.album.photos(id, start, count)

喜欢一个相册 client.album.like(id)
取消喜欢相册 client.album.unlike(id)

http://developers.douban.com/wiki/?title=photo_v2#get_album

图片 Photo

# 以下 id 指图片数字 id
获取一张图片 client.photo.get(id)
上传一张图片 client.photo.new(album_id, image, desc) # image = open('/path/pic.png')
更新图片描述 client.photo.update(id, desc)     # desc 为描述文字
删除一条图片 client.photo.delete(id)

喜欢一张图片 client.photo.like(id)
取消喜欢图片 client.photo.unlike(id)

获取回复列表  client.photo.comments(id, start, count)
新加一条回复  client.photo.comment.new(id, content)
获取一条回复  client.photo.comment.get(comment_id)
删除一条回复  client.photo.comment.delete(comment_id)

http://developers.douban.com/wiki/?title=photo_v2#get_photo

读书 Book

# 以下 id 指图书条目数字 id
# q: 关键词, tag: 标签
获取一本图书信息 client.book.get(id)
通过isbn获取信息 client.book.isbn(isbn_number)
搜索图书信息     client.book.search(q, tag, start, count) 

获取图书标签 client.book.tags(id)
获取用户标签 client.book.tagged_list(user_id)

发表一条书评 client.book.review.new(id, title, content)
更新一条书评 client.book.review.update(review_id, title, content)
删除一条书评 client.book.review.delete(review_id)

http://developers.douban.com/wiki/?title=book_v2

电影 Movie

# 以下 id 指电影条目数字 id
# q: 关键词, tag: 标签
获取一部电影信息 client.movie.get(id)
获取影人信息 client.movie.celebrity(celebrity_id)
通过imdb获取电影 client.movie.imdb(imdb_number)
搜索电影信息     client.movie.search(q, tag, start, count) 

获取电影标签 client.movie.tags(id)
获取用户标签 client.movie.tagged_list(user_id)

发表一条影评 client.movie.review.new(id, title, content)
更新一条影评 client.movie.review.update(review_id, title, content)
删除一条影评 client.movie.review.delete(review_id)

http://developers.douban.com/wiki/?title=movie_v2

音乐 Music

# 以下 id 指音乐条目数字 id
# q: 关键词, tag: 标签
获取音乐信息 client.music.get(id)
搜索音乐信息 client.music.search(q, tag, start, count) 

获取音乐标签 client.music.tags(id)
获取用户标签 client.music.tagged_list(user_id)

发表一条乐评 client.music.review.new(id, title, content)
更新一条乐评 client.music.review.update(review_id, title, content)
删除一条乐评 client.music.review.delete(review_id)

http://developers.douban.com/wiki/?title=music_v2

线上活动 Online

# 以下 id 指线上活动数字 id
# begin_time, end_time 格式为 '%Y-%m-%d %H:%M:%S'
# cate 可选值: day, week, latest
获取一条线上活动 client.online.get(id)
发表一条线上活动 client.online.new(title, desc, begin_time, end_time)
更新一条线上活动 client.online.update(title, desc, begin_time, end_time)
删除一条线上活动 client.online.delete(id)

参加一条线上活动 client.online.join(id)
取消参加线上活动 client.online.quit(id)

喜欢一条线上活动 client.online.like(id)
取消喜欢线上活动 client.online.unlike(id)

获取线上活动图片列表 client.online.photos(id, start, count)
上传图片到线上活动   client.online.upload(id, image) # image = open('xxx.jpg')

获取线上活动讨论列表 client.online.discussions(id, start, count)
在线上活动新发讨论   client.online.discussion.new(id, title, content)

获取参加线上活动成员列表 client.online.participants(id, start, count)

获取线上活动列表 client.online.list(cate, start, end) 
获取参加过的活动 client.online.joined(user_id, start, count)
获取创建过的活动 client.online.created(user_id, start, count)

http://developers.douban.com/wiki/?title=online_v2

同城活动 Event

# 以下 id 指同城活动 id 
# q: 关键词, loc: 城市
# day_type: future, week, weekend, today, tomorrow
# type: all,music, film, drama, commonweal, salon, \
#       exhibition, party, sports, travel, others
获取同城活动 client.event.get(id)
搜索同城活动 client.event.search(q, loc, start, count)

参加同城活动 client.event.join(id)
取消参加活动 client.event.quit(id)

对同城活动感兴趣 client.event.wish(id)
取消同城活动兴趣 client.event.unwish(id)

某同城活动参加者   client.event.participants(id, start, count)
某同城活动感兴趣者 client.event.wishers(id, start, count)

获取用户创建过的同城活动 client.event.owned(user_id, start, count)
获取用户参加过的同城活动 client.event.participated(user_id, start, count)
获取用户感兴趣的同城活动 client.event.wished(user_id, start, count)

获取同城活动列表 client.event.list(loc, day_type, type, start, count)

http://developers.douban.com/wiki/?title=event_v2

论坛 Discussion

# 以下 id 指论坛帖子 id 
# target 指相应产品线（如 online, review 等）
# target_id 指相应产品 id
获取帖子 client.discussion.get(id)
发表帖子 client.discussion.new(target, target_id, title, content)
更新帖子 client.discussion.update(id, title, content)
删除帖子 client.discussion.delete(id)

获取帖子列表 client.discussion.list(target, target_id)

获取回复列表 client.discussion.comments(id, start, count)
新加一条回复 client.discussion.comment.new(id, content)
获取某条回复 client.discussion.comment.get(comment_id)
删除某条回复 client.discussion.comment.delete(comment_id)

http://developers.douban.com/wiki/?title=discussion_v2

已实现的接口中单元测试覆盖 90%+，如果文档中有没有说明的可以参考下： https://github.com/liluo/douban-client/tree/master/tests

Changelog

v0.0.6 [2013-12-18]

• 兼容 Python 3.x
• 接口变更:

+ note: upload_photo
- user: block, friendships, follow_in_common
- movie: celebrity_works
- miniblog: mentions

v0.0.5 [2013-04-26]

• 修复文档中关于授权部分的错误
• 修复 refresh_token 错误
• DoubanClient 实例对象增加 token_code, refresh_token_code 属性

v0.0.4 [2013-04-07]

• 增加 refresh token 方法

v0.0.3 [2012-10-23]

• 解决 py-oauth2 与 python-oauth2 命名冲突
• 同步更新同城活动 api

v0.0.2 [2012-09-07]

• 与豆瓣官网同步，调整 people -> user
• 获取创建线上活动接口变更 online.owned -> online.created
• 去除已被删除的豆瓣猜接口

v0.0.1 [2012-09-06]

• 根据豆瓣 API v2 文档，发布第一个版本

联系

• 使用 douban-client 过程中遇到 bug, 可以到 Issues 反馈
• 比较紧急的问题可以在 Douban 或者 Twitter @liluoliluo
• 欢迎提 pull request

douban-client's Issues

ImportError: cannot import name AccessToken

from oauth2 import Client, AccessToken

ImportError: cannot import name AccessToken

我使用给的例子进行测试的时候报出这个错误，去看了下OAuth确实没有这个AccessToken这个模块
不知道怎么处理？？

developer.douban.com 已经下线了么？

developer.douban.com 已经下线了么？网站已经无法打开。

这个项目是否已经失去意义了。

调用 delete 类 API 时报 ValueError

根据豆瓣 API 文档，比如 book_v2 中删除笔记调用 client.book._delete(url) 删除成功但会报 ValueError，原因在于此 API 无返回信息，但 api/base.py 中 check_exception 装饰器在无错误的情况下总是返回 resp.parsed ，resp.parsed 中没有检查是否有返回信息便试图转换结果为 json 导致 ValueError.

通过pip安装报md5不一致错误

错误描述：

Collecting douban-client
Using cached douban-client-0.0.6.tar.gz
Collecting py-oauth2>=0.0.8 (from douban-client)
Using cached py-oauth2-0.0.10.tar.gz
Collecting six>=1.4.1 (from douban-client)
Using cached six-1.9.0-py2.py3-none-any.whl
Collecting requests (from py-oauth2>=0.0.8->douban-client)
Using cached requests-2.7.0-py2.py3-none-any.whl
Hash of the package https://pypi.python.org/packages/2.7/r/requests/requests-2.7.0-py2.py3-none-any.whl#md5=564fb256f865a79f977e57b79d31659a (from https://pypi.python.org/simple/requests/) (9703a9e5b8ddd20165da369ff89a7fbb) doesn't match the expected hash 564fb256f865a79f977e57b79d31659a!
Bad md5 hash for package https://pypi.python.org/packages/2.7/r/requests/requests-2.7.0-py2.py3-none-any.whl#md5=564fb256f865a79f977e57b79d31659a (from https://pypi.python.org/simple/requests/)

diy client

is there a API to get music history of a user and make some songs play

支持 Python 3.x

已支持.

examples bug

[file]
auth_with_token.py

[bug]
in 11 line
cleint = client

: )

话说, 现在是不对个人开发者提供使用了是吗?

较早的时候申请过的apikey/secret貌似也失效了, oauth认证的时候返回:

<html>
<head>
<title>403 Forbidden</title>
</head>
<body bgcolor="white">
<center>
<h1>403 Forbidden</h1>
</center>
<hr>
<center>dae</center>
</body>
</html>

示例中auth_with_password的代码不能正常工作

我按照这里给出的代码测试：https://github.com/douban/douban-client/blob/master/examples/auth_with_password.py 运行报错。auth_with_password似乎没有认证成功

from douban_client import DoubanClient

KEY = '***'
SECRET = '***'
CALLBACK = ''
SCOPE = 'douban_basic_common,community_basic_user'

client = DoubanClient(KEY, SECRET, CALLBACK, SCOPE)
client.auth_with_password('user_email', 'user_password')
print client.user.me

Tracback如下

  File "/Users/tianyu/.virtualenvs/wall-e/lib/python2.7/site-packages/douban_client/api/user.py", line 16, in me
    return self.get('~me')
  File "/Users/tianyu/.virtualenvs/wall-e/lib/python2.7/site-packages/douban_client/api/user.py", line 12, in get
    return self._get('/v2/user/%s' % id)
  File "/Users/tianyu/.virtualenvs/wall-e/lib/python2.7/site-packages/douban_client/api/base.py", line 15, in _check
    raise DoubanAPIError(resp)
douban_client.api.error.DoubanAPIError: ***403 (Forbidden)*** {u'msg': u'need_permission', u'code': 1000, u'request': u'GET /service/v2/user/~me'}

app的id和secret检查过了没填错，用户名密码确认过了没填错。

怎样知道target应该填什么值？

比如在获取某论坛id为'foo'的帖子列表，代码如下：
client.discussion.list(target, target_id)
翻遍了文档，我只能确认target_id应该填'foo'，但是我无法从文档中得知target应该赋给什么值。

douban_client.api.error.DoubanAPIError: ***400 (Bad Request)***

我寫了下面簡單的code:
token = '-----------------------'
client.auth_with_token(token)

my_content = client.user.me
print my_content

然後得到下面的錯誤：
Traceback (most recent call last):
File "test.py", line 31, in
my_content = client.user.me
File "/usr/local/lib/python2.7/site-packages/douban_client/api/user.py", line 16, in me
return self.get('~me')
File "/usr/local/lib/python2.7/site-packages/douban_client/api/user.py", line 12, in get
return self._get('/v2/user/%s' % id)
File "/usr/local/lib/python2.7/site-packages/douban_client/api/base.py", line 15, in check
raise DoubanAPIError(resp)
douban_client.api.error.DoubanAPIError: _400 (Bad Request) {u'msg': u'invalid_access_token: 4b19728adfd624be', u'code': 103, u'request': u'GET /v2/user/~me'}
notebook20:Douban_API standard2$

能不能請Liluo指點一下

AttributeError: 'Client' object has no attribute 'get'

采用client.movie.get(id)方法获取电影信息时，报错：
AttributeError: 'Client' object has no attribute 'get'

查了下
/usr/local/lib/python2.6/dist-packages/py_oauth2-0.0.3-py2.6.egg/oauth2/client.py
中Client类的实现，确实没有get方法

求助！

不能使用一些不需要进行 oAuth 认证就能调用的接口

例如这个根据 isbn 获取书籍信息的接口，不一定需要通过认证就能进行调用了，但是在 douban-client 里还是需要，否则就会抛出 401 的异常。

粗略看了看实现，所有的接口都继承了 DoubanApiBase 这个类，默认调用的时候是检查认证的。那能不能添加另外一个检查选项，让类似 get_isbn_book 这样的接口也能直接调用？

请问client.auth_with_token这个参数是什么形式呢？

请删除，谢谢～

py_oauth2是自己封装的吧？问题太多

糟糕的结构导致其很难向python3迁移，我想这也是douban-client迟迟不能支持python3的原因，官方不愿搞，民间无法搞

client.note.get(0) 出现400错误

douban_client/api/base.py", line 15, in _check
    raise DoubanAPIError(resp)
douban_client.api.error.DoubanAPIError: ***400 (Bad Request)*** {u'msg': u'target_not_found', u'code': 1006, u'request': u'GET /service/v2/note/0'}

解释器运行from douban_client import DoubanClient报错

您好，我是个python 新手 ，在解释器中运行如题脚本时报错，望答复。谢谢。
使用环境为python3.2，windows7 cmd 或者 windows GitBash
1.安装

pip install douban-client

安装完成后，在路径Lib\site-packages下，可以看到安装了一下包(版本为包中init.py中所示)：
douban_client '0.0.5'
httplib2
pyoauth2 '0.0.6'

2.此时我试着通过解释器运行如下代码：

from douban_client import DoubanClient

报如下错误：

File "c:\Python33\lib\site-packages\pyoauth2\__init__.py", line 3, in <module>
from client import Client
ImportError: No module named 'client'  

我尝试着解决这个错误，修改Lib\site-packages\pyoauth2、init.py，将导入代码

from client import Client

修改为

from .client import Client  

然后尝试运行脚本，报如下错误

File "c:\Python33\lib\site-packages\pyoauth2\__init__.py", line 3, in <module>
from .client import Client
File "c:\Python33\lib\site-packages\pyoauth2\client.py", line 3, in <module>
from libs.auth_code import AuthCode
ImportError: No module named 'libs.auth_code'

不知道这是为什么？好吧，写了这么多，发现 @liluo 的一个issue里面的回答：

py-oauth2 和 douban-client 暂时没有对 Py 3.x 做兼容。

好吧，看来我继续学习了，这个issue关闭了吧。。

pyoauth2好像不支持3.2版本的

下载最新的但安装之后执行from douban_client import DoubanClient会报错，然后发现pyoauth2里面很多类似于urlparse和StringIO等都已经不支持3.2的版本

文档中OAuth2.0认证示例关于access_token部分有错误

• access_token为NoneType

#1. 引导用户授权
print 'Go to the following link in your browser:' 
print client.authorize_url
code = raw_input('Enter the verification code:')
access_token = client.auth_with_code(code)

代码中auth_with_code并没有返回值，access_token为NoneType：

    def auth_with_code(self, code):
        self.client = self.client.auth_code.get_token(code, redirect_uri=self.redirect_uri)

要获取access_token需要

print 'Go to the following link in your browser:' 
print client.authorize_url
code = raw_input('Enter the verification code:')
client.auth_with_code(code)
client.client.token

• auth_with_token也没有返回值或对象

#2. 如果有之前有 token，则可以
access_token = client.auth_with_token(token)

    def auth_with_token(self, token):
        self.client = AccessToken(self.client, token)

后续在refresh token的时候会报错

# Refresh Token(请注意：refresh_token 值仅可在引导用户授权完成后获取)
refresh_token = access_token.client.refresh_token
new_access_token = access_token.refresh_token(refresh_token)

木有refresh_token() 吗

RT

example里的代码运行不了

我尝试过with_password和with_code，每次都是返回403 Forbidden。
我的SCOPE已经 设为shuo_basic_r,shuo_basic_w,douban_basic_common

问题2：我尝试在api的User类下面添加一个自定义方法，在使用的时候会发生找不到此属性，请问我应该怎么做

突然无法授权成功了，是因为频率的原因么，封装以后也看不到错误码

• [2015/06/04 19:33:46] - raise ValueError("No JSON object could be decoded") yq34
  • [2015/06/04 19:33:46] - File "/usr/local/sae/python/lib/python2.7/json/decoder.py", line 384, in raw_decode yq34
  • [2015/06/04 19:33:46] - obj, end = self.raw_decode(s, idx=_w(s, 0).end()) yq34
  • [2015/06/04 19:33:46] - File "/usr/local/sae/python/lib/python2.7/json/decoder.py", line 366, in decode yq34
  • [2015/06/04 19:33:46] - return _default_decoder.decode(s) yq34
  • [2015/06/04 19:33:46] - File "/usr/local/sae/python/lib/python2.7/json/init.py", line 338, in loads yq34
  • [2015/06/04 19:33:46] - return json.loads(self.text, **kwargs) yq34
  • [2015/06/04 19:33:46] - File "/data1/www/htdocs/708/freesz/1/site-packages/requests/models.py", line 741, in json yq34
  • [2015/06/04 19:33:46] - return self.resp.json() yq34
  • [2015/06/04 19:33:46] - File "/data1/www/htdocs/708/freesz/1/site-packages/pyoauth2/libs/response.py", line 42, in parsed yq34
  • [2015/06/04 19:33:46] - opts.update(self.response.parsed) yq34
  • [2015/06/04 19:33:46] - File "/data1/www/htdocs/708/freesz/1/site-packages/pyoauth2/client.py", line 39, in get_token yq34

import 报错

from oauth2 import Client, AccessToken
ImportError: cannot import name AccessToken

client.user.me 提示错误 403 (Forbidden)

测试的 examples 里的 auth_with_password.py 代码。提供了 apikey 和 secret，用户名和密码也提供了。命令行打印
douban_client.api.error.DoubanError: _403 (Forbidden)_ {u'msg': u'need_permission', u'code': 1000, u'request': u'GET /v2/user/~me'}

看到 callback 地址和申请的不一样，以为是这里错了，结果改成一样了还是同样的错误。
提示权限不够，但是 scope 里的 douban_basic_common 和 community_basic_user 应该够了撒？
谢谢关注！

依赖的 pyoauth2 是什么版本的啊？

我下载了 douban-client 的python sdk，测试的时候发现以下错误：

from pyoauth2 import Client, AccessToken
ImportError: cannot import name Client

然后检查了下 pyoauth2 ，从 http://pypi.python.org/pypi/pyoauth2 这里下载的；说的是0.0.4，其实包里面有个文件信息没改，显示还是 0.0.3 。

但是包里可以导入的 是 client, 而不是 Client， 也不能到 AccessToken 。

建议在指明下依赖包的版本吧，最好包含下载链接 :)