Installation

Requirements

SheetAlchemy requires:

  • Python 3.8 or higher

  • gspread >= 6.2.0

  • Google Sheets API access

Installing SheetAlchemy

From PyPI

The recommended way to install SheetAlchemy is via pip:

pip install sheetalchemy

From GitHub

To install the latest development version:

pip install git+https://github.com/0xdps/sheet-alchemy.git

For Development

If you want to contribute to SheetAlchemy, clone the repository and install in development mode:

git clone https://github.com/0xdps/sheet-alchemy.git
cd sheet-alchemy
pip install -e ".[dev]"

This will install SheetAlchemy along with all development dependencies including:

  • pytest (testing)

  • black (code formatting)

  • isort (import sorting)

  • flake8 (linting)

  • mypy (type checking)

Installing Dependencies

Core Dependencies

SheetAlchemy has minimal core dependencies:

pip install gspread>=6.2.0

Optional Dependencies

For development and testing:

pip install sheetalchemy[dev]

Verifying Installation

To verify that SheetAlchemy is installed correctly:

import sheetalchemy
print(sheetalchemy.__version__)

You should see the version number printed (e.g., 2.0).

Google Sheets API Setup

Before using SheetAlchemy, you need to set up Google Sheets API access:

  1. Create a Google Cloud Project

  2. Enable Google Sheets API

    • In your project, go to “APIs & Services” > “Library”

    • Search for “Google Sheets API”

    • Click “Enable”

  3. Create Service Account

    • Go to “APIs & Services” > “Credentials”

    • Click “Create Credentials” > “Service Account”

    • Fill in the service account details

    • Click “Create and Continue”

  4. Generate Key

    • Click on the created service account

    • Go to the “Keys” tab

    • Click “Add Key” > “Create new key”

    • Choose JSON format

    • Save the downloaded key file securely

  5. Share Your Google Sheet

    • Open your Google Sheet

    • Click “Share”

    • Add the service account email (found in the JSON key file)

    • Give it “Editor” access

Next Steps

Once installed, proceed to the Quick Start Guide guide to learn how to use SheetAlchemy.

Troubleshooting

Common Issues

ModuleNotFoundError: No module named ‘gspread’

Make sure gspread is installed:

pip install gspread>=6.2.0

Authentication Errors

Ensure your service account has access to the Google Sheet and the API is enabled in your Google Cloud Project.

Version Conflicts

If you encounter dependency conflicts, try creating a fresh virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install sheetalchemy