def list_former(self):
"""List all former groups.
:return: a list of groups
:rtype: :class:`list`
"""
url = utils.urljoin(self.url, 'former')
response = self.session.get(url)
return [Group(self, **group) for group in response.data]
def list_former(self):
"""List all former groups.
:return: a list of groups
:rtype: :class:`list`
"""
url = utils.urljoin(self.url, 'former')
response = self.session.get(url)
return [Group(self, **group) for group in response.data]
def get(self, id):
"""Get a single group by ID.
:param str id: a group ID
:return: a group
:rtype: :class:`~groupy.api.groups.Group`
"""
url = utils.urljoin(self.url, id)
response = self.session.get(url)
return Group(self, **response.data)
def get(self, id):
"""Get a single group by ID.
:param str id: a group ID
:return: a group
:rtype: :class:`~groupy.api.groups.Group`
"""
url = utils.urljoin(self.url, id)
response = self.session.get(url)
return Group(self, **response.data)
def destroy(self, bot_id):
"""Destroy a bot.
:param str bot_id: the ID of the bot to destroy
:return: ``True`` if successful
:rtype: bool
"""
url = utils.urljoin(self.url, 'destroy')
payload = {'bot_id': bot_id}
response = self.session.post(url, json=payload)
return response.ok
def destroy(self, id):
"""Destroy a group.
:param str id: a group ID
:return: ``True`` if successful
:rtype: bool
"""
path = '{}/destroy'.format(id)
url = utils.urljoin(self.url, path)
response = self.session.post(url)
return response.ok
def destroy(self, id):
"""Destroy a group.
:param str id: a group ID
:return: ``True`` if successful
:rtype: bool
"""
path = '{}/destroy'.format(id)
url = utils.urljoin(self.url, path)
response = self.session.post(url)
return response.ok
def rejoin(self, group_id):
"""Rejoin a former group.
:param str group_id: the group_id of a group
:return: the group
:rtype: :class:`~groupy.api.groups.Group`
"""
url = utils.urljoin(self.url, 'join')
payload = {'group_id': group_id}
response = self.session.post(url, json=payload)
return Group(self, **response.data)
def rejoin(self, group_id):
"""Rejoin a former group.
:param str group_id: the group_id of a group
:return: the group
:rtype: :class:`~groupy.api.groups.Group`
"""
url = utils.urljoin(self.url, 'join')
payload = {'group_id': group_id}
response = self.session.post(url, json=payload)
return Group(self, **response.data)
def remove(self, membership_id):
"""Remove a member from the group.
:param str membership_id: the ID of a member in this group
:return: ``True`` if the member was successfully removed
:rtype: bool
"""
path = '{}/remove'.format(membership_id)
url = utils.urljoin(self.url, path)
payload = {'membership_id': membership_id}
response = self.session.post(url, json=payload)
return response.ok
def remove(self, membership_id):
"""Remove a member from the group.
:param str membership_id: the ID of a member in this group
:return: ``True`` if the member was successfully removed
:rtype: bool
"""
path = '{}/remove'.format(membership_id)
url = utils.urljoin(self.url, path)
payload = {'membership_id': membership_id}
response = self.session.post(url, json=payload)
return response.ok
def join(self, group_id, share_token):
"""Join a group using a share token.
:param str group_id: the group_id of a group
:param str share_token: the share token
:return: the group
:rtype: :class:`~groupy.api.groups.Group`
"""
path = '{}/join/{}'.format(group_id, share_token)
url = utils.urljoin(self.url, path)
response = self.session.post(url)
group = response.data['group']
return Group(self, **group)
def join(self, group_id, share_token):
"""Join a group using a share token.
:param str group_id: the group_id of a group
:param str share_token: the share token
:return: the group
:rtype: :class:`~groupy.api.groups.Group`
"""
path = '{}/join/{}'.format(group_id, share_token)
url = utils.urljoin(self.url, path)
response = self.session.post(url)
group = response.data['group']
return Group(self, **group)
def upload(self, fp):
"""Upload image data to the image service.
Call this, rather than :func:`from_file`, you don't want to
create an attachment of the image.
:param file fp: a file object containing binary image data
:return: the URLs for the image uploaded
:rtype: dict
"""
url = utils.urljoin(self.url, 'pictures')
response = self.session.post(url, data=fp.read())
image_urls = response.data
return image_urls
def upload(self, fp):
"""Upload image data to the image service.
Call this, rather than :func:`from_file`, you don't want to
create an attachment of the image.
:param file fp: a file object containing binary image data
:return: the URLs for the image uploaded
:rtype: dict
"""
url = utils.urljoin(self.url, 'pictures')
response = self.session.post(url, files={'file': fp})
image_urls = response.data['payload']
return image_urls
def check(self, results_id):
"""Check for results of a membership request.
:param str results_id: the ID of a membership request
:return: successfully created memberships
:rtype: :class:`list`
:raises groupy.exceptions.ResultsNotReady: if the results are not ready
:raises groupy.exceptions.ResultsExpired: if the results have expired
"""
path = 'results/{}'.format(results_id)
url = utils.urljoin(self.url, path)
response = self.session.get(url)
if response.status_code == 503:
raise exceptions.ResultsNotReady(response)
if response.status_code == 404:
raise exceptions.ResultsExpired(response)
return response.data['members']
def check(self, results_id):
"""Check for results of a membership request.
:param str results_id: the ID of a membership request
:return: successfully created memberships
:rtype: :class:`list`
:raises groupy.exceptions.ResultsNotReady: if the results are not ready
:raises groupy.exceptions.ResultsExpired: if the results have expired
"""
path = 'results/{}'.format(results_id)
url = utils.urljoin(self.url, path)
response = self.session.get(url)
if response.status_code == 503:
raise exceptions.ResultsNotReady(response)
if response.status_code == 404:
raise exceptions.ResultsExpired(response)
return response.data['members']
def post(self, bot_id, text, attachments=None):
"""Post a new message as a bot to its room.
:param str bot_id: the ID of the bot
:param str text: the text of the message
:param attachments: a list of attachments
:type attachments: :class:`list`
:return: ``True`` if successful
:rtype: bool
"""
url = utils.urljoin(self.url, 'post')
payload = dict(bot_id=bot_id, text=text)
if attachments:
payload['attachments'] = [a.to_json() for a in attachments]
response = self.session.post(url, json=payload)
return response.ok
def add_multiple(self, *users):
"""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.
:param args users: the users to add
:return: a membership request
:rtype: :class:`MembershipRequest`
"""
guid = uuid.uuid4()
for i, user_ in enumerate(users):
user_['guid'] = '{}-{}'.format(guid, i)
payload = {'members': users}
url = utils.urljoin(self.url, 'add')
response = self.session.post(url, json=payload)
return MembershipRequest(self, *users, group_id=self.group_id,
**response.data)
def update(self,
id,
name=None,
description=None,
image_url=None,
office_mode=None,
share=None,
**kwargs):
"""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 providing ``office_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 :class:`~groupy.api.groups.Group` object.
:param str id: group ID
:param str name: group name (140 characters maximum)
:param str description: short description (255 characters maximum)
:param str image_url: GroupMe image service URL
:param bool office_mode: (undocumented)
:param bool share: whether to generate a share URL
:return: an updated group
:rtype: :class:`~groupy.api.groups.Group`
"""
path = '{}/update'.format(id)
url = utils.urljoin(self.url, path)
payload = {
'name': name,
'description': description,
'image_url': image_url,
'office_mode': office_mode,
'share': share,
}
payload.update(kwargs)
response = self.session.post(url, json=payload)
return Group(self, **response.data)
def change_owners(self, group_id, owner_id):
"""Change the owner of a group.
.. note:: you must be the owner to change owners
:param str group_id: the group_id of a group
:param str owner_id: the ID of the new owner
:return: the result
:rtype: :class:`~groupy.api.groups.ChangeOwnersResult`
"""
url = utils.urljoin(self.url, 'change_owners')
payload = {
'requests': [{
'group_id': group_id,
'owner_id': owner_id,
}],
}
response = self.session.post(url, json=payload)
result, = response.data['results'] # should be exactly one
return ChangeOwnersResult(**result)
def change_owners(self, group_id, owner_id):
"""Change the owner of a group.
.. note:: you must be the owner to change owners
:param str group_id: the group_id of a group
:param str owner_id: the ID of the new owner
:return: the result
:rtype: :class:`~groupy.api.groups.ChangeOwnersResult`
"""
url = utils.urljoin(self.url, 'change_owners')
payload = {
'requests': [{
'group_id': group_id,
'owner_id': owner_id,
}],
}
response = self.session.post(url, json=payload)
result, = response.data['results'] # should be exactly one
return ChangeOwnersResult(**result)
def add_multiple(self, *users):
"""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.
:param args users: the users to add
:return: a membership request
:rtype: :class:`MembershipRequest`
"""
guid = uuid.uuid4()
for i, user_ in enumerate(users):
user_['guid'] = '{}-{}'.format(guid, i)
payload = {'members': users}
url = utils.urljoin(self.url, 'add')
response = self.session.post(url, json=payload)
return MembershipRequest(self,
*users,
group_id=self.group_id,
**response.data)
def update(self, id, name=None, description=None, image_url=None,
office_mode=None, share=None, **kwargs):
"""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 providing ``office_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 :class:`~groupy.api.groups.Group` object.
:param str id: group ID
:param str name: group name (140 characters maximum)
:param str description: short description (255 characters maximum)
:param str image_url: GroupMe image service URL
:param bool office_mode: (undocumented)
:param bool share: whether to generate a share URL
:return: an updated group
:rtype: :class:`~groupy.api.groups.Group`
"""
path = '{}/update'.format(id)
url = utils.urljoin(self.url, path)
payload = {
'name': name,
'description': description,
'image_url': image_url,
'office_mode': office_mode,
'share': share,
}
payload.update(kwargs)
response = self.session.post(url, json=payload)
return Group(self, **response.data)
def disable(self):
url = utils.urljoin(self.url, 'delete')
response = self.session.post(url)
return response.ok
def update(self, **params):
url = utils.urljoin(self.url, 'update')
response = self.session.post(url, json=params)
return response.data
def get_me(self):
url = utils.urljoin(self.url, 'me')
response = self.session.get(url)
return response.data
def unlike(self):
"""Unlike the message."""
url = utils.urljoin(self.url, 'unlike')
response = self.session.post(url)
return response.ok
def _get_messages(self, path=None, **params):
url = utils.urljoin(self.url, path)
response = self.session.get(url, params=params)
messages = response.data['messages']
return [Message(self, **message) for message in messages]
def __init__(self, session, path=None):
self.session = session
self.url = utils.urljoin(self.base_url, path)
def test_path_appending(self):
url = utils.urljoin(self.url, 'bar')
self.assertEqual(url, 'http://example.com/foo/bar')
def unlike(self):
"""Unlike the message."""
url = utils.urljoin(self.url, 'unlike')
response = self.session.post(url)
return response.ok
def _get_messages(self, path=None, **params):
url = utils.urljoin(self.url, path)
response = self.session.get(url, params=params)
messages = response.data['messages']
return [Message(self, **message) for message in messages]
def test_result_is_base_when_no_path(self):
self.assertEqual(utils.urljoin(self.url), self.url)
