GData.OAuth2Authorizer¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37), GData.Authorizer (5)
Structs:: GObject.ObjectClass (5)

class	`new` (client_id, client_secret, redirect_uri, service_type)
class	`new_for_authorization_domains` (client_id, client_secret, redirect_uri, authorization_domains)
	`build_authentication_uri` (login_hint, include_granted_scopes)
	`dup_refresh_token` ()
	`get_client_id` ()
	`get_client_secret` ()
	`get_locale` ()
	`get_proxy_resolver` ()
	`get_redirect_uri` ()
	`get_timeout` ()
	`request_authorization` (authorization_code, cancellable)
	`request_authorization_async` (authorization_code, cancellable, callback, *user_data)
	`request_authorization_finish` (async_result)
	`set_locale` (locale)
	`set_proxy_resolver` (proxy_resolver)
	`set_refresh_token` (refresh_token)
	`set_timeout` (timeout)

Virtual Methods¶

Inherited:: GObject.Object (7), GData.Authorizer (5)

Properties¶

Name	Type	Flags	Short Description
`client-id`	`str`	r/w/co	A client ID for your application.
`client-secret`	`str`	r/w/co	Client secret provided by Google.
`locale`	`str`	r/w	The locale to use for network requests, in UNIX locale format.
`proxy-resolver`	`Gio.ProxyResolver`	r/w	A `Gio.ProxyResolver` used to determine a proxy URI.
`redirect-uri`	`str`	r/w/co	Redirect URI to send the response from the authorisation request to.
`refresh-token`	`str`	r/w	The server provided refresh token.
`timeout`	`int`	r/w	A timeout, in seconds, for network operations.

Signals¶

Inherited:: GObject.Object (1)

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent	`GObject.Object`	r

Class Details¶

class GData.OAuth2Authorizer(**kwargs)¶

Bases:: GObject.Object, GData.Authorizer
Abstract:: No
Structure:: GData.OAuth2AuthorizerClass

All the fields in the GData.OAuth2Authorizer structure are private and should never be accessed directly.

New in version 0.17.0.

classmethod new(client_id, client_secret, redirect_uri, service_type)¶

Parameters:

client_id (str) – your application’s client ID
client_secret (str) – your application’s client secret
redirect_uri (str) – authorisation redirect URI
service_type (GObject.GType) – the GObject.GType of a GData.Service subclass which the GData.OAuth2Authorizer will be used with

Returns:

a new GData.OAuth2Authorizer; unref with GObject.Object.unref()

Return type:

GData.OAuth2Authorizer

Creates a new GData.OAuth2Authorizer. The client_id must be unique for your application, and as registered with Google, and the client_secret must be paired with it.

New in version 0.17.0.

classmethod new_for_authorization_domains(client_id, client_secret, redirect_uri, authorization_domains)¶

Parameters:

client_id (str) – your application’s client ID
client_secret (str) – your application’s client secret
redirect_uri (str) – authorisation redirect URI
authorization_domains ([GData.AuthorizationDomain]) – a non-empty list of GData.AuthorizationDomains to be authorized against by the GData.OAuth2Authorizer

Returns:

a new GData.OAuth2Authorizer; unref with GObject.Object.unref()

Return type:

GData.OAuth2Authorizer

Creates a new GData.OAuth2Authorizer. The client_id must be unique for your application, and as registered with Google, and the client_secret must be paired with it.

New in version 0.17.0.

build_authentication_uri(login_hint, include_granted_scopes)¶

Parameters:

login_hint (str or None) – optional e-mail address or sub identifier for the user
include_granted_scopes (bool) – True to enable incremental authorisation

Returns:

the authentication URI to open in a web browser; free with GLib.free()

Return type:

str

Build an authentication URI to open in the user’s web browser (or an embedded browser widget). This will display an authentication page from Google, including an authentication form and confirmation of the authorisation domains being requested by this GData.Authorizer. The user will authenticate in the browser, then an authorisation code will be returned via the GData.OAuth2Authorizer :redirect-uri, ready to be passed to GData.OAuth2Authorizer.request_authorization().

