Development Setup¶

This guide will help you set up your development environment for working with TelcoAPI.

Prerequisites¶

Python Environment
Python 3.8 or higher
pip package manager
virtualenv or venv
System Requirements
Git
Docker (optional, for containerized development)
Make (for build scripts)
OpenSSL (for certificate generation)

Installation¶

1. Clone the Repository¶

git clone https://github.com/TelcoAPI/telcoapi.git
cd telcoapi

2. Create Virtual Environment¶

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# On Windows
.venv\Scripts\activate
# On Unix or MacOS
source .venv/bin/activate

3. Install Dependencies¶

# Install development dependencies
pip install -r requirements-dev.txt

# Install pre-commit hooks
pre-commit install

Development Environment¶

1. IDE Configuration¶

VS Code Settings¶

{
    "python.linting.enabled": true,
    "python.linting.pylintEnabled": true,
    "python.formatting.provider": "black",
    "python.testing.pytestEnabled": true,
    "python.testing.unittestEnabled": false,
    "python.testing.nosetestsEnabled": false,
    "python.testing.pytestArgs": [
        "tests"
    ]
}

PyCharm Settings¶

Enable Python Integrated Tools
Set Black as code formatter
Enable Pylint
Configure pytest as test runner

2. Environment Variables¶

Create a .env file:

# Development settings
TELCOAPI_ENV=development
DEBUG=true

# Protocol settings
SS7_POINT_CODE=1-1-1
SS7_SUBSYSTEM=8
DIAMETER_HOST=dev.example.com
DIAMETER_REALM=example.com

# Security settings
TLS_ENABLED=true
CERT_PATH=./certs
KEY_PATH=./certs

# Testing settings
TEST_PEER_HOST=test.example.com
TEST_PEER_PORT=3868

3. Certificate Generation¶

# Generate development certificates
make generate-certs

# Or manually:
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

Project Structure¶

telcoapi/
├── docs/               # Documentation
├── src/               # Source code
│   ├── telcoapi/
│   │   ├── ss7/      # SS7 protocol implementations
│   │   ├── diameter/ # Diameter protocol implementations
│   │   ├── sip/      # SIP protocol implementations
│   │   └── utils/    # Utility functions
├── tests/             # Test files
├── examples/          # Example implementations
├── scripts/           # Development scripts
└── tools/             # Development tools

Development Tools¶

1. Code Quality Tools¶

# Run linting
make lint
# or
pylint src/telcoapi

# Run type checking
make typecheck
# or
mypy src/telcoapi

# Run code formatting
make format
# or
black src/telcoapi

2. Testing¶

# Run all tests
make test
# or
pytest

# Run specific test file
pytest tests/test_diameter.py

# Run with coverage
make coverage
# or
pytest --cov=telcoapi tests/

3. Documentation¶

# Install mkdocs and dependencies
pip install -r docs/requirements.txt

# Serve documentation locally
mkdocs serve

# Build documentation
mkdocs build

Docker Development¶

1. Development Container¶

# Dockerfile.dev
FROM python:3.9-slim

WORKDIR /app
COPY requirements-dev.txt .
RUN pip install -r requirements-dev.txt

COPY . .
CMD ["python", "-m", "telcoapi"]

2. Docker Compose Setup¶

# docker-compose.yml
version: '3.8'

services:
  telcoapi:
    build:
      context: .
      dockerfile: Dockerfile.dev
    volumes:
      - .:/app
    ports:
      - "3868:3868"
    environment:
      - TELCOAPI_ENV=development
      - DEBUG=true

  test-peer:
    image: telcoapi/test-peer
    ports:
      - "3869:3868"

3. Docker Commands¶

# Build and start development environment
docker-compose up -d

# Run tests in container
docker-compose exec telcoapi pytest

# Run linting in container
docker-compose exec telcoapi make lint

# Stop development environment
docker-compose down

Development Workflow¶

Create Feature Branch
```
git checkout -b feature/new-feature
```
Make Changes
Write code
Add tests
Update documentation

Run Quality Checks

# Run all checks
make check-all

# Or individual checks
make lint
make test
make typecheck
make docs

Commit Changes

git add .
git commit -m "feat: add new feature"

Create Pull Request
Push changes to GitHub
Create pull request
Wait for CI checks
Address review comments

Debugging¶

1. Logging Configuration¶

# setup_logging.py
import logging

logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[
        logging.FileHandler('debug.log'),
        logging.StreamHandler()
    ]
)

2. Protocol Debugging¶

from telcoapi.debug import ProtocolDebugger

debugger = ProtocolDebugger(
    protocol="diameter",
    log_level="DEBUG"
)

# Start debugging session
debugger.start_capture()

# Your code here
client.send_request(...)

# Stop debugging and analyze
debugger.stop_capture()
debugger.analyze()

3. Remote Debugging¶

import debugpy

# Allow remote debugging on port 5678
debugpy.listen(("0.0.0.0", 5678))

Performance Testing¶

1. Load Testing¶

from telcoapi.testing import LoadTester

tester = LoadTester(
    target="diameter_peer",
    concurrent_users=100,
    duration=300
)

results = tester.run()
results.generate_report()

2. Profiling¶

from telcoapi.profiling import Profiler

with Profiler() as p:
    # Your code here
    client.send_request(...)

p.print_stats()

Troubleshooting¶

Common Issues¶

Connection Issues

# Check network connectivity
telnet test.example.com 3868

# Check SSL/TLS
openssl s_client -connect test.example.com:3868

Protocol Issues

# Capture protocol traffic
tcpdump -i any port 3868 -w capture.pcap

# Analyze with Wireshark
wireshark capture.pcap

Environment Issues

# Check Python environment
python --version
pip list

# Check system resources
top
netstat -an | grep 3868