Skip to content

Authorization

_Clients

Bases: object

Base client object for authorization to all Google APIs. This object contains methods to authorize local files, Credentials objects, and more.

Source code in pygsuite/auth/authorization.py 
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
class _Clients(object):
    """Base client object for authorization to all Google APIs.
    This object contains methods to authorize local files, `Credentials` objects, and more.
    """

    def __init__(self):
        """Class constructor"""
        self.cred_path = None
        self.cred_text = None
        self.auth = None

    def validate(self):
        """Method to verify authorization has been obtained.
        Raises a `ValueError` if no `Credentials` object exists in `self.auth`.
        """
        if not self.auth:
            raise ValueError("Need to provide credential path or credential text or auth object.")

    def auth_default(self, project: Optional[str] = None):
        """Gets the default credentials for the current environment.
        More information in [Google's default auth documentation](
            https://google-auth.readthedocs.io/en/master/reference/google.auth.html#google.auth.default
        )

        Args:
            project (Optional[str]): The project ID.

        Sets the client auth to the default credentials fetched from Google.
        """
        import google.auth

        self.auth, project_id = google.auth.default(quota_project_id=project)

    def create_client_file_from_string(self) -> Flow:
        """Creates a OAuth 2.0 Authorization Flow object from a credential string if provided.

        Returns a constructed `Flow` object with credential information from credential string.
        """
        from tempfile import TemporaryDirectory
        import os

        with TemporaryDirectory() as temppath:
            with open(os.path.join(temppath, "writer-key.json"), "w") as keyfile:
                keyfile.write(self.cred_text)
            flow = InstalledAppFlow.from_client_secrets_file(keyfile.name, SCOPES)
        return flow

    def authorize(self, auth: Credentials, project: Optional[str] = None):
        """Sets the credentials for the current environment to a given `Credentials` object.

        Args:
            auth (Credentials): A valid `google.oauth2.credentials.Credentials` object.
            project (Optional[str]): The project ID, not currently used.
        """
        self.auth = auth

    def authorize_string(self, auth_string: str):
        """Sets the credentials for the current environment based on a JSON-like credentials string.

        Args:
            auth_string (str): A JSON-like string containing credentials information to be authenticated.
        """
        self.auth = get_oauth_credential(auth_string)

    def local_file_auth(self, filepath: Optional[str] = None):
        """Sets the credentials for the current environment based on a local file with credentials.

        Args:
            filepath (Optional[str]): Filepath to the credentials file, will default to token.json in working directory.
        """
        filepath = filepath or join(os.getcwd(), "token.json")
        directory = dirname(filepath)
        pickle_path = join(directory, "cache.pickle")
        creds = None
        if os.path.exists(pickle_path):
            with open(pickle_path, "rb") as token:
                creds = pickle.load(token)
        if not creds or not creds.valid:
            if creds and creds.expired and creds.refresh_token:
                creds.refresh(Request())
            else:
                flow = InstalledAppFlow.from_client_secrets_file(filepath, SCOPES)
                creds = flow.run_local_server(port=0)
            with open(pickle_path, "wb") as token:
                pickle.dump(creds, token)
        self.auth = creds

    @lazy_property
    def docs_client(self):
        """Google Docs client"""
        self.validate()
        return build("docs", DOCS_VERSION, credentials=self.auth)

    @lazy_property
    def sheets_client(self):
        """Google Sheets client"""
        self.validate()
        return build("sheets", SHEETS_VERSION, credentials=self.auth)

    @lazy_property
    def slides_client(self):
        """Google Slides client"""
        self.validate()
        return build("slides", SLIDES_VERSION, credentials=self.auth)

    @lazy_property
    def _local_sheets_client(self):
        return build("sheets", SHEETS_VERSION, credentials=self.auth)

    @lazy_property
    def local_docs_client(self):
        return build("docs", DOCS_VERSION, credentials=self.auth)

    @lazy_property
    def _local_slides_client(self):
        return build("slides", SLIDES_VERSION, credentials=self.auth)

    @lazy_property
    def drive_client(self):
        """Google Drive client (API v3)"""
        return self.drive_client_v3

    @lazy_property
    def drive_client_v2(self):
        """Google Drive client (API v2)"""
        self.validate()
        return build("drive", DRIVE_VERSION, credentials=self.auth)

    @lazy_property
    def drive_client_v3(self):
        """Google Drive client (API v3)"""
        self.validate()
        return build("drive", "v3", credentials=self.auth)

    @lazy_property
    def forms_client(self):
        """Form Client"""
        self.validate()
        return build("forms", FORMS_VERSION, credentials=self.auth)