If login_hint is non-None, it will be passed to the server as a hint of which user is attempting to authenticate, which can be used to pre-fill the e-mail address box in the authentication form.

If include_granted_scopes is True, the authentication request will automatically include all authorisation domains previously granted to this user/application pair, allowing for incremental authentication — asking for permissions as needed, rather than all in one large bundle at the first opportunity. If include_granted_scopes is False, incremental authentication will not be enabled, and only the domains passed to the GData.OAuth2Authorizer constructor will eventually be authenticated. See the

reference documentation for more details.

New in version 0.17.0.

dup_refresh_token()¶

Returns:: the authorizer’s refresh token
Return type:: str

Returns the authorizer’s refresh token, GData.OAuth2Authorizer :refresh-token, as set by client code previously on the GData.OAuth2Authorizer, or as returned by the most recent authentication operation.

New in version 0.17.2.

get_client_id()¶

Returns:: the authorizer’s client ID
Return type:: str

Returns the authorizer’s client ID, GData.OAuth2Authorizer :client-id, as specified on constructing the GData.OAuth2Authorizer.

New in version 0.17.0.

get_client_secret()¶

Returns:: the authorizer’s client secret
Return type:: str

Returns the authorizer’s client secret, GData.OAuth2Authorizer :client-secret, as specified on constructing the GData.OAuth2Authorizer.

New in version 0.17.0.

get_locale()¶

Returns:: the current locale
Return type:: str or None

Returns the locale currently being used for network requests, or None if the locale is the default.

New in version 0.17.0.

get_proxy_resolver()¶

Returns:: a Gio.ProxyResolver, or None
Return type:: Gio.ProxyResolver or None

Gets the Gio.ProxyResolver on the GData.OAuth2Authorizer's Soup.Session.

New in version 0.17.0.

get_redirect_uri()¶

Returns:: the authorizer’s redirect URI
Return type:: str

Returns the authorizer’s redirect URI, GData.OAuth2Authorizer :redirect-uri, as specified on constructing the GData.OAuth2Authorizer.

New in version 0.17.0.

get_timeout()¶

Returns:: the timeout, or 0
Return type:: int

Gets the GData.OAuth2Authorizer :timeout property; the network timeout, in seconds.

New in version 0.17.0.

request_authorization(authorization_code, cancellable)¶

Parameters:

authorization_code (str) – code returned from the authentication page
cancellable (Gio.Cancellable or None) – a Gio.Cancellable, or None

Raises:

GLib.Error

Returns:

True on success, False otherwise

Return type:

bool

Request an authorisation code from the user’s web browser is converted to authorisation (access and refresh) tokens. This is the final step in the authentication process; once complete, the GData.OAuth2Authorizer should be fully authorised for its domains.

On failure, GData.ServiceError.FORBIDDEN will be returned if the user or server denied the authorisation request. GData.ServiceError.PROTOCOL_ERROR will be returned if the server didn’t follow the expected protocol. Gio.IOErrorEnum.CANCELLED will be returned if the operation was cancelled using cancellable.

New in version 0.17.0.

request_authorization_async(authorization_code, cancellable, callback, *user_data)¶

Parameters:

authorization_code (str) – code returned from the authentication page
cancellable (Gio.Cancellable or None) – an optional Gio.Cancellable, or None
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when authorization is finished
user_data (object or None) – data to pass to the callback function

Asynchronous version of GData.OAuth2Authorizer.request_authorization().

New in version 0.17.0.

request_authorization_finish(async_result)¶

Parameters:: async_result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: True if authorization was successful, False otherwise
Return type:: bool

Finishes an asynchronous authorization operation started with GData.OAuth2Authorizer.request_authorization_async().

New in version 0.17.0.

set_locale(locale)¶

Parameters:: locale (str or None) – the new locale in UNIX locale format, or None for the default locale

Set the locale used for network requests to locale, given in standard UNIX locale format. See GData.OAuth2Authorizer :locale for more details.

Note that while it’s possible to change the locale after sending network requests (i.e. calling GData.OAuth2Authorizer.build_authentication_uri() for the first time), it is unsupported, as the server-side software may behave unexpectedly. The only supported use of this method is after creation of the authorizer, but before any network requests are made.

