HypChat

A Python package for HipChat's v2 JSON REST API. It's based on v2's navigability and self-declaration.

Installation

HypChat can either be installed from PyPI:

pip install hypchat

Or from source:

python setup.py install

Concepts

There are two basic types in HypChat: Linker and RestObject. They are not meant to be instantiated directly but instead created as references from other objects.

Linker

A simple callable that represents an unfollowed reference.

l.url
The URL this object points to
l()
Calling a Linker will perform the request and return a RestObject

RestObject

A subclass of dict, contains additional functionality for links and actions.

Links

As part of the v2 API, all objects have a links property with references to other objects. This is used to create Linker objects as attributes.

For example, all objects have a link called self. This may be referenced as:

obj.self

And the request performed by calling it:

obj.self()

If Title Expansion is desired, just past a list of things to be expanded as the expand keyword argument.

Other Actions

Many of the v2 types define additional types, eg Rooms have methods for messaging, setting the topic, getting the history, and inviting users to the room. These are implemented as methods of subclasses. The complete listing is in the Type List.

Timezone Handling

HypChat uses aware datetime objects throughout by the dateutil module. However, the HipChat API universally uses UTC.

For methods that take a datetime, if a naive object is given, it will be assumed to be in UTC. If this is not what you mean, dateutil.tz has a wonderful selection of timezones available.

Usage

First, create a HypChat object with the token

hc = HypChat("mytoken")

If you use Hipchat Server

hc = HypChat("mytoken", endpoint="https://hipchat.example.com")

There are several root links:

rooms = hc.rooms()
users = hc.users()
emots = hc.emoticons()
caps = hc.capabilities()

In addition, the HypChat object has methods for creating objects and directly referencing the basic types.

For example, you might do:

for room in (r for r in hipchat.rooms(expand='items') if r['last_active'] < datetime.datetime(2013, 12, 1)):
        room.owner.message("Your room is dead; maybe archive it")

Since room.owner is a User stub, not just a generic object. (The Room objects are not stubs, since the expand keyword is used).

Downloading history is as easy as:

list(HypChat(token).get_room(id).history(datetime.datetime.utcnow()).contents())

Note that this may eat up many requests for large rooms.

Navigation

Any time an object is referenced in a value (eg room['owner']), a stub of that object is created, and the full object may be found with .self(). Stubs contain the ID of the object, the name (if applicable), and any links that object has-including self. This can be avoided by using the expand keyword.

Collections-such as rooms, users, and emots above-all have an 'items' key containing their list of things. In addition, the .contents() method will generate all of the items, handling pagination. As usual, object

Console

If you call python -m hypchat, a interactive prompt (using IPython if available) will appear. The environment will contain hipchat, an instance of the HypChat object. The token is pulled from ~/.hypchat, /etc/hypchat, or the environment variable HIPCHAT_TOKEN.

Type List

See TYPES.rst

TODO List

  • API Links


HypChat

HipChat的 v2 JSON REST API 的Python软件包。它基于v2的导航性和自我声明。

安装

HypChat可以从 PyPI 安装:

pip install hypchat

来源

python setup.py install

概念

HypChat有两种基本类型: Linker RestObject 。它们不是要直接实例化,而是创建为来自其他对象的引用。

链接器

一个简单的可调用表示一个取消关注的引用。

l.url
The URL this object points to
l()
Calling a Linker will perform the request and return a RestObject

RestObject

dict 的子类包含链接和操作的其他功能。

Links

作为v2 API的一部分,所有对象都具有引用其他对象的链接属性。这用于将 Linker 对象创建为属性。

例如,所有对象都有一个名为 self 的链接。这可以被引用为:

obj.self

通过调用它执行的请求:

obj.self()

如果希望标题扩展,只需通过事物列表作为展开关键字参数扩展。

Other Actions

许多v2类型定义了其他类型,例如房间具有消息传递方法,设置主题,获取历史记录以及邀请用户进入房间。这些被实现为子类的方法。完整的列表位于类型列表

时区处理

HypChat在 dateutil 模块中使用了意义 datetime 对象。但是,HipChat API通常使用UTC。

对于采用 datetime 的方法,如果给出了一个天真的对象,它将被假定为UTC。如果这不是你的意思, dateutil.tz 有一个很好的选择 timezones 可用。

用法

首先,使用令牌

创建一个HypChat对象
hc = HypChat("mytoken")

如果您使用Hipchat Server

hc = HypChat("mytoken", endpoint="https://hipchat.example.com&#34;)

有几个根链接:

rooms = hc.rooms()
users = hc.users()
emots = hc.emoticons()
caps = hc.capabilities()

此外,HypChat对象具有创建对象并直接引用基本类型的方法。

例如,您可以:

for room in (r for r in hipchat.rooms(expand='items') if r['last_active'] < datetime.datetime(2013, 12, 1)):
        room.owner.message("Your room is dead; maybe archive it")

由于 room.owner 是用户存根,而不仅仅是通用对象。 (Room对象不是存根,因为使用了 expand 关键字。

下载历史记录与以下简单:

list(HypChat(token).get_room(id).history(datetime.datetime.utcnow()).contents())

请注意,这可能会消耗大量房间的许多请求。

导航

只要有一个值被引用(例如 room [‘owner’] ),则创建该对象的一个​​存根,并且可以使用 .self ()。存根包含对象的ID,名称(如果适用)以及对象包含 self 的任何链接。这可以通过使用展开关键字来避免。

集合 - 例如 rooms users emots 上面都有一个‘items’包含他们的事物列表。另外, .contents()方法将生成所有的项目,处理分页。像往常一样,对象

控制台

如果您调用 python -m hypchat ,将出现交互式提示(使用 IPython (如果可用))。环境将包含 hipchat ,这是 HypChat 对象的一个​​实例。令牌从〜/ .hypchat / etc / hypchat 或环境变量 HIPCHAT_TOKEN

类型列表

请参阅 TYPES.rst

TODO列表

  • API链接




相关问题推荐