A Python package for HipChat's v2 JSON REST API. It's based on v2's navigability and self-declaration.
HypChat can either be installed from PyPI:
pip install hypchat
Or from source:
python setup.py install
There are two basic types in HypChat:
RestObject. They are not meant to be instantiated directly but instead created as references from other objects.
A simple callable that represents an unfollowed reference.
- The URL this object points to
- Calling a
Linkerwill perform the request and return a
A subclass of
dict, contains additional functionality for links and actions.
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:
And the request performed by calling it:
If Title Expansion is desired, just past a list of things to be expanded as the
expand keyword argument.
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.
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.
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")
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:
Note that this may eat up many requests for large rooms.
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.
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
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
/etc/hypchat, or the environment variable
- API Links