VPN/.serena/memories/code_style_conventions.md

VPN Access Server - Code Style and Conventions

Python Version and Requirements

• Python version: 3.13+ (minimum requirement)
• Type hints: Required for all function parameters and return values
• Docstrings: Mandatory for all functions, classes, and modules
• Encoding: UTF-8 for all files

Naming Conventions

• Functions and variables: snake_case (e.g., validate_mac_address, user_id)
• Classes: PascalCase (e.g., ClientRequest, DatabaseConnection)
• Constants: UPPER_CASE (e.g., DEFAULT_SESSION_LIMIT)
• Modules: snake_case (e.g., auth.py, session.py)

Import Organization

# Standard library imports
import os
import sys
import logging
from typing import Optional, Dict, Any

# Third-party imports
import mysql.connector
from fastapi import FastAPI

# Local imports
from config import config
from utils import setup_logging

Error Handling

• Use try/except blocks for all database operations and external API calls
• Custom exit codes: 0=success, 1=authentication failure, 2=configuration error
• Log all errors with appropriate log levels
• Use safe_exit() utility for graceful error termination

Logging

• Use setup_logging() from access.utils for consistent logging
• Structured log format with timestamps, logger name, level, and message
• Log levels: DEBUG, INFO, WARNING, ERROR, CRITICAL
• File and console handlers supported

Security Practices

• SQL: Always use parameterized queries to prevent injection
• Credentials: Store in environment variables, never in code
• Passwords: Hash using secure algorithms (bcrypt/scrypt)
• Configuration: Validate all configuration before use
• Access: Principle of least privilege for database accounts

Code Structure

• Functions: Small, focused, single responsibility
• Classes: When needed for related functionality
• Modules: Logical grouping of related functions
• Error messages: Clear, actionable, and secure (no sensitive data)

Database Design

• Use foreign keys and constraints
• Index frequently queried columns
• Use appropriate data types
• Handle connection pooling for performance