API documentation¶
Authenticator object¶
-
class
yampy.
Authenticator
(client_id, client_secret, oauth_dialog_url=None, oauth_base_url=None, proxies=None)¶ Responsible for authenticating users against the Yammer API.
The OAuth2 authentication process involves several steps:
- Send the user to the URL returned by
authorization_url
. They can use this page to grant your application access to their account. - Yammer redirects them to the
redirect_uri
you provided with a code that can be exchanged for an access token. - Exchange the code for an access token using the
fetch_access_token
method.
-
__init__
(client_id, client_secret, oauth_dialog_url=None, oauth_base_url=None, proxies=None)¶ Initializes a new Authenticator. The client_id and client_secret identify your application, you acquire them when registering your application with Yammer. See http://www.yammer.com/client_applications
Keyword arguments can be used to modify the URLs generated in this class, e.g. to avoid hitting the live API from a client application’s test suite. Pass None to use the default URLs.
oauth_dialog_url
– The URL the user must visit to authorize the application. Used by the authorization_url method.oauth_base_url
– The base URL for OAuth API requests, e.g. token exchange. Used byfetch_access_data
orfetch_access_token
.proxies
– provide a proxies dictionary to be used by the client.
Returns the URL the user needs to visit to grant your application access to their Yammer account. When they are done they will be redirected to the
redirect_uri
you provide with a code that can be exchanged for an access token.
-
fetch_access_data
(code)¶ Returns the complete response from the Yammer API access token request. This is a dict with “user”, “network” and “access_token” keys.
You can access the token itself as:
response.access_token.token
If you only intend to make use of the token, you can use the
fetch_access_token
method instead for convenience.
-
fetch_access_token
(code)¶ Convenience method to exchange a code for an access token, discarding the other user and network data that the Yammer API returns with the access token.
If you require user and network information, you should use the
fetch_access_data
method instead.
- Send the user to the URL returned by
Yammer object¶
-
class
yampy.
Yammer
(access_token=None, base_url=None, proxies=None)¶ Main entry point for accessing the Yammer API.
Essentially this is just a Factory class that provides instances of various classes that interact directly with the API. For example, the
messages
method returns aMessagesAPI
object.-
__init__
(access_token=None, base_url=None, proxies=None)¶ Initialize a new Yammer instance.
access_token
identifies the current user. You can acquire an access token using anyampy.Authenticator
.base_url
defaults to the live Yammer API. Provide a different base URL to make requests against some other server, e.g. a fake in your application’s test suite.
-
client
¶ Returns a
yampy.client.Client
object which can be used to make HTTP requests to any of the Yammer REST API endpoints.You should use this if there isn’t a more specific interface available for the request you want to make, e.g. if you want to request users you should use the
users
method instead of theclient
method.
-
current_network
(include_suspended=None)¶ Get details on the networks available to this user
-
groups
¶ Returns a
yampy.apis.GroupsAPI
object which can be used to call the Yammer API’s user-related endpoints.
-
messages
¶ Returns a
yampy.apis.MessagesAPI
object which can be used to call the Yammer API’s message-related endpoints.
-
relationships
¶ Returns a
yampy.apis.RelationshipsAPI
object which can be used to call the Yammer API’s relations endpoints.
-
topics
¶ Returns a
yampy.apis.TopicsAPI
object which can be used to call the Yammer API’s topic-related endpoints.
-
users
¶ Returns a
yampy.apis.UsersAPI
object which can be used to call the Yammer API’s user-related endpoints.
-
MessagesAPI object¶
-
class
yampy.apis.
MessagesAPI
(client)¶ Provides an interface for accessing the message related endpoints of the Yammer API. You should not instantiate this class directly; use the
yampy.Yammer.messages()
method instead.-
__init__
(client)¶ Initializes a new MessagesAPI that will use the given
client
object to make HTTP requests.
-
about_topic
(topic_id)¶ Returns the messages about a topic
-
all
(older_than=None, newer_than=None, limit=None, threaded=None)¶ Returns public messages from the current user’s network.
Customize the response using the keyword arguments:
older_than
– Only fetch messages older than this message ID.newer_than
– Only fetch messages newer than this message ID.limit
– Only fetch this many messages.threaded
– Set toTrue
to only receive the first message of each thread, or to"extended"
to recieve the first and two newest messages from each thread.
-
create
(body, group_id=None, replied_to_id=None, direct_to_id=None, topics=[], broadcast=None, open_graph_object={})¶ Posts a new message to Yammer. Returns the new message in the same format as the various message listing methods (
all()
,sent()
, etc.).The following keyword arguments are supported:
group_id
– Send this message to the group identified by group_id.replied_to_id
– This message is a reply to the message identified by replied_to_id.direct_to_id
– Send this as a direct message to the user identified by direct_to_id.topics
– A list of topics for the message. Topics should be given as strings. There cannot be more than 20 topics for one message.broadcast
– Set this to True to send a broadcast message. Only network admins have permission to send broadcast messages.open_graph_object
– A dict describing an open graph object to attach to the message. It supports the following keys:url
(required)title
image
description
object_type
site_name
fetch
(set toTrue
to derive other OG data from the URL)meta
(for custom structured data)
-
delete
(message_id)¶ Deletes the message identified by message_id.
-
email
(message_id)¶ Emails the message identified by message_id to the authenticated user.
-
find
(message_id)¶ Returns the message identified by the given message_id.
-
from_followed_conversations
(older_than=None, newer_than=None, limit=None, threaded=None)¶ Returns messages from users the current user follows, or groups the current user belongs to.
See the
all()
method for a description of the keyword arguments.
-
from_group
(group_id, older_than=None, newer_than=None, limit=None, threaded=None)¶ Returns messages from specific group, specified with group_id.
See the
all()
method for a description of the keyword arguments.
-
from_my_feed
(older_than=None, newer_than=None, limit=None, threaded=None)¶ Returns messages from the current user’s feed. This will either correspond to
from_top_conversations()
orfrom_followed_conversations()
depending on the user’s settings.See the
all()
method for a description of the keyword arguments.
-
from_top_conversations
(older_than=None, newer_than=None, limit=None, threaded=None)¶ Returns messages from the current user’s top conversations.
See the
all()
method for a description of the keyword arguments.
-
from_user
(user_id, older_than=None, newer_than=None, limit=None, threaded=None)¶ Returns messages that were posted by the user identified by user_id.
See the
all()
method for a description of the keyword arguments.
-
in_thread
(thread_id, older_than=None, newer_than=None, limit=None, threaded=None)¶ Returns messages that belong to the thread identified by thread_id.
See the
all()
method for a description of the keyword arguments.
-
like
(message_id)¶ The current user likes the message identified by message_id.
-
private
(older_than=None, newer_than=None, limit=None, threaded=None)¶ Returns of the private messages received by the current user.
See the
all()
method for a description of the keyword arguments.
-
received
(older_than=None, newer_than=None, limit=None, threaded=None)¶ Returns messages received by the current user.
See the
all()
method for a description of the keyword arguments.
-
sent
(older_than=None, newer_than=None, limit=None, threaded=None)¶ Returns of the current user’s sent messages.
See the
all()
method for a description of the keyword arguments.
-
unlike
(message_id)¶ Removes the current user’s “like” from the message identified by message_id.
-
RelationshipsAPI object¶
-
class
yampy.apis.
RelationshipsAPI
(client)¶ Provides an interface for accessing the relations related endpoints of the Yammer API. You should not instantiate this class directly; use the
yampy.Yammer.relationships()
method instead.-
__init__
(client)¶ Initializes a new RelationshipsAPI that will use the given
client
object to make HTTP requests.
-
all
(user_id=None)¶ Returns the relationships for the current user or the user specified
-
UsersAPI object¶
-
class
yampy.apis.
UsersAPI
(client)¶ Provides an interface for accessing the user related endpoints of the Yammer API. You should not instantiate this class directly; use the
yampy.Yammer.users()
method instead.-
__init__
(client)¶ Initializes a new UsersAPI that will use the given client object to make HTTP requests.
-
all
(page=None, letter=None, sort_by=None, reverse=None)¶ Returns all the users in the current user’s network.
Customize the response using the keyword arguments:
- page – Enable pagination, and return the nth page of 50 users.
- letter – Only return users whose username begins with this letter.
- sort_by – Sort users by “messages” or “followers” (default order is alphabetical by username).
- reverse – Reverse sort order.
-
create
(email_address, full_name=None, job_title=None, location=None, im=None, work_telephone=None, work_extension=None, mobile_telephone=None, significant_other=None, kids_names=None, interests=None, summary=None, expertise=None, education=None, previous_companies=None)¶ Creates a new user.
Most of the parameter names are self explanatory, and accept strings. A few expect specific formats:
im
– Provide instant messages details as a dict withprovider
andusername
keys, e.g.{"provider": "gtalk", "username": "me@gmail.com"}
education
– Provide education details as a list of dicts. Each dict should have the keys:school
,degree
,description
,start_year
andend_year
.previous_companies
– Provide previous employment details as a list of dicts. Each dict should have the keys:company
,position
,start_year
,end_year
.
-
delete
(user_id)¶ Delete the user identified by user_id.
-
find
(user_id)¶ Returns the user identified by the given user_id.
-
find_by_email
(email_address)¶ Returns the user identified by the given email_address.
-
find_current
(include_group_memberships=None, include_followed_users=None, include_followed_tags=None)¶ Returns the current user.
-
in_group
(group_id, page=None)¶ Returns all the users belonging to the group identified by the given group_id.
Use the page parameter to enable pagination and retrieve a specific page of users.
-
suspend
(user_id)¶ Suspend the user identified by user_id.
-
update
(user_id, full_name=None, job_title=None, location=None, im=None, work_telephone=None, work_extension=None, mobile_telephone=None, significant_other=None, kids_names=None, interests=None, summary=None, expertise=None, education=None, previous_companies=None)¶ Updates the user identified by the given user_id.
For more information on parameter formats, see the
create()
method.
-
GroupsAPI object¶
-
class
yampy.apis.
GroupsAPI
(client)¶ Provides an interface for accessing the groups related endpoints of the Yammer API. You should not instantiate this class directly; use the
yampy.Yammer.groups()
method instead.-
__init__
(client)¶ Initializes a new GroupsAPI that will use the given client object to make HTTP requests.
-
all
(mine=None, reverse=None)¶ Returns all the groups in the current user’s network.
Customize the response using the keyword arguments:
- mine – Only return group of current user.
- reverse – return group in descending order by name.
-
create
(name, private=False)¶ Create a group.
Return Group info
-
delete
(group_id)¶ Delete a group.
Return True if success
-
find
(group_id)¶ Returns the group identified by the given group_id.
-
join
(group_id)¶ Join the group identified by the given group_id.
Return True
-
leave
(group_id)¶ Leave the group identified by the given group_id.
Return True
-
members
(group_id, page=None, reverse=None)¶ Returns the group identified by the given group_id.
Customize the response using the keyword arguments:
- page – Enable pagination, and return the nth page of 50 users.
-
TopicsAPI object¶
-
class
yampy.apis.
TopicsAPI
(client)¶ Provides an interface for accessing the topics related endpoints of the Yammer API. You should not instantiate this class directly; use the
yampy.Yammer.topics()
method instead.-
__init__
(client)¶ Initializes a new TopicsAPI that will use the given
client
object to make HTTP requests.
-
topic
(topic_id)¶ Returns the users that have used the topic specified by the numeric topic_id.
-
Client object¶
-
class
yampy.client.
Client
(access_token=None, base_url=None, proxies=None)¶ A client for the Yammer API.
-
__init__
(access_token=None, base_url=None, proxies=None)¶
-
delete
(path, **kwargs)¶ Makes an HTTP DELETE request to the Yammer API.
The path should be the path of an API endpoint, e.g. “/messages/123”
-
get
(path, **kwargs)¶ Makes an HTTP GET request to the Yammer API. Any keyword arguments will be converted to query string parameters.
The path should be the path of an API endpoint, e.g. “/messages”
-
post
(path, **kwargs)¶ Makes an HTTP POST request to the Yammer API. Any keyword arguments will be sent as the body of the request.
The path should be the path of an API endpoint, e.g. “/messages”
-
put
(path, **kwargs)¶ Makes an HTTP PUT request to the Yammer API. Any keyword arguments will be sent as the body of the request.
The path should be the path of an API endpoint, e.g. “/users/123”
-
GenericModel object¶
-
class
yampy.models.
GenericModel
¶ A dict subclass that provides access to its members as if they were attributes.
Note that an attribute that has the same name as one of dict’s existing method (
keys
,items
, etc.) will not be accessible as an attribute.-
classmethod
from_json
(json_string)¶ Parses the given json_string, returning GenericModel instances instead of dicts.
-
classmethod
Errors¶
Exception classes representing error responses from the Yammer API.
-
exception
yampy.errors.
InvalidAccessTokenError
¶ Raised when a request is made with an access token that has expired or has been revoked by the user.
-
exception
yampy.errors.
InvalidEducationRecordError
¶ Raised when creating a user with an education record that doesn’t include all of the requried information.
-
exception
yampy.errors.
InvalidMessageError
¶ Super class for the various kinds of errors that can occur when creating a message.
-
exception
yampy.errors.
InvalidOpenGraphObjectError
¶ Raised when an invalid Open Graph object is attached to a new message.
-
exception
yampy.errors.
InvalidPreviousCompanyRecord
¶ Raised when creating a user with a previous_companies record that doesn’t include all of the required fields.
-
exception
yampy.errors.
InvalidUserError
¶ Super class for the various kinds of errors that can occur when creating a user.
-
exception
yampy.errors.
NotFoundError
¶ Raised when the Yammer API responds with an HTTP 404 Not Found error.
-
exception
yampy.errors.
RateLimitExceededError
¶ Raised when a request is rejected because the rate limit has been exceeded.
-
exception
yampy.errors.
ResponseError
¶ Raised when the Yammer API responds with an HTTP error, and there isn’t a more specific subclass that represents the situation.
-
exception
yampy.errors.
TooManyTopicsError
¶ Raised when a message cannot be created because too many topics have been specified.
Raised when the Yammer API responds with an HTTP 401 Unauthorized error. This may mean that the access token you are using is invalid.