Development Environment Guide¶

Overview¶

This guide provides detailed instructions for setting up and configuring a development environment for the DSTA (Dr. Strange Trading Analysis) project. Follow these steps to get your local development environment up and running.

Table of Contents¶

Prerequisites
Initial Setup
Development Tools
IDE Configuration
Running Services
Database Setup
Testing
Code Quality
Debugging
Common Workflows
Troubleshooting
Best Practices

Prerequisites¶

Required Software¶

Python 3.12+: The project requires Python 3.12 or higher
Docker & Docker Compose: For running services (PostgreSQL, Redis)
Git: For version control
uv (recommended) or pip: For package management

System Requirements¶

OS: Linux (Ubuntu 22.04+), macOS (13+), or Windows 10/11 with WSL2
RAM: Minimum 8GB (16GB recommended)
Disk: 10GB free space
CPU: 2+ cores

Optional but Recommended¶

make: For using Makefile commands
curl: For API testing
jq: For JSON processing
httpie: Better alternative to curl for API testing

Initial Setup¶

1. Clone the Repository¶

# Clone the repository
git clone https://github.com/minhdqdev/dsta.git
cd dsta

# Initialize and update submodules
git submodule update --init --recursive

2. Install uv (Recommended Package Manager)¶

# Install uv (faster than pip)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Verify installation
uv --version

3. Create Virtual Environment¶

Using uv (recommended):

# Create virtual environment
uv venv

# Activate virtual environment
source .venv/bin/activate  # Linux/macOS
# or
.venv\Scripts\activate     # Windows

Using venv:

python3.12 -m venv .venv
source .venv/bin/activate

4. Install Dependencies¶

# Install project dependencies with uv
uv pip install -e .

# Or install from requirements.txt
pip install -r src/requirements.txt

# Install development dependencies
pip install pytest pytest-django black isort flake8 mypy

5. Install TA-Lib (Optional but Recommended)¶

Ubuntu/Debian:

# Install TA-Lib C library
sudo apt-get update
sudo apt-get install build-essential wget
wget http://prdownloads.sourceforge.net/ta-lib/ta-lib-0.4.0-src.tar.gz
tar -xzf ta-lib-0.4.0-src.tar.gz
cd ta-lib/
./configure --prefix=/usr
make
sudo make install
sudo ldconfig

# Install Python wrapper
pip install TA-Lib

macOS:

brew install ta-lib
pip install TA-Lib

Windows or if compilation fails: The project includes fallback implementations, so TA-Lib is optional.

6. Configure Environment Variables¶

# Copy example environment file
cp .env_files/dev.env.example .env_files/dev.env

# Edit configuration
nano .env_files/dev.env

Required environment variables:

# Django
SECRET_KEY=your-secret-key-here
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1

# Database
DATABASE_URL=postgresql://dsta:dsta@localhost:5432/dsta_dev

# Redis
REDIS_URL=redis://localhost:6379/0

# Exchange API (for development/testing)
BINANCE_API_KEY=your-api-key
BINANCE_API_SECRET=your-api-secret

Development Tools¶

Essential Tools¶

uv: Fast Python package installer

uv pip install <package>
uv run python script.py

Docker & Docker Compose: Service orchestration

docker-compose up -d
docker-compose ps
docker-compose logs -f

pytest: Testing framework

pytest tests/
pytest tests/backtesting/ -v
pytest -k "test_indicators"

Black: Code formatter
```
black src/ tests/
black --check src/
```

isort: Import organizer

isort src/ tests/
isort --check-only src/

flake8: Linter
```
flake8 src/ tests/
```
mypy: Type checker
```
mypy src/
```

Recommended Tools¶

httpie: Better HTTP client

pip install httpie
http GET localhost:8000/api/health/

ipython: Enhanced Python REPL
```
pip install ipython
ipython
```

Django Debug Toolbar: Web debugging

pip install django-debug-toolbar
# Enable in settings.py for development

IDE Configuration¶

VS Code (Recommended)¶

Extensions¶

