User Bank

A Pythonic wrapper for Google Sheets based user management using the official Google API client.

Features

• Secure Authentication: Check credentials (username/email and password) without listing or exposing other user records.
• Least Privilege Access: Operates entirely over read-only Google Sheets scopes (spreadsheets.readonly), guaranteeing that the client cannot write to, modify, or corrupt the user spreadsheet.
• Zero OAuth Popups: Uses a Google Service Account — fully automated, ideal for headless/CI/CD usage.
• CLI Setup Wizard: One command (userbank) to configure credentials and connect.
• Environment-First Auth: Pulls credentials from GOOGLE_APPLICATION_CREDENTIALS or USER_BANK_CREDENTIALS_JSON environment variables (or .env file).

Quick Start

pip install .

# Run the setup wizard
userbank

The wizard will:

1. Ask for your Google Service Account JSON key (path or paste)
2. Ask for your Google Sheet URL (it saves it to config.yml)
3. Write GOOGLE_APPLICATION_CREDENTIALS=keys.json to .env
4. Test the connection

Then use it:

from userbank import UserBank

bank = UserBank.from_config()
is_authenticated = bank.authenticate("jdoe", "securepass123", "MyApp")

Manual Setup

1. Google Service Account

1. Go to Google Cloud Console.
2. Create a project (or select an existing one).
3. Create a Service Account → Keys → Add Key → Create New Key (JSON).
4. Save the downloaded file as keys.json in your project root.

2. Enable Google Sheets API

Visit the URL below and click Enable:

https://console.cloud.google.com/apis/api/sheets.googleapis.com/

(The API must be enabled for the project your service account belongs to.)

3. Spreadsheet

1. Create a new Google Sheet.
2. Share it with the service account email (found in keys.json).
3. Copy the sheet URL into config.yml:

   USER_BANK_URL: https://docs.google.com/spreadsheets/d/YOUR_ID/edit
   

3. Authentication

Credentials are resolved in this order:

The simplest approach: put GOOGLE_APPLICATION_CREDENTIALS=keys.json in your .env and it just works. With the configured environment/config file, the class can be instantiated with no arguments:

from userbank import UserBank

bank = UserBank()  # Implicitly resolves spreadsheet ID and credentials

Usage

from userbank import UserBank

bank = UserBank()

# Authenticate a user by username or email
is_authenticated = bank.authenticate(
    username_or_email="jdoe", # or "john.doe@example.com"
    password="securepassword123",
    application="MyApp"
)

if is_authenticated:
    print("User authenticated successfully!")
else:
    print("Invalid credentials or inactive user.")

Spreadsheet Fields

The first row of the Google Sheet must contain these headers:

CLI Reference

Run userbank with no arguments for the interactive setup wizard.

Installation

pip install .

Publishing

make publish

or

$ python -m build
$ python -m twine upload --repository pypi dist/*