Advanced Usage¶
This part of the documentation contains explanations and examples of more obscure aspects of Groupy.
Filter Lists¶
FilterList
s are exactly like the built-in
list
but with some convenient additions.
first
and last
¶
first
and last
are merely convenience properties. first
corresponds
to the item at index 0
, while last
corresponds to the item at index
-1
.
>>> from groupy.object.listers import FilterList
>>> fl = FilterList(range(1, 11))
>>> fl
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
>>> fl.first
1
>>> fl.last
10
One important difference, however, is when there are no elements in the list.
>>> fl = FilterList()
>>> fl
[]
>>> print(fl.first)
None
>>> fl[0]
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
IndexError: list index out of range
>>> print(fl.last)
None
>>> fl[-1]
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
IndexError: list index out of range
Note that no exception is raised and None
is returned instead.
filter()
¶
The filter()
method parses its keyword
arguments as filtering criteria. Only the items meeting all criteria are
returned.
The keywords correspond to object properties, but also indicate how to test the
relation to the value of the keyword argument. Thus a keyword-value pair such as
name='Bob'
would keep only those items with a name
property equal to
"Bob"
, whereas a pair like age__lt=20
keeps only those items with an
age
property less than 20
.
This is probably better explained with some simple examples.
>>> from groupy import Group
>>> groups = Group.list()
>>> for g in groups:
... print(g.name)
...
My Family
DevTeam #6
Friday Night Trivia
>>> for g in groups.filter(name__contains='am'):
... print(g.name)
My Family
DevTeam #6
>>>
>>> members = groups.first.members()
>>> for m in members:
... print(m.nickname)
...
Dan the Man
Manuel
Fred
Dan
>>> for m in members.filter(nickname='Dan'):
... print(m.nickname)
...
Dan
>>> for m in members.filter(nickname__contains='Dan'):
... print(m.nickname)
...
Dan the Man
Dan
>>> for m in members.filter(nickname__ge='F'):
... print(m.nickname)
...
Manuel
Fred
Attachments¶
Attachments are a common part of Message
s
and there are several different types. Currently, Groupy supports the
following types of attachments:
Location
- for locationsImage
- for imagesMentions
- for “@” mentionsEmoji
- for emoticonsSplit
- for splitting bills[*]
For all other types of attachments (such as those introduced in the future)
there exists a GenericAttachment
.
[*] | Split attachments are depreciated. |
Types¶
The section covers the various types of attachments and how to create them.
Locations¶
Location
attachments are the simplest of all
attachment types. Each includes a name
, a latitude lat
, and a longitude
lng
. Some location attachments also contain a foursqure_venue_id
.
>>> from groupy import attachments
>>> loc = attachments.Location('My house', lat=34, lng=-84)
>>> loc
Location('My house', lat=34, lng=-84)
>>> loc.name
'My house'
>>> loc.lat, loc.lng
(34, -84)
Images¶
Image
attachments are unique in that they do
not actually contain the image data. Instead, they specify the URL from which
you can obtain the actual image. To create a new image from a local file object,
use the file()
method.
>>> from groupy import attachments
>>> image_attachment = attachments.Image.file(open(filename, 'rb'))
>>> image_attachment
Image(url='http://i.groupme.com/123456789')
>>> image_attachment.url
'http://i.groupme.com/123456789'
We can see that the image has been uploaded in exchange for a URL via the GroupMe image service.
To fetch the actual image from an image attachment, simply use its
download()
method. The image is returned
as a Pillow Image
, so saving it to a file is simple.
>>> image_file = image_attachment.download()
>>> image_file.save(filename)
Mentions¶
Mentions
are a new type of attachment and
have yet to be documented. However, they are simple to understand. Mentions
capture the details necessary to highlight “@” mentions of members in groups.
They contain a list of loci
and an equal-sized list of user_ids
. Let’s
find a good example to demonstrate mentions.
>>> from groupy import Group
>>> message = None
>>> mention = None
>>> for g in Group.list():
... for m in g.messages():
... for a in m.attachments:
... if a.type == 'mentions' and len(a.user_ids) > 1:
... message = m
... mention = a
... break
>>> message.text
'@Bill hey I saw you with @Zoe Childs at the park!'
>>> mention.user_ids
['1234567', '5671234']
>>> mention.loci
[[0, 5], [25, 11]]
As you can see, each element in loci
has two integers, the first of which
indicates the starting index of the mentioning text, while second indicates its
length. The strings in user_ids
correspond by index to the elements in
loci
. You can use the loci
to extract the mentioning portion of the
text, as well as obtain the mentioned member via user_ids
.
>>> for uid, (start, length) in zip(mention.user_ids, mention.loci):
... end = start + length
... uid, message.text[start:end]
... member = message.group.members().filter(user_id=uid).first
... member.uid, member.nickname
('1234567', '@Bill')
('1234567', 'Bill')
('5671234', '@Zoe Childs')
('5671234', 'Zoe Childs')
To create a mention, simply pass in a list
of user IDs and an
equally-sized list
of loci.
>>> from groupy.attachments import Mentions
>>> Mentions(['1234567', '2345671'], [[0, 4], [5, 3]])
Mentions(['1234567', '2345671'])
Emojis¶
Emojis are relatively undocumented but frequently appear in messages. More documentation will come as more is learned.
Emoji attachments have a placeholder
and a charmap
. The placeholder
is a high-point or unicode character designed to mark the location of the emoji
in the text of the message. The charmap
serves as some sort of translation
or lookup tool for obtaining the actual emoji.
Sending Attachments¶
To send an attachment along with a message, simply append it to the
post()
method as another argument.
>>> from groupy import Group
>>> from groupy.attachment import Location
>>> loc = Location.create('My house', lat=33, lng=-84)
>>> group = Group.list().first
>>> group.post("Hey meet me here", loc)
If there are several attachments you’d like to send in a single message, simply keep appending them!
>>> from groupy.attachment import Image
>>> img = Image.file('front-door.png')
>>> group.post("I said meet me here!", loc, img)
Alternatively, you can collect multiple attachments into an
iterable
.
>>> attachments = [img, loc]
>>> group.post("Are you listening?", *attachments)