Install these essential extensions: - Python (ms-python.python) - Pylance (ms-python.vscode-pylance) - Django (batisteo.vscode-django) - Docker (ms-azuretools.vscode-docker) - GitLens (eamodio.gitlens) - YAML (redhat.vscode-yaml)

Settings (.vscode/settings.json)¶

{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
  "python.linting.enabled": true,
  "python.linting.flake8Enabled": true,
  "python.linting.pylintEnabled": false,
  "python.formatting.provider": "black",
  "python.formatting.blackArgs": ["--line-length", "120"],
  "python.sortImports.args": ["--profile", "black"],
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.organizeImports": true
  },
  "python.testing.pytestEnabled": true,
  "python.testing.pytestArgs": [
    "tests",
    "-v"
  ],
  "files.exclude": {
    "**/__pycache__": true,
    "**/*.pyc": true,
    ".pytest_cache": true
  }
}

Launch Configuration (.vscode/launch.json)¶

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Django Server",
      "type": "python",
      "request": "launch",
      "program": "${workspaceFolder}/src/manage.py",
      "args": ["runserver", "0.0.0.0:8000"],
      "django": true,
      "justMyCode": true
    },
    {
      "name": "Python: Current File",
      "type": "python",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal"
    },
    {
      "name": "Pytest: Current File",
      "type": "python",
      "request": "launch",
      "module": "pytest",
      "args": ["${file}", "-v"],
      "console": "integratedTerminal"
    }
  ]
}

PyCharm¶

Set Python Interpreter:
File → Settings → Project → Python Interpreter
Add Interpreter → Existing Environment
Select .venv/bin/python
Configure Django Support:
File → Settings → Languages & Frameworks → Django
Enable Django support
Django project root: src/
Settings: dsta/settings.py
Manage script: manage.py
Code Style:
File → Settings → Tools → Black
Enable "On save"
Line length: 120
Run Configurations:
Add Django Server configuration
Add pytest configuration

Vim/Neovim¶

Use ALE or coc.nvim for linting and completion:

" .vimrc or init.vim
let g:ale_linters = {
\   'python': ['flake8', 'mypy'],
\}
let g:ale_fixers = {
\   'python': ['black', 'isort'],
\}
let g:ale_fix_on_save = 1

Running Services¶

Start All Services¶

cd deploy
docker-compose up -d

Start Specific Profile¶

# Minimal (just database and API)
docker-compose --profile minimal up -d

# Development (with debugging tools)
docker-compose --profile dev up -d

# Full (all services)
docker-compose --profile full up -d

Check Service Status¶

docker-compose ps
docker-compose logs -f api-server
docker-compose logs -f postgres

Stop Services¶

docker-compose down
# or to remove volumes
docker-compose down -v

Database Setup¶

Initialize Database¶

cd src

# Run migrations
python manage.py migrate

# Create superuser
python manage.py createsuperuser

# Load sample data (optional)
python manage.py loaddata fixtures/sample_data.json

Access Database¶

# Using psql
docker-compose exec postgres psql -U dsta -d dsta_dev

# Using Django shell
python manage.py dbshell

# Using Django ORM shell
python manage.py shell

Database Migrations¶

# Create new migration
python manage.py makemigrations

# Apply migrations
python manage.py migrate

# Show migration status
python manage.py showmigrations

# Rollback migration
python manage.py migrate api 0001_initial

Testing¶

Run All Tests¶

# Using pytest
pytest

# With coverage
pytest --cov=src --cov-report=html

# Verbose output
pytest -v

# Run specific test file
pytest tests/backtesting/test_indicators.py

# Run specific test
pytest tests/backtesting/test_indicators.py::TestSMA::test_basic_calculation

Run Tests by Marker¶

# Unit tests only
pytest -m unit

# Integration tests
pytest -m integration

# Skip slow tests
pytest -m "not slow"

Test with Different Settings¶

# Without Django integration
pytest -p no:django

# With specific settings
DJANGO_SETTINGS_MODULE=dsta.settings.test pytest

