Developer Docs¶
This section of the documentation is for other developers, and contains the complete information about each package, module, class, and method.
groupy.client
¶
groupy.api
¶
groupy.api.attachments
¶
-
class
groupy.api.attachments.
Attachment
(type, **data)[source]¶ Base attachment class.
Every attachment has a type and additional data.
Parameters: - type (str) – attachment type
- data (kwargs) – additional attachment data
-
classmethod
from_bulk_data
(attachments)[source]¶ Create multiple attachments from a list of attachment data.
Returns: attachment sublcass objects Return type: list
-
class
groupy.api.attachments.
Images
(session, path=None)[source]¶ A manager for handling image uploads/downloads.
-
base_url
= 'https://image.groupme.com/'¶ the base url for the pictures API
-
download
(image, url_field='url', suffix=None)[source]¶ Download the binary data of an image attachment.
Parameters: Returns: binary image data
Return type:
-
download_avatar
(image, url_field='url')[source]¶ Downlaod the binary data of an image attachment at avatar size.
Parameters: url_field (str) – the field of the image with the right URL Returns: binary image data Return type: bytes
-
download_large
(image, url_field='url')[source]¶ Downlaod the binary data of an image attachment at large size.
Parameters: url_field (str) – the field of the image with the right URL Returns: binary image data Return type: bytes
-
download_preview
(image, url_field='url')[source]¶ Downlaod the binary data of an image attachment at preview size.
Parameters: url_field (str) – the field of the image with the right URL Returns: binary image data Return type: bytes
-
from_file
(fp)[source]¶ Create a new image attachment from an image file.
Parameters: fp (file) – a file object containing binary image data Returns: an image attachment Return type: Image
-
upload
(fp)[source]¶ Upload image data to the image service.
Call this, rather than
from_file()
, you don’t want to create an attachment of the image.Parameters: fp (file) – a file object containing binary image data Returns: the URLs for the image uploaded Return type: dict
-
-
class
groupy.api.attachments.
Location
(lat, lng, name, foursqure_venue_id=None)[source]¶ A location attachment.
Parameters:
groupy.api.base
¶
groupy.api.blocks
¶
-
class
groupy.api.blocks.
Block
(manager, **data)[source]¶ A block between you and another user.
-
class
groupy.api.blocks.
Blocks
(session, user_id)[source]¶ Blocks manager.
Parameters: - session (
Session
) – the request session - user_id (str) – your user ID
-
between
(other_user_id)[source]¶ Check if there is a block between you and the given user.
Returns: True
if the given user has been blockedReturn type: bool
- session (
groupy.api.bots
¶
-
class
groupy.api.bots.
Bots
(session)[source]¶ A bot manager.
-
create
(name, group_id, avatar_url=None, callback_url=None, dm_notification=None, **kwargs)[source]¶ Create a new bot in a particular group.
Parameters: Returns: the new bot
Return type:
-
groupy.api.chats
¶
-
class
groupy.api.chats.
Chat
(manager, **data)[source]¶ A chat with another user.
-
post
(text=None, attachments=None)[source]¶ Post a message to the chat.
Note
This endpoint seems to only work with an application API token. If you’re getting HTTP 429 Too Many Requests, create a new application at https://dev.groupme.com/applications and use the API token provided at the end of that process.
Parameters: Returns: True
if successfulReturn type:
-
groupy.api.groups
¶
-
class
groupy.api.groups.
ChangeOwnersResult
(group_id, owner_id, status)[source]¶ The result of requesting a group owner change.
Parameters: -
is_success
¶ Return
True
if the request was successful.
-
status_texts
= {'200': 'everything checked out', '400': 'the group is already owned by that user', '403': 'you must own a group to change its owner', '404': 'either the new owner is not a member of the group, or the new owner or the group were not found', '405': 'request object is missing required field or any of the required fields is not an ID'}¶ a map of statuses to meanings
-
success_code
= '200'¶ the status that represents success
-
-
class
groupy.api.groups.
Group
(manager, **data)[source]¶ A group.
-
change_owners
(user_id)[source]¶ Change the owner of the group.
Note that the user must be a member of the group.
Parameters: user_id (str) – the user_id of the new owner Returns: the result Return type: ChangeOwnersResult
-
create_bot
(name, avatar_url=None, callback_url=None, dm_notification=None, **kwargs)[source]¶ Create a new bot in a particular group.
Parameters: Returns: the new bot
Return type:
-
destroy
()[source]¶ Destroy the group.
Note that you must be the owner.
Returns: True
if successfulReturn type: bool
-
get_membership
()[source]¶ Get your membership.
Note that your membership may not exist. For example, you do not have a membership in a former group. Also, the group returned by the API when rejoining a former group does not contain your membership. You must call
refresh_from_server()
to update the list of members.Returns: your membership in the group Return type: Member
Raises: groupy.exceptions.MissingMembershipError – if your membership is not in the group data
-
post
(text=None, attachments=None)[source]¶ Post a new message to the group.
Parameters: Returns: the message
Return type:
-
rejoin
()[source]¶ Rejoin the group.
Note that this must be a former group.
Returns: a current (not former) group Return type: Group
-
-
class
groupy.api.groups.
Groups
(session)[source]¶ A group manager.
-
change_owners
(group_id, owner_id)[source]¶ Change the owner of a group.
Note
you must be the owner to change owners
Parameters: Returns: the result
Return type:
-
create
(name, description=None, image_url=None, share=None, **kwargs)[source]¶ Create a new group.
Note that, although possible, there may be issues when not using an image URL from GroupMe’s image service.
Parameters: Returns: a new group
Return type:
-
destroy
(id)[source]¶ Destroy a group.
Parameters: id (str) – a group ID Returns: True
if successfulReturn type: bool
-
get
(id)[source]¶ Get a single group by ID.
Parameters: id (str) – a group ID Returns: a group Return type: Group
-
join
(group_id, share_token)[source]¶ Join a group using a share token.
Parameters: Returns: the group
Return type:
-
list
(page=1, per_page=10, omit=None)[source]¶ List groups by page.
The API allows certain fields to be excluded from the results so that very large groups can be fetched without exceeding the maximum response size. At the time of this writing, only ‘memberships’ is supported.
Parameters: Returns: a list of groups
Return type:
-
list_all
(per_page=10, omit=None)[source]¶ List all groups.
Since the order of groups is determined by recent activity, this is the recommended way to obtain a list of all groups. See
list()
for details aboutomit
.Parameters: Returns: a list of groups
Return type:
-
rejoin
(group_id)[source]¶ Rejoin a former group.
Parameters: group_id (str) – the group_id of a group Returns: the group Return type: Group
-
update
(id, name=None, description=None, image_url=None, office_mode=None, share=None, **kwargs)[source]¶ Update the details of a group.
Note
There are significant bugs in this endpoint! 1. not providing
name
produces 400: “Topic can’t be blank” 2. not providingoffice_mode
produces 500: “sql: Scan error on column index 14: sql/driver: couldn’t convert <nil> (<nil>) into type bool”Note that these issues are “handled” automatically when calling update on a
Group
object.Parameters: Returns: an updated group
Return type:
-
groupy.api.memberships
¶
-
class
groupy.api.memberships.
Member
(manager, group_id, **data)[source]¶ A user’s membership in a particular group.
Members have both an ID and a membership ID. The membership ID is unique to the combination of user and group.
It can be helpful to think of a “memmber” as a “membership.” That is, a specific user in a specific group. Thus, two
Member
objects are equal only if theirid
fields are equal,. As a consequence, the twoMember
objects representing user A in two groups X and Y will _not_ be equal.Parameters: -
add_to_group
(group_id, nickname=None)[source]¶ Add the member to another group.
If a nickname is not provided the member’s current nickname is used.
Parameters: Returns: a membership request
Return type:
-
is_blocked
()[source]¶ Check whether you have the user of the membership blocked.
Returns: True
if the user is blockedReturn type: bool
-
post
(text=None, attachments=None, source_guid=None)[source]¶ Post a direct message to the user.
Parameters: Returns: the message sent
Return type:
-
-
class
groupy.api.memberships.
MembershipRequest
(manager, *requests, **data)[source]¶ A membership request.
Parameters: - manager (
Manager
) – a manager for the group of the membership - requests (args) – the members requested to be added
- data (kwargs) – the membership request response data
-
class
Results
(members, failures)¶ -
failures
¶ Alias for field number 1
-
members
¶ Alias for field number 0
-
-
get
()[source]¶ Return the results now.
Returns: the membership request results
Return type: Results
Raises: - groupy.exceptions.ResultsNotReady – if the results are not ready
- groupy.exceptions.ResultsExpired – if the results have expired
-
get_failed_requests
(results)[source]¶ Return the requests that failed.
Parameters: results ( list
) – the results of a membership request checkReturns: the failed requests Return type: generator
-
get_new_members
(results)[source]¶ Return the newly added members.
Parameters: results ( list
) – the results of a membership request checkReturns: the successful requests, as Members
Return type: generator
- manager (
-
class
groupy.api.memberships.
Memberships
(session, group_id)[source]¶ A membership manager for a particular group.
Parameters: - session (
Session
) – the request session - group_id (str) – the group_id of a group
-
add
(nickname, email=None, phone_number=None, user_id=None)[source]¶ Add a user to the group.
You must provide either the email, phone number, or user_id that uniquely identifies a user.
Parameters: Returns: a membership request
Return type:
-
add_multiple
(*users)[source]¶ Add multiple users to the group at once.
Each given user must be a dictionary containing a nickname and either an email, phone number, or user_id.
Parameters: users (args) – the users to add Returns: a membership request Return type: MembershipRequest
-
check
(results_id)[source]¶ Check for results of a membership request.
Parameters: results_id (str) – the ID of a membership request
Returns: successfully created memberships
Return type: Raises: - groupy.exceptions.ResultsNotReady – if the results are not ready
- groupy.exceptions.ResultsExpired – if the results have expired
- session (
groupy.api.messages
¶
-
class
groupy.api.messages.
DirectMessage
(manager, **data)[source]¶ A direct message between two users.
-
class
groupy.api.messages.
DirectMessages
(session, other_user_id)[source]¶ Manager for direct messages with a particular user.
Parameters: - session – request session
- other_user_id (str) – user_id of another user
-
create
(text=None, attachments=None, source_guid=None)[source]¶ Send a new direct message to the user.
Only provide the source_guid if you want to control it.
Note
This endpoint seems to only work with an application API token. If you’re getting HTTP 429 Too Many Requests, create a new application at https://dev.groupme.com/applications and use the API token provided at the end of that process.
Parameters: Returns: the message sent
Return type:
-
list
(before_id=None, since_id=None, **kwargs)[source]¶ Return a page of direct messages.
The messages come in reversed order (newest first). Note you can only provide _one_ of
before_id
,since_id
.Parameters: Returns: direct messages
Return type:
-
list_all
(before_id=None, since_id=None, **kwargs)[source]¶ Return all direct messages.
The messages come in reversed order (newest first). Note you can only provide _one_ of
before_id
,since_id
.Parameters: Returns: direct messages
Return type: generator
-
list_all_before
(message_id, **kwargs)[source]¶ Return all direct messages created before a message.
This can be used to page backwards through messages.
Parameters: message_id (str) – the ID of a message Returns: direct messages Return type: generator
-
list_before
(message_id, **kwargs)[source]¶ Return a page of direct messages created before a message.
This can be used to page backwards through messages.
Parameters: message_id (str) – the ID of a message Returns: direct messages Return type: MessageList
-
list_since
(message_id, **kwargs)[source]¶ Return a page of direct messages created since a message.
This is used to fetch the most recent messages after another. There may exist messages between the one given and the ones returned.
Parameters: message_id (str) – the ID of a message Returns: direct messages Return type: MessageList
-
class
groupy.api.messages.
Gallery
(session, group_id)[source]¶ Manager for messages in the gallery.
This endpoint is undocumented!
Parameters: - session – request session
- group_id (str) – group_id for a particular group
-
class
groupy.api.messages.
GenericMessage
(manager, conversation_id, **data)[source]¶ A message.
Parameters: - manager – a message manager
- conversation_id (str) – the ID for the conversation
- data (kwargs) – the data of the message
-
preview_length
= 42¶ number of characters seen in the repr output
-
class
groupy.api.messages.
Leaderboard
(session, group_id)[source]¶ Manager for messages on the leaderboard.
-
list
(period)[source]¶ List most liked messages for a given period.
Parameters: period (str) – either “day”, “week”, or “month” Returns: the messages Return type: list
-
list_day
()[source]¶ List most liked messages for the last day.
Returns: the messages Return type: list
-
-
class
groupy.api.messages.
Likes
(session, conversation_id, message_id)[source]¶ Manager for likes/unlikes of a particular message.
The message can be from either a group or a chat.
Parameters:
-
class
groupy.api.messages.
Messages
(session, group_id)[source]¶ A message manager for a particular group.
Parameters: - session (
Session
) – the request session - group_id (str) – the group_id of a group
-
create
(text=None, attachments=None, source_guid=None)[source]¶ Create a new message in the group.
Parameters: Returns: the created message
Return type:
-
list
(before_id=None, since_id=None, after_id=None, limit=20)[source]¶ Return a page of group messages.
The messages come in reversed order (newest first). Note you can only provide _one_ of
before_id
,since_id
, orafter_id
.Parameters: Returns: group messages
Return type:
-
list_after
(message_id, limit=None)[source]¶ Return a page of group messages created after a message.
This is used to page forwards through messages.
Parameters: Returns: group messages
Return type:
-
list_all
(limit=None)[source]¶ Return all group messages.
Parameters: limit (int) – maximum number of messages per page Returns: group messages Return type: generator
-
list_all_after
(message_id, limit=None)[source]¶ Return all group messages created after a message.
Parameters: Returns: group messages
Return type: generator
-
list_all_before
(message_id, limit=None)[source]¶ Return all group messages created before a message.
Parameters: Returns: group messages
Return type: generator
-
list_before
(message_id, limit=None)[source]¶ Return a page of group messages created before a message.
This can be used to page backwards through messages.
Parameters: Returns: group messages
Return type:
-
list_since
(message_id, limit=None)[source]¶ Return a page of group messages created since a message.
This is used to fetch the most recent messages after another. There may exist messages between the one given and the ones returned. Use
list_after()
to retrieve newer messages without skipping any.Parameters: Returns: group messages
Return type:
- session (
groupy.pagers
¶
-
class
groupy.pagers.
GroupList
(manager, endpoint, **params)[source]¶ Pager for groups.
-
default_params
= {'page': 1}¶ default to the first page
-
-
class
groupy.pagers.
MessageList
(manager, endpoint, **params)[source]¶ Pager for messages.
-
default_mode
= 'before_id'¶ the default mode param
-
classmethod
detect_mode
(**params)[source]¶ Detect which listing mode of the given params.
Params kwargs params: the params Returns: one of the available modes Return type: str Raises: ValueError – if multiple modes are detected
-
fetch_next
()[source]¶ Fetch the next page of results.
Returns: the next page of results Return type: list
-
get_next_page_param
(item)[source]¶ Return the param from the given item.
Parameters: item – the item that has the next page param Returns: next page param value
-
modes
= {'after_id': -1, 'before_id': -1, 'since_id': 0}¶ all possible mode params and the index for their next page params
-
-
class
groupy.pagers.
Pager
(manager, endpoint, **params)[source]¶ Class for iterating over multiple pages of results.
This is a generic, base class. To create a specific type of pager, provide a definition for
set_next_page_params
in a subclass.Parameters: - manager (
Manager
) – the manager from which to get results - endpoint (func) – a callable from which results can be fetched
- params (kwargs) – initial params to pass to the manager
-
autopage
()[source]¶ Iterate through results from all pages.
Returns: all results Return type: generator
-
default_params
= {}¶ the base set of params
-
fetch
()[source]¶ Fetch the current page of results.
Returns: the current page of results Return type: list
- manager (
groupy.exceptions
¶
-
exception
groupy.exceptions.
ApiError
(message=None)[source]¶ Base exception for all GroupMe API errors.
-
exception
groupy.exceptions.
BadResponse
(response, message=None)[source]¶ Exception raised when the status code of the response was 400 or more.
Parameters:
-
exception
groupy.exceptions.
FindError
(message, objects, tests, matches=None)[source]¶ Exception raised when the number of results is not 1.
-
exception
groupy.exceptions.
GroupyError
(message=None)[source]¶ Base exception for all Groupy exceptions.
Parameters: message (str) – a description of the exception -
message
= None¶ a description of the exception
-
-
exception
groupy.exceptions.
InvalidJsonError
(response, message='The JSON was incomplete/invalid')[source]¶ Exception raised for incomplete/invalid JSON in a response.
-
exception
groupy.exceptions.
MissingMembershipError
(group_id, user_id, message=None)[source]¶ Exception raied when your membership could not be found in a group.
-
exception
groupy.exceptions.
MissingMetaError
(response, message='The response contained no meta data')[source]¶ Exception raised for a response that lacks meta data.
-
exception
groupy.exceptions.
MissingResponseError
(response, message='The response contained no response data')[source]¶ Exception raised for a response that lacks response data.
-
exception
groupy.exceptions.
MultipleMatchesError
(objects, tests, matches)[source]¶ Exception raised when the number of results exceeds 1.
-
exception
groupy.exceptions.
NoMatchesError
(objects, tests)[source]¶ Exception raised when the number of results is 0.
-
exception
groupy.exceptions.
NoResponse
(request, *args, **kwargs)[source]¶ Exception raised when the API server could not be reached.
Parameters: - request (
PreparedRequest
) – the original request that was made - message (str) – a description of the exception
- request (
-
exception
groupy.exceptions.
ResultsError
(response, message)[source]¶ Exception raised for asynchronous results.
Parameters: