blackroad-operating-system/sdk/python/INSTALL.md

BlackRoad Python SDK - Installation Guide

Prerequisites

• Python 3.8 or higher
• pip (Python package installer)
• Virtual environment (recommended)

Installation Methods

Method 1: Install from Source (Development)

This is recommended for development or if you want to contribute to the SDK.

# Clone the repository
git clone https://github.com/blackboxprogramming/BlackRoad-Operating-System.git
cd BlackRoad-Operating-System/sdk/python

# Create a virtual environment (recommended)
python -m venv venv

# Activate virtual environment
# On Linux/Mac:
source venv/bin/activate
# On Windows:
venv\Scripts\activate

# Install the SDK in development mode
pip install -e .

# Or install with development dependencies
pip install -e ".[dev]"

Method 2: Install from PyPI (When Published)

Once the package is published to PyPI, you can install it directly:

pip install blackroad

Method 3: Install from requirements.txt

pip install -r requirements.txt
python setup.py install

Verify Installation

After installation, verify that the SDK is installed correctly:

python -c "import blackroad; print(blackroad.__version__)"

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

Quick Start

1. Set up environment variables (optional):

export BLACKROAD_BASE_URL="http://localhost:8000"
export BLACKROAD_API_KEY="your-api-key"  # Optional

2. Test the installation:

from blackroad import BlackRoadClient

# Initialize client
client = BlackRoadClient(base_url="http://localhost:8000")

# Test connection (will fail if server is not running)
try:
    stats = client.blockchain.get_stats()
    print(f"Connected! Total blocks: {stats.total_blocks}")
except Exception as e:
    print(f"Connection failed: {e}")
finally:
    client.close()

3. Run example scripts:

# Make sure the BlackRoad backend is running first
cd examples
python quickstart.py

Running Tests

# Install test dependencies
pip install -e ".[test]"

# Run all tests
pytest

# Run with coverage
pytest --cov=blackroad --cov-report=html

# Run specific test file
pytest tests/test_client.py -v

# Run specific test
pytest tests/test_client.py::TestBlackRoadClient::test_client_initialization -v

Development Setup

For development, install with all development dependencies:

# Install with dev dependencies
pip install -e ".[dev]"

# Install pre-commit hooks (if using)
pre-commit install

# Format code
black blackroad/

# Lint code
flake8 blackroad/
pylint blackroad/

# Type checking
mypy blackroad/

# Sort imports
isort blackroad/

Upgrading

From Source

cd BlackRoad-Operating-System/sdk/python
git pull origin main
pip install -e . --upgrade

From PyPI

pip install --upgrade blackroad

Uninstallation

pip uninstall blackroad

Troubleshooting

Import Error

If you get an import error:

ModuleNotFoundError: No module named 'blackroad'

Solution: Make sure you're in the correct virtual environment and the package is installed:

pip list | grep blackroad

Connection Error

If you get connection errors when using the client:

NetworkError: Network error: ...

Solution: Make sure the BlackRoad backend is running:

# Start the backend
cd ../../backend
uvicorn app.main:app --reload

Version Conflicts

If you get dependency version conflicts:

Solution: Create a fresh virtual environment:

deactivate  # If in a virtual environment
rm -rf venv  # Remove old environment
python -m venv venv
source venv/bin/activate
pip install -e .

SSL Certificate Error

If you get SSL certificate errors:

Solution: Either fix your SSL certificates or disable SSL verification (not recommended for production):

import httpx
from blackroad import BlackRoadClient

# Create a custom HTTP client with SSL disabled
client = BlackRoadClient(base_url="http://localhost:8000")
# Note: Use HTTPS in production!

Getting Help

If you encounter any issues:

1. Check the README.md for usage examples
2. Review the CHANGELOG.md for recent changes
3. Look at the examples/ directory for working code
4. Open an issue on GitHub

Next Steps

After installation:

1. Read the README.md for usage examples
2. Try the example scripts in examples/
3. Check out the API documentation
4. Join the BlackRoad community

---

Happy coding with BlackRoad! 🛣️