Package: hypchat
A Python package for HipChat’sv2 JSON REST API. It’s based on v2’s navigability and self-declaration.InstallationHypChat can either be installed fromPyPI:pip install hypchatOr fromsource:python setup.py installConceptsThere are two basic types in HypChat:LinkerandRestObject. They are not meant to be instantiated directly but instead created as references from other objects.LinkerA simple callable that represents an unfollowed reference.l.urlThe URL this object points tol()Calling aLinkerwill perform the request and return aRestObjectRestObjectA subclass ofdict, contains additional functionality for links and actions.LinksAs part of the v2 API, all objects have alinksproperty with references to other objects. This is used to createLinkerobjects as attributes.For example, all objects have a link calledself. This may be referenced as:obj.selfAnd the request performed by calling it:obj.self()IfTitle Expansionis desired, just past a list of things to be expanded as theexpandkeyword argument.Other ActionsMany 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 theType List.Timezone HandlingHypChat uses awaredatetimeobjects throughout by thedateutilmodule. However, the HipChat API universally uses UTC.For methods that take adatetime, if a naive object is given, it will be assumed to be in UTC. If this is not what you mean,dateutil.tzhas a wonderful selection oftimezonesavailable.UsageFirst, create a HypChat object with the tokenhc = HypChat("mytoken")If you use Hipchat Serverhc = 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")Sinceroom.owneris a User stub, not just a generic object. (The Room objects are not stubs, since theexpandkeyword 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.NavigationAny time an object is referenced in a value (egroom['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-includingself. This can be avoided by using theexpandkeyword.Collections-such asrooms,users, andemotsabove-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, objectConsoleIf you callpython-mhypchat, a interactive prompt (usingIPythonif available) will appear. The environment will containhipchat, an instance of theHypChatobject. The token is pulled from~/.hypchat,/etc/hypchat, or the environment variableHIPCHAT_TOKEN.Type ListSeeTYPES.rstTODO ListAPI Links