Installation Guide

This guide will help you install the Upstox TOTP Python SDK in your environment.

Requirements

Before installing, ensure you have:

  • Python 3.12 or higher

  • Active Upstox trading account

  • Upstox Developer App (for client credentials)

  • TOTP app setup (Google Authenticator, Authy, etc.)

Installation Methods

Using pip

# Install from PyPI
pip install upstox-totp

# Install specific version
pip install upstox-totp==1.0.3

# Install with extra dependencies (if available)
pip install upstox-totp[dev]

Using pipx (For CLI usage)

If you only want to use the CLI tool:

# Install CLI tool globally
pipx install upstox-totp

# Use the CLI
upstox_cli --help

Development Installation

If you want to contribute or run the latest development version:

# Clone the repository
git clone https://github.com/batpool/upstox-totp.git
cd upstox-totp

# Install dependencies with uv
uv sync

# Install development dependencies
uv sync --group dev

# Install in editable mode
uv pip install -e .

Virtual Environment Setup

It’s recommended to use a virtual environment:

Using venv

# Create virtual environment
python -m venv upstox-env

# Activate (Linux/macOS)
source upstox-env/bin/activate

# Activate (Windows)
upstox-env\Scripts\activate

# Install package
pip install upstox-totp

Using conda

# Create conda environment
conda create -n upstox-env python=3.12

# Activate environment
conda activate upstox-env

# Install package
pip install upstox-totp

Using Poetry

# Initialize project (if new)
poetry init

# Add dependency
poetry add upstox-totp

# Install dependencies
poetry install

# Run in poetry environment
poetry run upstox_cli --help

Verification

After installation, verify that everything is working:

# Check CLI is available
upstox_cli --help

# Check Python package
python -c "import upstox_totp; print(upstox_totp.__version__)"

Expected output:

Usage: upstox_cli [OPTIONS] COMMAND [ARGS]...

  Upstox TOTP CLI - Generate access tokens for Upstox API authentication.

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  check-env        Check if environment variables are properly configured.
  generate-token   Generate Upstox access token using TOTP authentication.

Docker Installation

If you prefer using Docker:

FROM python:3.12-slim

# Install upstox-totp
RUN pip install upstox-totp

# Set working directory
WORKDIR /app

# Copy your application
COPY . .

# Set environment variables
ENV UPSTOX_USERNAME=your-username
ENV UPSTOX_PASSWORD=your-password
# ... other environment variables

# Run your application
CMD ["python", "your_app.py"]

Build and run:

# Build image
docker build -t my-upstox-app .

# Run container
docker run --env-file .env my-upstox-app

Troubleshooting Installation

Common Issues

ImportError: No module named ‘upstox_totp’

# Ensure you're in the correct environment
which python
python -m pip list | grep upstox

# Reinstall if necessary
pip uninstall upstox-totp
pip install upstox-totp

Permission denied errors

# Use --user flag
pip install --user upstox-totp

# Or use virtual environment
python -m venv venv
source venv/bin/activate
pip install upstox-totp

SSL Certificate errors

# Install with trusted hosts
pip install --trusted-host pypi.org --trusted-host pypi.python.org upstox-totp

# Or upgrade certificates
pip install --upgrade certifi

Python version compatibility

# Check Python version
python --version

# Use specific Python version
python3.12 -m pip install upstox-totp

Dependencies

The package automatically installs these dependencies:

Core Dependencies

  • click>=8.3.0 - Command-line interface framework

  • curl-cffi>=0.13.0 - HTTP client with better performance

  • dotenv>=0.9.9 - Environment variable management

  • pydantic>=2.11.9 - Data validation and settings management

  • pyotp>=2.9.0 - TOTP (Time-based One-Time Password) generation

Development Dependencies

  • black>=25.9.0 - Code formatting

  • isort>=6.0.1 - Import sorting

Optional Dependencies

For documentation building:

  • sphinx - Documentation generator

  • sphinx-rtd-theme - Read the Docs theme

  • myst-parser - Markdown parser for Sphinx

Installation Verification Script

Create a simple script to verify installation:

# verify_installation.py

def verify_installation():
    """Verify that upstox-totp is properly installed."""
    try:
        import upstox_totp
        from upstox_totp import UpstoxTOTP

        print(f"✅ upstox-totp version: {upstox_totp.__version__}")
        print("✅ All imports successful")

        # Try to initialize (will fail without env vars, but import should work)
        try:
            upx = UpstoxTOTP()
            print("✅ UpstoxTOTP class can be instantiated")
        except Exception as e:
            print(f"⚠️  UpstoxTOTP instantiation failed (expected without env vars): {e}")

        print("\n🎉 Installation verified successfully!")

    except ImportError as e:
        print(f"❌ Import failed: {e}")
        print("💡 Try reinstalling: pip install upstox-totp")

    except Exception as e:
        print(f"❌ Unexpected error: {e}")

if __name__ == "__main__":
    verify_installation()

Run the verification:

python verify_installation.py

Next Steps

After successful installation:

  1. Set up your credentials - See Configuration Guide

  2. Try the quickstart - See Quick Start Guide

  3. Read the API reference - See Client API Reference

  4. Check out examples - See Basic Usage Examples

Need Help?

If you encounter any installation issues: