Developer Docs¶
This section of the documentation is for other developers, and contains the complete information about each package, module, class, and method.
The api
Package¶
This module is a direct wrapper around GroupMe API calls.
The api.endpoint
Module¶
-
class
groupy.api.endpoint.
Bots
[source]¶ Endpoint for the bots API.
Bots can be listed, created, updated, and destroyed. Bots can also post messages to groups.
-
classmethod
create
(name, group_id, avatar_url=None, callback_url=None)[source]¶ Create a new bot.
Parameters: Returns: the new bot
Return type:
-
classmethod
-
class
groupy.api.endpoint.
DirectMessages
[source]¶ Endpoint for the direct message API.
-
classmethod
create
(recipient_id, text, *attachments)[source]¶ Create a direct message to a recipient user.
Parameters: Returns: the created direct message
Return type:
-
classmethod
-
class
groupy.api.endpoint.
Endpoint
[source]¶ An API endpoint capable of building a url and extracting data from the response.
This class serves as the base class for all of the API endpoints.
-
classmethod
build_url
(path=None, *args)[source]¶ Build and return a url extended with path and filled in with args.
Parameters: Returns: a complete URL
Return type:
-
static
clamp
(value, lower, upper)[source]¶ Utility method for clamping a value between a lower and an upper value.
Parameters: - value – the value to clamp
- lower – the “smallest” possible value
- upper – the “largest” possible value
Returns: value such that
lower <= value <= upper
-
classmethod
response
(r)[source]¶ Extract the data from the API response r.
This method essentially strips the actual response of the envelope while raising an ApiError if it contains one or more errors.
Parameters: r ( requests.Response
) – the HTTP response from an API callReturns: API response data Return type: json
-
classmethod
-
class
groupy.api.endpoint.
Groups
[source]¶ Endpoint for the groups API.
Groups can be listed, loaded, created, updated, and destroyed.
-
classmethod
create
(name, description=None, image_url=None, share=True)[source]¶ Create a new group.
Parameters: Returns: the new group
Return type:
-
classmethod
destroy
(group_id)[source]¶ Destroy (or leave) a group.
Note
If you are not the owner of a group, you cannot destroy it.
Parameters: group_id (str) – the ID of the group to destroy/leave Return type: dict
-
classmethod
index
(page=1, per_page=500, former=False)[source]¶ Return a list of groups.
Parameters: Returns: a list of groups
Return type:
-
classmethod
show
(group_id)[source]¶ Return a specific group by its group_id.
Parameters: group_id (str) – the ID of the group to show. Returns: the group with the given group_id Return type: dict
-
classmethod
-
class
groupy.api.endpoint.
Images
[source]¶ Endpoint for the image service API.
GroupMe images are created through an upload service that returns a URL at which it can be accessed.
-
classmethod
create
(image)[source]¶ Submit a new image.
Parameters: image ( file
) – object with a file-like interface and containing an imageReturns: the URL at which the image can be accessed Return type: dict
-
classmethod
response
(r)[source]¶ Extract the data from the image service API response r.
This method basically returns the inner “payload.”
Parameters: r ( requests.Response
) – the HTTP response from an API callReturns: API response data Return type: json
-
classmethod
-
class
groupy.api.endpoint.
Likes
[source]¶ Endpoint for the likes API.
Likes can be created or destroyed.
Note
The
conversation_id
is poorly documented. For messages in a group, it corresponds to thegroup_id
(orid
since they seem to always be identical). For direct messages, it corresponds to theuser_id
of both conversation participants sorted lexicographically and concatenated with a plus sign (“+”).
-
class
groupy.api.endpoint.
Members
[source]¶ Endpoint for the members API.
Members can be added and removed from a group, and the results of adding members can be obtained.
-
classmethod
add
(group_id, *members)[source]¶ Add one or more members to a group.
Parameters: Returns: the results ID for this request
Return type:
-
classmethod
-
class
groupy.api.endpoint.
Messages
[source]¶ Endpoint for the messages API.
Messages can be listed and created.
-
classmethod
create
(group_id, text, *attachments)[source]¶ Create a new message in a group.
All messages must have either text or one attachment. Note that while the API provides for an unlimited number of attachments, most clients can only handle one of each attachment type (location, image, split, or emoji).
Parameters: Returns: the created message
Return type:
-
classmethod
index
(group_id, before_id=None, since_id=None, after_id=None, limit=100)[source]¶ List the messages from a group.
Listing messages gives the most recent 100 by default. Additional messages can be obtained by specifying a reference message, thereby facilitating paging through messages.
Use
before_id
andafter_id
to “page” through messages.since_id
is odd in that it returns the most recent messages since the reference message, which means there may be messages missing between the reference message and the oldest message in the returned list of messages.Note
Only one of
before_id
,after_id
, orsince_id
can be specified in a single call.Parameters: - group_id (str) – the ID of the group from which to list messages
- before_id (str) – a reference message ID; specify this to list messages just prior to it
- since_id (str) – a reference message ID; specify this to list the most recent messages after it (not the messages right after the reference message)
- after_id (str) – a reference message ID; specifying this will return the messages just after the reference message
- limit (int) – a limit on the number of messages returned (between 1 and 100 inclusive)
Returns: a
dict
containingcount
andmessages
Return type: Raises ValueError: if more than one of
before_id
,after_id
orsince_id
are specified
-
classmethod
The api.errors
Module¶
The error
module contains all of the exceptions thrown by the
GroupMe API.
-
exception
groupy.api.errors.
ApiError
[source]¶ Error raised when errors are returned in a GroupMe response.
The api.status
Module¶
The status
module contains API response status code constants and a method
that returns the textual description of such a constant.
-
groupy.api.status.
OK
= 200¶ Success
-
groupy.api.status.
CREATED
= 201¶ Resource was created successfully
-
groupy.api.status.
NO_CONTENT
= 204¶ Resource was deleted successfully
-
groupy.api.status.
NOT_MODIFIED
= 304¶ There was no new data to return
-
groupy.api.status.
BAD_REQUEST
= 400¶ Invalid format or invalid data is specified in the request
-
groupy.api.status.
UNAUTHORIZED
= 401¶ Authentication credentials were missing or incorrect
-
groupy.api.status.
FORBIDDEN
= 403¶ The request was understood, but it has been refused
-
groupy.api.status.
NOT_FOUND
= 404¶ The URI requested is invalid or the requested resource does not exist
-
groupy.api.status.
ENHANCE_YOUR_CLAIM
= 420¶ You are being rate limited
-
groupy.api.status.
INTERNAL_SERVER_ERROR
= 500¶ Something unexpected occurred
-
groupy.api.status.
BAD_GATEWAY
= 502¶ GroupMe is down or being upgraded
-
groupy.api.status.
SERVICE_UNAVAILABLE
= 503¶ The GroupMe servers are up but overloaded with requests
The object
Package¶
This module abstracts the objects returned by GroupMe API calls.
The object.responses
Module¶
This module contains classes that encapsulate the information returned in API responses.
-
class
groupy.object.responses.
Recipient
(endpoint, mkey, idkey, **kwargs)[source]¶ Base class for Group and Member.
Recipients can post and recieve messages.
Parameters: -
messages
(before=None, since=None, after=None, limit=None)[source]¶ Return a page of messages from the recipient.
Note
Only one of
before
,after
, orsince
can be specified in a single call.Parameters: Returns: a page of messages
Return type: Raises ValueError: if more than one of
before
,after
orsince
are specified
-
post
(text, *attachments)[source]¶ Post a message to the recipient.
Although the API limits messages to 1000 characters, this method will split the text component into as many as necessary and include the attachments in the final message. Note that a list of messages sent is always returned, even if it contains only one element.
Parameters: Returns: a list of raw API responses (sorry!)
Return type:
-
-
class
groupy.object.responses.
Group
(**kwargs)[source]¶ A GroupMe group.
-
add
(*members, refresh=False)[source]¶ Add a member to a group.
Each member can be either an instance of
Member
or adict
containingnickname
and one ofemail
,phone_number
, oruser_id
.Parameters: Returns: the results ID of the add call
Return type:
-
classmethod
create
(name, description=None, image_url=None, share=True)[source]¶ Create a new group.
Parameters: Returns: the newly created group
Return type:
-
destroy
()[source]¶ Disband (destroy) a group that you created.
If unsuccessful, this raises an
ApiError
Returns: OK
-
classmethod
list
(former=False)[source]¶ List all of your current or former groups.
Parameters: former (bool) – True
if former groups should be listed,False
(default) lists current groupsReturns: a list of groups Return type: FilterList
-
members
()[source]¶ Return a list of the members in the group.
Returns: the members of the group Return type: FilterList
-
remove
(member, refresh=False)[source]¶ Remove a member from the group.
Note
The group must contain the member to be removed. This will not be the case if the group information has not been requested since the member was added. When in doubt, use the
refresh()
method to update the internal list of members before attempting to remove them.Parameters: Returns: True
if successfulReturn type: Raises groupy.api.errors.ApiError: if removal is not successful
-
-
class
groupy.object.responses.
Member
(**kwargs)[source]¶ A GroupMe member.
-
identification
()[source]¶ Return the identification of the member.
A member is identified by their
nickname
anduser_id
properties. If the member does not yet have a GUID, a new one is created and assigned to them (and is returned alongside thenickname
anduser_id
properties).Returns: the nickname
,user_id
, andguid
of the memberReturn type: dict
-
classmethod
identify
(member)[source]¶ Return or create an identification for a member.
Member identification is required for adding them to groups. If member is a
dict
, it must contain the following keys:nickname
user_id
oremail
orphone_number
If an identification cannot be created then raise an
ValueError
.Parameters: member – either a Member
or adict
with the required keysReturns: the identification of member Return type: dict
Raises ValueError: if an identification cannot be made
-
-
class
groupy.object.responses.
Message
(recipient, **kwargs)[source]¶ A GroupMe message.
Parameters: recipient ( Recipient
) – the reciever of the message-
like
()[source]¶ Like the message.
Returns: True
if successfulReturn type: bool Raises groupy.api.errors.ApiError: if unsuccessful
-
likes
()[source]¶ Return a
FilterList
of the members that like the message.Returns: a list of the members who “liked” this message Return type: FilterList
-
recipient
¶ Return the source of the message.
If the message is a direct message, this returns a member. Otherwise, it returns a group.
Returns: the source of the message Return type: Recipient
-
unlike
()[source]¶ Unlike the message.
Returns: True
if successfulReturn type: bool Raises groupy.api.errors.ApiError: if unsuccessful
-
-
class
groupy.object.responses.
Bot
(**kwargs)[source]¶ A GroupMe bot.
Each bot belongs to a single group. Messages posted by the bot are always posted to the group to which the bot belongs.
-
classmethod
create
(name, group, avatar_url=None, callback_url=None)[source]¶ Create a new bot.
Parameters: Returns: the new bot
Return type:
-
destroy
()[source]¶ Destroy the bot.
Returns: True
if successfulReturn type: bool Raises groupy.api.errors.ApiError: if unsuccessful
-
classmethod
list
()[source]¶ Return a list of your bots.
Returns: a list of your bots Return type: FilterList
-
classmethod
-
class
groupy.object.responses.
User
(**kwargs)[source]¶ A GroupMe user.
This is you, as determined by your API key.
-
classmethod
disable_sms
()[source]¶ Disable SMS mode.
Disabling SMS mode causes push notifications to resume and SMS text messages to be discontinued.
Returns: True
if successfulReturn type: bool
Raises groupy.api.errors.ApiError: if unsuccessful
-
classmethod
enable_sms
(duration=4, registration_token=None)[source]¶ Enable SMS mode.
Each client has a unique registration token that allows it to recieve push notifications. Enabling SMS mode causes GroupMe to suppress those push notification and send SMS text messages instead for a number of hours no greater than 48.
Note
If the
registration_token
is omitted, no push notifications will be suppressed and the user will recieve both text messages and push notifications.Parameters: Returns: True
if successfulReturn type: Raises groupy.api.errors.ApiError: if unsuccessful
-
classmethod
get
()[source]¶ Return your user information.
Returns: your user information Return type: dict
-
nickname
¶ Your user name.
-
classmethod
The object.attachments
Module¶
This module contains classes for the different types of attachments.
-
class
groupy.object.attachments.
Attachment
(type)[source]¶ Base class for attachments.
Parameters: type (str) – the type of the attachment
-
class
groupy.object.attachments.
AttachmentFactory
[source]¶ A factory for creating attachments from dictionaries.
-
classmethod
create
(**kwargs)[source]¶ Create and return an attachment.
Parameters: type (str) – the type of attachment to create; if unrecognized, a generic attachment is returned Returns: a subclass of Attachment
-
classmethod
-
class
groupy.object.attachments.
Emoji
(placeholder, charmap)[source]¶ An attachment containing emoticons.
Emoji attachments do not contain any emoticon images. Instead, a placeholder specifies the location of the emoticon in the text, and a
charmap
facilitates translation into the emoticons.Parameters:
-
class
groupy.object.attachments.
GenericAttachment
(type, **kwargs)[source]¶ A generic attachment.
This attachment accepts any keyword arguments, but must be given a particular type.
Parameters: type (str) – the type of attachment
-
class
groupy.object.attachments.
Image
(url, source_url=None)[source]¶ An image attachemnt.
Image attachments do not contain an image. Instead, they specify a URL from which the image can be downloaded and must have a domain of “i.groupme.com”. Such URLs are known as “i” URLs, and are from the GroupMe image service.
Note
Use the direct initializer if and only if the image already has a known GroupMe image service URL. Otherwise, use the
file()
method.Parameters: -
download
()[source]¶ Download the image data of the image attachment.
Returns: the actual image the image attachment references Return type: PIL.Image.Image
-
-
class
groupy.object.attachments.
Location
(name, lat, lng, foursquare_venue_id=None)[source]¶ An attachment that specifies a geo-location.
In addition to latitude and longitude, every location attachment also specifies a name. Some (especially older) location attachments also contain a
foursquare_venue_id
attribute.Parameters:
-
class
groupy.object.attachments.
Mentions
(user_ids, loci=None)[source]¶ An attachment that specifies “@” mentions.
Mentions are a new addition to the types of attachments. Each contains two parallel lists:
user_ids
andloci
. The elements inloci
specify the start index and length of the mention, while the elements inuser_ids
specify by user_id which user was mentioned in the corresponding element ofloci
.Note
The length of
user_ids
must be equal to the length ofloci
!Parameters:
The object.listers
Module¶
-
class
groupy.object.listers.
FilterList
[source]¶ A filterable list.
Acts just like a regular
list
, except it can be filtered using a special keyword syntax. Also, the first and last items are special properties.-
filter
(**kwargs)[source]¶ Filter the list and return a new instance.
Arguments are keyword arguments only, and can be appended with operator method names to indicate relationships other than equals. For example, to filter the list down to only items whose
name
property contains “ie”:new_list = filter_list.filter(name__contains='ie')
As another example, this filters the list down to only those with a
created
property that is less than 1234567890:new_list = filter_list.filter(created__lt=1234567890)
Acceptable operators are:
__lt
: less than__gt
: greater than__contains
: contains__eq
: equal to__ne
: not equal to__le
: less than or equal to__ge
: greater than or equal to
Use of any operator listed here results in a
InvalidOperatorError
.Returns: a new list with potentially less items than the original Return type: FilterList
-
first
¶ The first element in the list.
-
last
¶ The last element in the list.
-
-
class
groupy.object.listers.
MessagePager
(group, messages, backward=False)[source]¶ A filterable, extendable page of messages.
Parameters: -
inewer
()[source]¶ Add in-place the next (newer) page of messages.
Returns: True
if successful,False
otherwiseReturn type: bool
-
iolder
()[source]¶ Add in-place the previous (older) page of messages.
Returns: True
if successful,False
otherwiseReturn type: bool
-
newer
()[source]¶ Return the next (newer) page of messages.
Returns: a newer page of messages Return type: MessagePager
-
newest
¶ Return the newest message in the list.
Returns: the newest message in the list Return type: Message
-
older
()[source]¶ Return the previous (older) page of messages.
Returns: an older page of messages Return type: MessagePager
-
The config
Module¶
The config
module contains all the configuration options.
-
groupy.config.
API_URL
= 'https://api.groupme.com/v3'¶ The URL for the GroupMe API
-
groupy.config.
IMAGE_API_URL
= 'https://image.groupme.com'¶ The URL for the GroupMe Image Service API
-
groupy.config.
KEY_LOCATION
= '~/.groupy.key'¶ Full path to the file in which your access token can be found