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:
- 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:
- 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: str
- 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 call Returns: API response data Return type: json
- 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
- 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 image Returns: 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 call Returns: API response data Return type: json
- 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 the group_id (or id since they seem to always be identical). For direct messages, it corresponds to the user_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:
- 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 and after_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, or since_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 containing count and messages
Return type:
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.
Parameters: Returns: a page of messages
Return type:
- post(text, *attachments)[source]¶
Post a message to the recipient.
Although the API limits messages to 450 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 a dict containing nickname and one of email, phone_number, or user_id.
Parameters: Returns: the results ID of the add call
Return type: str
- 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 groups Returns: 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 successful
Return type: bool
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 and user_id properties. If the member does not yet have a GUID, a new one is created and assigned to them (and is returned alongside the nickname and user_id properties).
Returns: the nickname, user_id, and guid of the member Return 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 or email or phone_number
If an identification cannot be created then raise an ValueError.
Parameters: member – either a Member or a dict with the required keys Returns: 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 successful Return 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[source]¶
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 successful Return 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 successful Return 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
- post(text, picture_url=None)[source]¶
Post a message to the group of the bot.
Parameters: Returns: True if successful
Return type: bool
Raises groupy.api.errors.ApiError: if unsuccessful
- 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 successful Return 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 successful
Return type: Raises groupy.api.errors.ApiError: if unsuccessful
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
- 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 and loci. The elements in loci specify the start index and length of the mention, while the elements in user_ids specify by user_id which user was mentioned in the corresponding element of loci.
Note
The length of user_ids must be equal to the length of loci!
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
- 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 otherwise Return type: bool
- iolder()[source]¶
Add in-place the previous (older) page of messages.
Returns: True if successful, False otherwise Return type: bool
- newer()[source]¶
Return the next (newer) page of messages.
Returns: a newer page of messages Return type: MessagePager
- newest[source]¶
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