Internal modules¶
Classes documented here are used by other parts of the library, and are typically not needed for client use of the API.
HTTP API requests¶
-
class
skpy.conn.
SkypeConnection
[source]¶ The main connection class – handles all requests to API resources.
To authenticate with a username and password, use
setUserPwd()
to store the credentials. Token files can be specified withsetTokenFile()
.-
sess
¶ Shared session used for all API requests.
- Type
-
endpoints
¶ Container of
SkypeEndpoint
instances for the current session.- Type
-
Auth
= ('SkypeToken', 'Authorize', 'RegToken')¶ Authentication types for different API calls.
-
Auth.
SkypeToken
¶ Add an
X-SkypeToken
header with the Skype token.
-
Auth.
Authorize
¶ Add an
Authorization
header with the Skype token.
-
Auth.
RegToken
¶ Add a
RegistrationToken
header with the registration token.
- Type
-
-
static
handle
(*codes, **kwargs)[source]¶ Method decorator: if a given status code is received, re-authenticate and try again.
- Parameters
codes (int list) – status codes to respond to
regToken (bool) – whether to try retrieving a new token on error
- Returns
decorator function, ready to apply to other methods
- Return type
method
-
classmethod
externalCall
(method, url, codes=(200, 201, 204, 207), **kwargs)[source]¶ Make a public API call without a connected
Skype
instance.The obvious implications are that no authenticated calls are possible, though this allows accessing some public APIs such as join URL lookups.
- Parameters
method (str) – HTTP request method
url (str) – full URL to connect to
codes (int list) – expected HTTP response codes for success
kwargs (dict) – any extra parameters to pass to
requests.request()
- Returns
response object provided by
requests
- Return type
- Raises
SkypeAuthException – if an authentication rate limit is reached
SkypeApiException – if a successful status code is not received
-
closure
(method, *args, **kwargs)[source]¶ Create a generic closure to call a method with fixed arguments.
-
__call__
(method, url, codes=(200, 201, 202, 204, 207), auth=None, headers=None, **kwargs)[source]¶ Make an API call. Most parameters are passed directly to
requests
.Set codes to a list of valid HTTP response codes – an exception is raised if the response does not match.
If authentication is required, set
auth
to one of theAuth
constants.- Parameters
method (str) – HTTP request method
url (str) – full URL to connect to
codes (int list) – expected HTTP response codes for success
auth (Auth) – authentication type to be included
headers (dict) – additional headers to be included
kwargs (dict) – any extra parameters to pass to
requests.request()
- Returns
response object provided by
requests
- Return type
- Raises
SkypeAuthException – if an authentication rate limit is reached
SkypeApiException – if a successful status code is not received
-
syncStateCall
(method, url, params={}, **kwargs)[source]¶ Follow and track sync state URLs provided by an API endpoint, in order to implicitly handle pagination.
In the first call,
url
andparams
are used as-is. If asyncState
endpoint is provided in the response, subsequent calls go to the latest URL instead.- Parameters
method (str) – HTTP request method
url (str) – full URL to connect to
params (dict) – query parameters to include in the URL
kwargs (dict) – any extra parameters to pass to
__call__()
-
setTokenFile
(path)[source]¶ Enable reading and writing session tokens to a file at the given location.
- Parameters
path (str) – path to file used for token storage
-
readToken
()[source]¶ Attempt to re-establish a connection using previously acquired tokens.
If the Skype token is valid but the registration token is invalid, a new endpoint will be registered.
- Raises
SkypeAuthException – if the token file cannot be used to authenticate
-
writeToken
()[source]¶ Store details of the current connection in the named file.
This can be used by
readToken()
to re-authenticate at a later time.
-
verifyToken
(auth)[source]¶ Ensure the authentication token for the given auth method is still valid.
- Parameters
auth (Auth) – authentication type to check
- Raises
SkypeAuthException – if Skype auth is required, and the current token has expired and can’t be renewed
-
skypeTokenClosure
(method, *args, **kwargs)[source]¶ Replace the stub
getSkypeToken()
method with one that connects using the given credentials. Avoids storing the account password in an accessible way.
-
setUserPwd
(user, pwd)[source]¶ Replace the stub
getSkypeToken()
method with one that connects via SOAP login using the given credentials. Avoids storing the account password in an accessible way.
-
liveLogin
(user, pwd)[source]¶ Obtain connection parameters from the Microsoft account login page, and perform a login with the given email address or Skype username, and its password. This emulates a login to Skype for Web on
login.live.com
.Note
Microsoft accounts with two-factor authentication enabled are not supported, and will cause a
SkypeAuthException
to be raised. See the exception definitions for other possible causes.- Parameters
- Returns
Skype token, and associated expiry if known
- Return type
- Raises
SkypeAuthException – if the login request is rejected
SkypeApiException – if the login form can’t be processed
-
soapLogin
(user, pwd)[source]¶ Perform a login with the given email address or Skype username, and its password, using the Microsoft account SOAP login APIs.
Note
Microsoft accounts with two-factor authentication enabled are supported if an application-specific password is provided. Skype accounts must be linked to a Microsoft account with an email address, otherwise
SkypeAuthException
will be raised. See the exception definitions for other possible causes.- Parameters
- Returns
Skype token, and associated expiry if known
- Return type
- Raises
SkypeAuthException – if the login request is rejected
SkypeApiException – if the login form can’t be processed
-
guestLogin
(url, name)[source]¶ Connect to Skype as a guest, joining a given conversation.
In this state, some APIs (such as contacts) will return 401 status codes. A guest can only communicate with the conversation they originally joined.
- Parameters
- Raises
SkypeAuthException – if the login request is rejected
SkypeApiException – if the login form can’t be processed
-
getSkypeToken
()[source]¶ A wrapper for the default login provider that applies the previously given username and password.
- Raises
SkypeAuthException – if credentials were never provided
-
refreshSkypeToken
()[source]¶ Take the existing Skype token and refresh it, to extend the expiry time without other credentials.
- Raises
SkypeAuthException – if the login request is rejected
SkypeApiException – if the login form can’t be processed
-
getUserId
()[source]¶ Ask Skype for the authenticated user’s identifier, and store it on the connection object.
-
-
class
skpy.conn.
SkypeAuthProvider
[source]¶ A base class for authentication providers. Subclasses should implement the
auth()
method.-
auth
(*args, **kwargs)[source]¶ Authenticate a user, given some form of identification.
- Returns
Skype token, and associated expiry if known
- Return type
- Raises
SkypeAuthException – if the login request is rejected
SkypeApiException – if the login forms can’t be processed
-
-
class
skpy.conn.
SkypeAPIAuthProvider
[source]¶ An authentication provider that connects via the Skype API. Only compatible with Skype usernames.
-
auth
(user, pwd)[source]¶ Perform a login with the given Skype username and its password. This emulates a login to Skype for Web on
api.skype.com
.- Parameters
- Returns
Skype token, and associated expiry if known
- Return type
- Raises
SkypeAuthException – if the login request is rejected
SkypeApiException – if the login form can’t be processed
-
-
exception
skpy.conn.
LiveAuthSuccess
(t)[source]¶ An exception used to capture the ‘t’ value needed during Microsoft account authentication.
-
class
skpy.conn.
SkypeLiveAuthProvider
[source]¶ An authentication provider that connects via Microsoft account authentication.
-
checkUser
(user)[source]¶ Query a username or email address to see if a corresponding Microsoft account exists.
-
auth
(user, pwd)[source]¶ Obtain connection parameters from the Microsoft account login page, and perform a login with the given email address or Skype username, and its password. This emulates a login to Skype for Web on
login.live.com
.Note
Microsoft accounts with two-factor authentication enabled are not supported, and will cause a
SkypeAuthException
to be raised. See the exception definitions for other possible causes.- Parameters
- Returns
Skype token, and associated expiry if known
- Return type
- Raises
SkypeAuthException – if the login request is rejected
SkypeApiException – if the login form can’t be processed
-
-
class
skpy.conn.
SkypeSOAPAuthProvider
[source]¶ An authentication provider that connects via Microsoft account SOAP authentication.
-
auth
(user, pwd)[source]¶ Perform a SOAP login with the given email address or Skype username, and its password.
Note
Microsoft accounts with two-factor authentication enabled must provide an application-specific password.
- Parameters
- Returns
Skype token, and associated expiry if known
- Return type
- Raises
SkypeAuthException – if the login request is rejected
SkypeApiException – if the login form can’t be processed
-
-
class
skpy.conn.
SkypeGuestAuthProvider
[source]¶ An authentication provider that connects and joins a public conversation via a join URL.
-
auth
(url, name)[source]¶ Connect to Skype as a guest, joining a given conversation.
In this state, some APIs (such as contacts) will return 401 status codes. A guest can only communicate with the conversation they originally joined.
- Parameters
- Returns
Skype token, and associated expiry if known
- Return type
- Raises
SkypeAuthException – if the login request is rejected
SkypeApiException – if the login form can’t be processed
-
-
class
skpy.conn.
SkypeRefreshAuthProvider
[source]¶ An authentication provider that connects via the Skype API. Only compatible with Skype usernames.
-
auth
(token)[source]¶ Take an existing Skype token and refresh it, to extend the expiry time without other credentials.
- Parameters
token (str) – existing Skype token
- Returns
Skype token, and associated expiry if known
- Return type
- Raises
SkypeAuthException – if the login request is rejected
SkypeApiException – if the login form can’t be processed
-
-
class
skpy.conn.
SkypeRegistrationTokenProvider
[source]¶ An authentication provider that handles the handshake for a registration token.
-
auth
(skypeToken)[source]¶ Request a new registration token using a current Skype token.
- Parameters
skypeToken (str) – existing Skype token
- Returns
- registration token, associated expiry if known,
resulting endpoint hostname, endpoint if provided
- Return type
- Raises
SkypeAuthException – if the login request is rejected
SkypeApiException – if the login form can’t be processed
-
-
class
skpy.conn.
SkypeEndpoint
[source]¶ An endpoint represents a single point of presence within Skype.
Typically, a user with multiple devices would have one endpoint per device (desktop, laptop, mobile and so on).
Endpoints are time-sensitive – they lapse after a short time unless kept alive (by
ping()
or otherwise).-
__init__
(conn, id)[source]¶ Create a new instance based on a newly-created endpoint identifier.
- Parameters
conn (SkypeConnection) – parent connection instance
id (str) – endpoint identifier as generated by the API
-
config
(name='skype')[source]¶ Configure this endpoint to allow setting presence.
- Parameters
name (str) – display name for this endpoint
-
ping
(timeout=12)[source]¶ Send a keep-alive request for the endpoint.
- Parameters
timeout (int) – maximum amount of time for the endpoint to stay active
-
subscribe
()[source]¶ Subscribe to contact and conversation events. These are accessible through
getEvents()
.
-
subscribePresence
(contacts)[source]¶ Enable presence subscriptions for the authenticated user’s contacts.
- Parameters
contacts (SkypeContacts) – contact list to select user IDs
-
getEvents
()[source]¶ Retrieve a list of events since the last poll. Multiple calls may be needed to retrieve all events.
If no events occur, the API will block for up to 30 seconds, after which an empty list is returned.
If any event occurs whilst blocked, it is returned immediately.
- Returns
list of events, possibly empty
- Return type
SkypeEvent
list
-
Miscellaneous¶
-
class
skpy.core.
SkypeObj
[source]¶ A basic Skype object. Holds references to the parent
Skype
instance, and a raw object from the API.-
attrs
¶ List of defined fields for the class. Used by
initAttrs()
to create an__init__()
method.- Type
-
defaults
¶ Collection of default values when any keyword arguments are omitted from the constructor.
- Type
-
__init__
(skype=None, raw=None)[source]¶ Instantiate a plain instance of this class, and store a reference to the Skype object for later API calls.
Normally this method won’t be called or implemented directly.
Implementers should make use of
fromRaw()
and theinitAttrs()
decorator instead.
-
classmethod
rawToFields
(raw={})[source]¶ Convert the raw properties of an API response into class fields. Override to process additional values.
-
classmethod
fromRaw
(skype=None, raw={})[source]¶ Create a new instance based on the raw properties of an API response.
This can be overridden to automatically create subclass instances based on the raw content.
-
merge
(other)[source]¶ Copy properties from other into self, skipping
None
values. Also merges the raw data.- Parameters
other (SkypeObj) – second object to copy fields from
-
-
class
skpy.core.
SkypeObjs
[source]¶ A basic Skype collection. Acts as a container for objects of a given type.
-
__init__
(skype=None)[source]¶ Create a new container object. The
synced
state and internalcache
are initialised here.- Parameters
skype (Skype) – parent Skype instance
-
-
class
skpy.core.
SkypeEnum
[source]¶ A basic implementation for an enum.
-
exception
skpy.core.
SkypeApiException
[source]¶ An exception thrown for errors specific to external API calls.
Arguments will usually be of the form (
message
,response
).
-
exception
skpy.core.
SkypeAuthException
[source]¶ An exception thrown when authentication cannot be completed.
Arguments will usually be of the form (
message
,response
). If the server provided an error message, it will be present in a third argument.Unfortunately there are many possible reasons why a login may be rejected, including but not limited to:
an incorrect username or password
two-factor authentication
rate-limiting after multiple failed login attempts
a captcha being required
an update to the Terms of Service that must be accepted
-
class
skpy.util.
SkypeUtils
[source]¶ A collection of miscellaneous static methods used throughout the library.
-
Status
= ('Offline', 'Hidden', 'Busy', 'Away', 'Idle', 'Online')¶ Types of user availability.
-
Status.
Offline
¶ User is not connected.
-
Status.
Hidden
¶ User is pretending to be offline. Shows as hidden to the current user, offline to anyone else.
-
Status.
Busy
¶ User wishes not to be disturbed. Disables notifications on some clients (e.g. on the desktop).
-
Status.
Away
¶ User has explicitly marked themselves as away. Alternatively, this may just be an alias for idle.
-
Status.
Idle
¶ User is online but not active. Messages will likely be delivered as normal, though may not be read.
-
Status.
Online
¶ User is available to talk.
- Type
-
-
static
noPrefix
(s)[source]¶ Remove the type prefix from a chat identifier (e.g.
8:
for a one-to-one,19:
for a group).
-
static
userToId
(url)[source]¶ Extract the username from a contact URL.
Matches addresses containing
users/<user>
orusers/ME/contacts/<user>
.
-
static
chatToId
(url)[source]¶ Extract the conversation ID from a conversation URL.
Matches addresses containing
conversations/<chat>
.
-
static
initAttrs
(cls)[source]¶ Class decorator: automatically generate an
__init__
method that expects args from cls.attrs and stores them.- Parameters
cls (class) – class to decorate
- Returns
same, but modified, class
- Return type
class
-
static
convertIds
(*types, **kwargs)[source]¶ Class decorator: add helper methods to convert identifier properties into SkypeObjs.
- Parameters
types (str list) – simple field types to add properties for (
user
,users
orchat
)user (str list) – attribute names to treat as single user identifier fields
users (str list) – attribute names to treat as user identifier lists
chat (str list) – attribute names to treat as chat identifier fields
- Returns
decorator function, ready to apply to other methods
- Return type
method
-
static
truthyAttrs
(cls)[source]¶ Class decorator: override __bool__ to set truthiness based on any attr being present.
- Parameters
cls (class) – class to decorate
- Returns
same, but modified, class
- Return type
class
-
static
exhaust
(fn, transform=None, *args, **kwargs)[source]¶ Repeatedly call a function, starting with init, until false-y, yielding each item in turn.
The
transform
parameter can be used to map a collection to another format, for example iterating over adict
by value rather than key.Use with state-synced functions to retrieve all results.
-
static
cacheResult
(fn)[source]¶ Method decorator: calculate the value on first access, produce the cached value thereafter.
If the function takes arguments, the cache is a dictionary using all arguments as the key.
- Parameters
fn (method) – function to decorate
- Returns
wrapper function with caching
- Return type
method
-