hyper/clp_auto_hedger/python-rules.md

Python Coding Standards (Visual Studio Style)

Naming Conventions

• Variables: snake_case (descriptive names)
• Functions: snake_case with descriptive verbs
• Classes: PascalCase
• Constants: UPPER_CASE_WITH_UNDERSCORES
• Private members: _leading_underscore
• Dunder methods: __double_underscore__

Code Style

• Use 4 spaces for indentation (never tabs)
• Line length: 100 characters (not 79)
• Blank lines between logical sections
• One statement per line where possible
• Use descriptive variable names, avoid abbreviations

Import Organization

1. Standard library imports first
2. Third-party imports second
3. Local/third-party imports last
4. Group related imports with blank lines between sections

Example:

import os
import sys
import time
import json
import threading
import re
import math

from dotenv import load_dotenv
from web3 import Web3
from eth_account import Account

Documentation

• Use docstrings for all functions and classes
• Follow Google-style or triple-quoted format
• Include parameter descriptions and return types
• Add inline comments for complex logic

Type Hints

• Use type hints for function parameters and returns
• Import typing module when needed
• Use Union for optional types
• Use Optional for parameters that can be None

Error Handling

• Use specific exceptions when possible
• Include informative error messages
• Use logging for debugging information
• Validate inputs before processing

Configuration and Constants

• Group configuration constants at module level
• Use descriptive section comments with ---
• Document environment variable usage
• Provide sensible defaults

Function Organization

• Keep functions focused on single responsibility
• Use helper functions for complex logic
• Group related functions together
• Use classes for related state and behavior

File Structure (Based on your code)

module_name.py
├── Imports (standard, third-party, local)
├── Configuration constants
├── Helper functions
├── Main classes
├── Utility functions  
└── Main execution block

Best Practices

• Use f-strings for string formatting
• Prefer list comprehensions when readable
• Use context managers for resources
• Avoid global variables when possible
• Use if __name__ == "__main__": for executable modules
• Follow PEP 8 with 100-char line length
• Use meaningful variable names that describe purpose

Web3/Blockchain Specific

• Handle connection errors gracefully
• Use proper address validation and cleaning
• Implement proper decimal handling for token amounts
• Use proper error handling for blockchain calls
• Include timeout considerations for network requests