New in version 0.17.0.

set_proxy_resolver(proxy_resolver)¶

Parameters:: proxy_resolver (Gio.ProxyResolver or None) – a Gio.ProxyResolver, or None

Sets the Gio.ProxyResolver on the Soup.Session used internally by the given GData.OAuth2Authorizer.

New in version 0.17.0.

set_refresh_token(refresh_token)¶

Parameters:: refresh_token (str or None) – the new refresh token, or None to clear authorization

Sets the authorizer’s refresh token, GData.OAuth2Authorizer :refresh-token. This is used to periodically refresh the access token. Set it to None to clear the current authentication from the authorizer.

New in version 0.17.2.

set_timeout(timeout)¶

Parameters:: timeout (int) – the timeout, or 0

Sets the GData.OAuth2Authorizer :timeout property; the network timeout, in seconds.

If timeout is 0, network operations will never time out.

New in version 0.17.0.

Property Details¶

GData.OAuth2Authorizer.props.client_id¶

Name:: client-id
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

A client ID for your application (see the

reference documentation). It is recommended that the ID is of the form company name- application name- version ID.

New in version 0.17.0.

GData.OAuth2Authorizer.props.client_secret¶

Name:: client-secret
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

Client secret provided by Google. This is unique for each application and is accessible from Google’s Developer Console when registering an application. It must be paired with the GData.OAuth2Authorizer :client-id.

See the

reference documentation for details.

New in version 0.17.0.

GData.OAuth2Authorizer.props.locale¶

Name:: locale
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE

The locale to use for network requests, in UNIX locale format. (e.g. “en_GB”, “cs”, “de_DE”.) Use None for the default “C” locale (typically “en_US”).

This locale will be used by the server-side software to localise the authentication and authorization pages at the URI returned by GData.OAuth2Authorizer.build_authentication_uri().

The server-side behaviour is undefined if it doesn’t support a given locale.

New in version 0.17.0.

GData.OAuth2Authorizer.props.proxy_resolver¶

Name:: proxy-resolver
Type:: Gio.ProxyResolver
Default Value:: None
Flags:: READABLE, WRITABLE

The Gio.ProxyResolver used to determine a proxy URI.

New in version 0.17.0.

GData.OAuth2Authorizer.props.redirect_uri¶

Name:: redirect-uri
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

Redirect URI to send the response from the authorisation request to. This must either be GData.OAUTH2_REDIRECT_URI_OOB, GData.OAUTH2_REDIRECT_URI_OOB_AUTO, or a

http://localhost URI with any port number (optionally) specified.

This URI is where the authorisation server will redirect the user after they have completed interacting with the authentication page (GData.OAuth2Authorizer.build_authentication_uri()). If it is GData.OAUTH2_REDIRECT_URI_OOB, a page will be returned in the user’s browser with the authorisation code in its title and also embedded in the page for the user to copy if it is not possible to automatically extract the code from the page title. If it is GData.OAUTH2_REDIRECT_URI_OOB_AUTO, a similar page will be returned with the authorisation code in its title, but without displaying the code to the user — the user will simply be asked to close the page. If it is a localhost URI, the authentication page will redirect to that URI with the authorisation code appended as a code query parameter. If the user denies the authentication request, the authentication page will redirect to that URI with

error=access_denied appended as a query parameter. Note that the redirect URI used must match that registered in Google’s Developer Console for your application.

See the reference documentation for details about choosing a redirect URI.

New in version 0.17.0.

GData.OAuth2Authorizer.props.refresh_token¶

Name:: refresh-token
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE

The server provided refresh token, which can be stored and passed in to new GData.OAuth2Authorizer instances before calling GData.Authorizer.refresh_authorization_async() to create a new short-lived access token.

The refresh token is opaque data and must not be parsed.

New in version 0.17.2.

GData.OAuth2Authorizer.props.timeout¶

Name:: timeout
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE

A timeout, in seconds, for network operations. If the timeout is exceeded, the operation will be cancelled and GData.ServiceError.NETWORK_ERROR will be returned.

If the timeout is 0, operations will never time out.

New in version 0.17.0.