npm 中文文档

douban-client


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

目前已完成的接口有：

  1. ``` sh
  2. * 用户 User
  3. * 广播 Miniblog
  4. * 豆邮 Doumail
  5. * 日记 Note
  6. * 相册 Album
  7. * 图片 Photo
  8. * 读书 Book
  9. * 电影 Movie
  10. * 音乐 Music
  11. * 线上活动 Online
  12. * 同城活动 Event
  13. * 论坛 Discussion
  14. * 回复 Comment

  16. ```

安装


  1. ``` sh
  2. pip install douban-client

  4. ```

或

  1. ``` sh
  2. easy_install douban-client

  4. ```

使用说明


OAuth 2.0 认证


  1. ``` sh
  2. from douban_client import DoubanClient

  4. API_KEY = 'your api key'
  5. API_SECRET = 'your api secret'

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

  11. SCOPE = 'douban_basic_common,shuo_basic_r,shuo_basic_w'

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

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

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

  25. # Token Code
  26. token_code = client.token_code

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

  33. ```

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

Douban API v2 说明


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

  12. ```

接口说明


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

  1. ``` sh
  2. start: 0
  3. count: 20

  5. ```

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

用户 User

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

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

  14. ```

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

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

广播 Miniblog

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

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

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

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

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

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

  25. ```

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

豆邮 Doumail

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

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

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

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

  17. ```

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

日记 Note

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

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

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

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

  20. ```

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

相册 Album

  1. ``` sh
  2. # 以下 id 指相册数字 id
  3. # desc 描述文字
  4. 获取一个相册 client.album.get(id)
  5. 新建一个相册 client.album.new(title, desc)
  6. 更新一个相册 client.album.update(id, title, desc)
  7. 删除一个相册 client.album.delete(id)

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

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

  16. ```

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

图片 Photo

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

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

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

  16. ```

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

读书 Book

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

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

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

  15. ```

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

电影 Movie

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

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

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

  16. ```

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

音乐 Music

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

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

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

  14. ```

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

线上活动 Online

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

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

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

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

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

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

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

  28. ```

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

同城活动 Event

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

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

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

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

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

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

  25. ```

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

论坛 Discussion

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

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

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

  17. ```

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
接口变更:

  1. ``` sh
  2. + note: upload_photo
  3. - user: block, friendships, follow_in_common
  4. - movie: celebrity_works
  5. - miniblog: mentions

  7. ```

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