Authentication

def authorize(client_secret='client_secret.json',
              service_account_file=None,
              service_account_env_var=None,
              service_account_json=None,
              credentials_directory='',
              scopes=_SCOPES,
              custom_credentials=None,
              local=False,
              **kwargs) -> Client:
    """
    Authenticate this application with a google account.
    
    Parameters:
    - client_secret (str): Location of the oauth2 credentials file
    - service_account_file (str): Location of a service account file
    - service_account_env_var (str): Environment variable containing service account credentials
    - service_account_json (str): Service account JSON string directly
    - credentials_directory (str): Location for token file storage. Use 'global' for OS-dependent global location
    - scopes (list): List of scopes for authentication. Defaults to Sheets and Drive API scopes
    - custom_credentials: Pre-configured credentials object
    - local (bool): Use local server for OAuth2 flow instead of console-based flow
    
    Returns:
    Client: Authenticated client instance for spreadsheet operations
    
    Raises:
    AuthenticationError: If authentication process fails
    """

import pygsheets

# Using service account file
gc = pygsheets.authorize(service_account_file='path/to/service-account.json')

# Using environment variable
import os
os.environ['GOOGLE_APPLICATION_CREDENTIALS'] = 'path/to/service-account.json'
gc = pygsheets.authorize(service_account_env_var='GOOGLE_APPLICATION_CREDENTIALS')

# Using JSON string directly
service_account_json = '{"type": "service_account", ...}'
gc = pygsheets.authorize(service_account_json=service_account_json)

import pygsheets

# Standard OAuth2 flow (console-based)
gc = pygsheets.authorize(client_secret='client_secret.json')

# Local server OAuth2 flow
gc = pygsheets.authorize(client_secret='client_secret.json', local=True)

# Custom credentials directory
gc = pygsheets.authorize(
    client_secret='client_secret.json',
    credentials_directory='/path/to/credentials'
)

# Global credentials directory
gc = pygsheets.authorize(
    client_secret='client_secret.json',
    credentials_directory='global'
)

import pygsheets

# Custom scopes for read-only access
readonly_scopes = [
    'https://www.googleapis.com/auth/spreadsheets.readonly',
    'https://www.googleapis.com/auth/drive.readonly'
]

gc = pygsheets.authorize(
    client_secret='client_secret.json',
    scopes=readonly_scopes
)

# Full access scopes (default)
full_scopes = [
    'https://www.googleapis.com/auth/spreadsheets',
    'https://www.googleapis.com/auth/drive'
]

gc = pygsheets.authorize(
    client_secret='client_secret.json',
    scopes=full_scopes
)

class Client:
    """
    Main interface for Google Sheets operations.
    
    Attributes:
    - credentials: Google API credentials object
    - service: Google Sheets API service instance
    - drive: Google Drive API service instance
    """
    
    def __init__(self, credentials, retries=3, seconds_per_quota=100):
        """
        Initialize client with credentials.
        
        Parameters:
        - credentials: Google API credentials
        - retries (int): Number of retry attempts for failed requests
        - seconds_per_quota (int): Seconds to wait between quota-limited requests
        """

class AuthenticationError(PyGsheetsException):
    """Raised when authentication process fails."""
    pass