Generate Coverage Report¶

pytest --cov=src --cov-report=html
# Open htmlcov/index.html in browser

Code Quality¶

Format Code¶

# Format with black
black src/ tests/

# Check without modifying
black --check src/

# Sort imports
isort src/ tests/

Lint Code¶

# Run flake8
flake8 src/ tests/

# Run mypy
mypy src/

Run All Quality Checks¶

Create a script scripts/quality.sh:

#!/bin/bash
set -e

echo "Running Black..."
black --check src/ tests/

echo "Running isort..."
isort --check-only src/ tests/

echo "Running flake8..."
flake8 src/ tests/

echo "Running mypy..."
mypy src/

echo "All quality checks passed!"

chmod +x scripts/quality.sh
./scripts/quality.sh

Debugging¶

Install:
```
pip install django-debug-toolbar
```

Add to settings.py:

INSTALLED_APPS = [
    # ...
    'debug_toolbar',
]

MIDDLEWARE = [
    'debug_toolbar.middleware.DebugToolbarMiddleware',
    # ...
]

INTERNAL_IPS = ['127.0.0.1']

Add to urls.py:

if settings.DEBUG:
    import debug_toolbar
    urlpatterns = [
        path('__debug__/', include(debug_toolbar.urls)),
    ] + urlpatterns

Python Debugger (pdb)¶

# Add breakpoint in code
import pdb; pdb.set_trace()

# Or use Python 3.7+ breakpoint()
breakpoint()

Django Shell¶

# Interactive Python shell with Django context
python manage.py shell

# Use IPython if installed
python manage.py shell -i ipython

# Run Python script with Django
python manage.py shell < script.py

Logging¶

# In your code
import logging

logger = logging.getLogger(__name__)

logger.debug("Debug message")
logger.info("Info message")
logger.warning("Warning message")
logger.error("Error message")

View logs:

# Application logs
tail -f logs/app.log

# Django logs
docker-compose logs -f api-server

# All logs
docker-compose logs -f

Common Workflows¶

Create a New Feature¶

# 1. Create feature branch
git checkout -b feature/my-feature

# 2. Make changes
# ... edit files ...

# 3. Format and lint
black src/ tests/
isort src/ tests/
flake8 src/ tests/

# 4. Run tests
pytest

# 5. Commit changes
git add .
git commit -m "Add my feature"

# 6. Push to remote
git push origin feature/my-feature

# 7. Create pull request on GitHub

Add New Dependency¶

# 1. Install package
uv pip install package-name

# 2. Update pyproject.toml
# Add to dependencies section

# 3. Generate requirements.txt (if needed)
uv pip compile pyproject.toml -o requirements.txt

# 4. Commit changes
git add pyproject.toml requirements.txt
git commit -m "Add package-name dependency"

Run a Backtest¶

cd src

# Using example strategy
python -m backtesting.example

# Or in Python
python
>>> from backtesting import Backtest
>>> from backtesting.strategies import SMACrossover
>>> # ... run backtest

Access Django Admin¶

# 1. Create superuser if not done
python manage.py createsuperuser

# 2. Start server
python manage.py runserver

# 3. Open browser
# http://localhost:8000/admin/

Troubleshooting¶

Common Issues¶

Issue: "No module named 'X'"¶

Solution:

# Ensure virtual environment is activated
source .venv/bin/activate

# Install dependencies
uv pip install -e .

Issue: "Database connection failed"¶

Solution:

# Check if PostgreSQL is running
docker-compose ps

# Start PostgreSQL if not running
docker-compose up -d postgres

# Check connection
psql -h localhost -U dsta -d dsta_dev

Issue: "Port already in use"¶

Solution:

# Find process using port
lsof -i :8000

# Kill process
kill -9 <PID>

# Or use different port
python manage.py runserver 8001

Issue: "Migration conflicts"¶

Solution:

# Show migration status
python manage.py showmigrations

# Merge migrations
python manage.py makemigrations --merge

# Or reset migrations (development only!)
python manage.py migrate api zero
python manage.py migrate