__init__()

Class constructor

Source code in pygsuite/auth/authorization.py 
74
75
76
77
78
def __init__(self):
    """Class constructor"""
    self.cred_path = None
    self.cred_text = None
    self.auth = None

auth_default(project=None)

Gets the default credentials for the current environment. More information in Google's default auth documentation

Parameters:

Name Type Description Default
project Optional[str]

The project ID.

 None

Sets the client auth to the default credentials fetched from Google.

Source code in pygsuite/auth/authorization.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
def auth_default(self, project: Optional[str] = None):
    """Gets the default credentials for the current environment.
    More information in [Google's default auth documentation](
        https://google-auth.readthedocs.io/en/master/reference/google.auth.html#google.auth.default
    )

    Args:
        project (Optional[str]): The project ID.

    Sets the client auth to the default credentials fetched from Google.
    """
    import google.auth

    self.auth, project_id = google.auth.default(quota_project_id=project)

authorize(auth, project=None)

Sets the credentials for the current environment to a given Credentials object.

Parameters:

Name Type Description Default
auth Credentials

A valid google.oauth2.credentials.Credentials object.

 required
project Optional[str]

The project ID, not currently used.

 None
Source code in pygsuite/auth/authorization.py 
116
117
118
119
120
121
122
123
def authorize(self, auth: Credentials, project: Optional[str] = None):
    """Sets the credentials for the current environment to a given `Credentials` object.

    Args:
        auth (Credentials): A valid `google.oauth2.credentials.Credentials` object.
        project (Optional[str]): The project ID, not currently used.
    """
    self.auth = auth

authorize_string(auth_string)

Sets the credentials for the current environment based on a JSON-like credentials string.

Parameters:

Name Type Description Default
auth_string str

A JSON-like string containing credentials information to be authenticated.

 required
Source code in pygsuite/auth/authorization.py 
125
126
127
128
129
130
131
def authorize_string(self, auth_string: str):
    """Sets the credentials for the current environment based on a JSON-like credentials string.

    Args:
        auth_string (str): A JSON-like string containing credentials information to be authenticated.
    """
    self.auth = get_oauth_credential(auth_string)

create_client_file_from_string()

Creates a OAuth 2.0 Authorization Flow object from a credential string if provided.

Returns a constructed Flow object with credential information from credential string.

Source code in pygsuite/auth/authorization.py 
102
103
104
105
106
107
108
109
110
111
112
113
114
def create_client_file_from_string(self) -> Flow:
    """Creates a OAuth 2.0 Authorization Flow object from a credential string if provided.

    Returns a constructed `Flow` object with credential information from credential string.
    """
    from tempfile import TemporaryDirectory
    import os

    with TemporaryDirectory() as temppath:
        with open(os.path.join(temppath, "writer-key.json"), "w") as keyfile:
            keyfile.write(self.cred_text)
        flow = InstalledAppFlow.from_client_secrets_file(keyfile.name, SCOPES)
    return flow

docs_client()

Google Docs client

Source code in pygsuite/auth/authorization.py 
156
157
158
159
160
@lazy_property
def docs_client(self):
    """Google Docs client"""
    self.validate()
    return build("docs", DOCS_VERSION, credentials=self.auth)

drive_client()

Google Drive client (API v3)

Source code in pygsuite/auth/authorization.py 
186
187
188
189
@lazy_property
def drive_client(self):
    """Google Drive client (API v3)"""
    return self.drive_client_v3

drive_client_v2()

Google Drive client (API v2)

Source code in pygsuite/auth/authorization.py 
191
192
193
194
195
@lazy_property
def drive_client_v2(self):
    """Google Drive client (API v2)"""
    self.validate()
    return build("drive", DRIVE_VERSION, credentials=self.auth)

drive_client_v3()

Google Drive client (API v3)

Source code in pygsuite/auth/authorization.py 
197
198
199
200
201
@lazy_property
def drive_client_v3(self):
    """Google Drive client (API v3)"""
    self.validate()
    return build("drive", "v3", credentials=self.auth)

forms_client()

Form Client

