userbank 1.0.0

A Pythonic wrapper for Google Sheets based user management.

User Bank

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

Features

• Programmatic User Addition: Add users with automatic timestamping.
• Flexible Search: Search by exact match or regex across any field.
• 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()
bank.initialize_sheet()
bank.add_user("MyApp", "[e-mail]", "jdoe", "securepass123")

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:

#	Source	Example
1	credentials_path argument	UserBank(..., credentials_path="keys.json")
2	credentials_info argument	UserBank(..., credentials_info={...})
3	GOOGLE_APPLICATION_CREDENTIALS env var	path to JSON key file
4	USER_BANK_CREDENTIALS_JSON env var	inline JSON string
5	.env file	loaded automatically, then checks #3–#4

The simplest approach: put GOOGLE_APPLICATION_CREDENTIALS=keys.json in your .env and it just works:

from userbank import UserBank

bank = UserBank(spreadsheet_id="YOUR_ID")  # credentials from .env

Usage

from userbank import UserBank

bank = UserBank.from_config()

# Initialize sheet headers (run once)
bank.initialize_sheet()

# Add a user
bank.add_user(
    application="MyApp",
    email="[e-mail]",
    username="jdoe",
    password="securepassword123"
)

# Search users
users = bank.search(application="MyApp", is_active=True)

# Search with regex
johns = bank.search(email_re="john.*")

# Search and iterate
for u in bank.search(is_active=True):
    print(f"{u['UserName']} ({u['Email']})")

Spreadsheet Fields

The first row must contain these headers (call bank.initialize_sheet() to create them automatically):

Field	Description
Application	App name
Email	User's email
UserName	Login name
UserPassword	Password
DateCreated	Auto-filled on add
DateLastAccess	Auto-filled on add
DateDeleted	Soft-delete timestamp
IsActive	TRUE or FALSE

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/*