Issue: "TA-Lib installation fails"¶

Solution: The project includes fallback implementations. TA-Lib is optional.

# Skip TA-Lib installation
pip install --no-binary TA-Lib .

# The wrapper will automatically use fallback

Performance Issues¶

Slow Tests¶

# Run tests in parallel
pytest -n auto

# Skip slow tests
pytest -m "not slow"

Slow Database Queries¶

# Enable query logging in settings.py
LOGGING = {
    'loggers': {
        'django.db.backends': {
            'level': 'DEBUG',
        },
    },
}

# Use Django Debug Toolbar to analyze queries

Getting Help¶

Check documentation: docs/ directory
Search issues: GitHub Issues
Ask in discussions: GitHub Discussions
Contact maintainers: See CONTRIBUTING.md

Best Practices¶

Code Organization¶

Keep functions small and focused
Use type hints consistently
Write docstrings for all public functions
Follow DRY (Don't Repeat Yourself) principle

Git Workflow¶

Commit often with meaningful messages
Use feature branches
Keep commits atomic
Write descriptive commit messages

Testing¶

Write tests before fixing bugs
Aim for 80%+ code coverage
Test edge cases
Use fixtures for test data

Performance¶

Profile before optimizing
Use database indexes appropriately
Cache expensive computations
Avoid N+1 queries

Security¶

Never commit secrets
Use environment variables
Keep dependencies updated
Validate user input

Documentation¶

Document public APIs
Update docs with code changes
Include examples
Keep README current

Additional Resources¶

Documentation¶

Project Documentation¶

README.md: Project overview
CONTRIBUTING.md: Contribution guide
TASKS.md: Task list
docs/: Additional documentation

Useful Commands¶

# Quick reference
make help               # Show available make targets
docker-compose ps       # List running services
pytest --markers        # List available test markers
python manage.py help   # Django management commands

Next Steps¶

After setting up your development environment:

Read CONTRIBUTING.md
Browse TASKS.md for available tasks
Run the test suite to ensure everything works
Try running a simple backtest
Explore the codebase

Happy coding! 🚀

Development Environment Guide¶

Overview¶

Table of Contents¶

Prerequisites¶

Required Software¶

System Requirements¶

Optional but Recommended¶

Initial Setup¶

1. Clone the Repository¶

2. Install uv (Recommended Package Manager)¶

3. Create Virtual Environment¶

4. Install Dependencies¶

5. Install TA-Lib (Optional but Recommended)¶

6. Configure Environment Variables¶

Development Tools¶

Essential Tools¶

Recommended Tools¶

IDE Configuration¶

VS Code (Recommended)¶

Extensions¶

Settings (.vscode/settings.json)¶

Launch Configuration (.vscode/launch.json)¶

PyCharm¶

Vim/Neovim¶

Running Services¶

Start All Services¶

Start Specific Profile¶

Check Service Status¶

Stop Services¶

Database Setup¶

Initialize Database¶

Access Database¶

Database Migrations¶

Testing¶

Run All Tests¶

Run Tests by Marker¶

Test with Different Settings¶

Generate Coverage Report¶

Code Quality¶

Format Code¶

Lint Code¶

Run All Quality Checks¶

Debugging¶

Django Debug Toolbar¶

Python Debugger (pdb)¶

Django Shell¶

Logging¶

Common Workflows¶

Create a New Feature¶

Add New Dependency¶

Run a Backtest¶

Access Django Admin¶

Troubleshooting¶

Common Issues¶

Issue: "No module named 'X'"¶

Issue: "Database connection failed"¶

Issue: "Port already in use"¶

Issue: "Migration conflicts"¶

Issue: "TA-Lib installation fails"¶

Performance Issues¶

Slow Tests¶

Slow Database Queries¶

Getting Help¶

Best Practices¶

Code Organization¶

Git Workflow¶

Testing¶

Performance¶

Security¶

Documentation¶

Additional Resources¶

Documentation¶

Project Documentation¶

Useful Commands¶

Next Steps¶