Source code in pygsuite/auth/authorization.py 
203
204
205
206
207
@lazy_property
def forms_client(self):
    """Form Client"""
    self.validate()
    return build("forms", FORMS_VERSION, credentials=self.auth)

local_file_auth(filepath=None)

Sets the credentials for the current environment based on a local file with credentials.

Parameters:

Name Type Description Default
filepath Optional[str]

Filepath to the credentials file, will default to token.json in working directory.

 None
Source code in pygsuite/auth/authorization.py 
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
def local_file_auth(self, filepath: Optional[str] = None):
    """Sets the credentials for the current environment based on a local file with credentials.

    Args:
        filepath (Optional[str]): Filepath to the credentials file, will default to token.json in working directory.
    """
    filepath = filepath or join(os.getcwd(), "token.json")
    directory = dirname(filepath)
    pickle_path = join(directory, "cache.pickle")
    creds = None
    if os.path.exists(pickle_path):
        with open(pickle_path, "rb") as token:
            creds = pickle.load(token)
    if not creds or not creds.valid:
        if creds and creds.expired and creds.refresh_token:
            creds.refresh(Request())
        else:
            flow = InstalledAppFlow.from_client_secrets_file(filepath, SCOPES)
            creds = flow.run_local_server(port=0)
        with open(pickle_path, "wb") as token:
            pickle.dump(creds, token)
    self.auth = creds

sheets_client()

Google Sheets client

Source code in pygsuite/auth/authorization.py 
162
163
164
165
166
@lazy_property
def sheets_client(self):
    """Google Sheets client"""
    self.validate()
    return build("sheets", SHEETS_VERSION, credentials=self.auth)

slides_client()

Google Slides client

Source code in pygsuite/auth/authorization.py 
168
169
170
171
172
@lazy_property
def slides_client(self):
    """Google Slides client"""
    self.validate()
    return build("slides", SLIDES_VERSION, credentials=self.auth)

validate()

Method to verify authorization has been obtained. Raises a ValueError if no Credentials object exists in self.auth.

Source code in pygsuite/auth/authorization.py 
80
81
82
83
84
85
def validate(self):
    """Method to verify authorization has been obtained.
    Raises a `ValueError` if no `Credentials` object exists in `self.auth`.
    """
    if not self.auth:
        raise ValueError("Need to provide credential path or credential text or auth object.")

get_oauth_credential(credential_string)

Convert a JSON-like string into a Google OAuth Credentials object, and refresh the credentials if they are expired and contain a refresh token. Raises a ValueError if invalid credentials cannot be refreshed.

Parameters:

Name Type Description Default
credential_string str

A JSON-like string containing Google authentication information.

 required

Returns a valid Credentials object.

Source code in pygsuite/auth/authorization.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
def get_oauth_credential(credential_string: str) -> Union[Credentials, SACredentials]:
    """Convert a JSON-like string into a Google OAuth `Credentials` object,
    and refresh the credentials if they are expired and contain a refresh token.
    Raises a `ValueError` if invalid credentials cannot be refreshed.

    Args:
        credential_string (str): A JSON-like string containing Google authentication information.

    Returns a valid `Credentials` object.
    """
    creds = json_str_to_oauth(credential_string)
    if isinstance(creds, Credentials) and not creds.valid:
        if creds.expired and creds.refresh_token:
            creds.refresh(Request())
            return creds
        raise ValueError(
            "Stored user token is no longer valid and no refresh token! Must be regenerated"
        )
    return creds

json_str_to_oauth(token_str)

Convert a JSON-like string into a Google OAuth Credentials object or a service account object, depending on what was provided.

Parameters:

Name Type Description Default
token_str str

A JSON-like string containing Google authentication information.

 required

Returns a Credentials object.

Source code in pygsuite/auth/authorization.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
def json_str_to_oauth(token_str: str) -> Union[Credentials, SACredentials]:
    """Convert a JSON-like string into a Google OAuth `Credentials` object or a service account object, depending on what was provided.

    Args:
        token_str (str): A JSON-like string containing Google authentication information.

    Returns a `Credentials` object.
    """
    import json

    cred_dict = json.loads(token_str)
    # check for service account credentials
    if cred_dict.get("type", "unknown") == "service_account":
        return SACredentials.from_service_account_info(info=cred_dict)
    return Credentials.from_authorized_user_info(info=cred_dict)