Python Development with Bitsec Standards

A specialized Python development assistant that enforces Bitsec-AI coding standards, emphasizing comprehensive documentation preservation, robust error handling, type safety, and AI-friendly practices.

Core Principles

This skill guides development with the following priorities:

1. **Configuration Management**: Use environment variables for all configuration

2. **Robust Error Handling**: Comprehensive error handling with context capture and logging

3. **Comprehensive Testing**: Use pytest and pytest plugins exclusively (never unittest)

4. **Detailed Documentation**: Complete docstrings (PEP 257) and README files

5. **AI-Friendly Coding**: Clear, well-annotated code optimized for AI-assisted development

Critical Preservation Rules

**ABSOLUTE REQUIREMENTS - NEVER VIOLATE:**

**NEVER DELETE COMMENTS** - Preserve all existing comments in the codebase

**NEVER DELETE DOCSTRINGS** - All docstrings must remain intact

**NEVER DELETE LOGGING** - Keep all logging statements

**NEVER DELETE PYDANTIC FIELD INFO** - Preserve Pydantic field metadata and descriptions

**NEVER DELETE PRINT STATEMENTS** - Retain all print statements for debugging/output

Type Annotations

Add typing annotations to **every** function and class

Include return types for all functions where applicable

Annotate test functions with types as well

Use modern Python type hints (from `typing` module)

Example:

```python

def process_data(input: str, max_retries: int = 3) -> dict[str, any]:

"""Process input data with retry logic."""

pass

```

Documentation Standards

Docstrings (PEP 257 Convention)

Add descriptive docstrings to all Python functions and classes

Follow PEP 257 conventions strictly

Update existing docstrings only for significant, non-obvious changes

Include parameter descriptions, return values, and exceptions raised

Example:

```python

def calculate_metrics(data: list[dict]) -> dict[str, float]:

"""

Calculate performance metrics from input data.

Args:

data: List of dictionaries containing raw measurement data

Returns:

Dictionary containing calculated metrics with metric names as keys

Raises:

ValueError: If data list is empty or contains invalid entries

"""

pass

```

Comments

Write comments only for non-obvious code

Preserve all existing comments

Focus on explaining "why" rather than "what"

Testing Requirements

Test Framework

**ONLY use pytest or pytest plugins** - Never use the unittest module

Place all tests in `./tests` directory

Create `__init__.py` files for test directories and subdirectories

Test Structure

All tests must have typing annotations

All tests must contain docstrings

Tests should be fully annotated with expected behaviors

Example:

```python

def test_process_valid_data() -> None:

"""

Test that process_data correctly handles valid input.

Verifies that the function returns expected output format

and all required fields are present.

"""

result = process_data("valid_input")

assert isinstance(result, dict)

assert "status" in result

```

File and Directory Management

Create all necessary files and folders as needed

When creating files in `./tests` or new directories, ensure `__init__.py` exists

Maintain proper Python package structure

Error Handling and Logging

Implement comprehensive error handling with context capture

Include descriptive logging at appropriate levels (DEBUG, INFO, WARNING, ERROR)

Preserve all existing logging statements

Use structured logging where appropriate

Example:

```python

import logging

logger = logging.getLogger(__name__)

def risky_operation(param: str) -> bool:

"""Execute operation with comprehensive error handling."""

try:

logger.info(f"Starting operation with param: {param}")

# operation logic

logger.debug("Operation completed successfully")

return True

except ValueError as e:

logger.error(f"Invalid parameter value: {param}", exc_info=True)

raise

except Exception as e:

logger.error(f"Unexpected error in operation: {e}", exc_info=True)

raise

```

Configuration Management

Use environment variables for all configuration

Never hardcode sensitive values

Use `.env` files for local development with python-dotenv

Document all required environment variables in README

Code Quality Checklist

Before completing any task, verify:

[ ] All functions and classes have type annotations

[ ] All functions and classes have PEP 257 docstrings

[ ] No comments have been deleted

[ ] No logging statements have been removed

[ ] No Pydantic field info has been deleted

[ ] No print statements have been removed

[ ] Tests use pytest (not unittest)

[ ] All tests have annotations and docstrings

[ ] `__init__.py` files exist in all test directories

[ ] Error handling includes context and logging

Workflow

1. **Read existing code** - Understand current structure and documentation

2. **Preserve documentation** - Never delete comments, docstrings, or logging

3. **Add type annotations** - Ensure all code is fully typed

4. **Write/update docstrings** - Follow PEP 257 for significant changes

5. **Implement changes** - Apply requested modifications

6. **Add tests** - Create pytest tests with full annotations

7. **Verify preservation** - Confirm no documentation was removed

Notes

This skill is optimized for AI-assisted development with a strong emphasis on maintainability, clarity, and comprehensive documentation. The absolute prohibition on deleting comments, docstrings, logging, and other documentation ensures that codebases remain well-documented and traceable over time.

Python Development with Bitsec Standards

Python Development with Bitsec Standards

Core Principles

Critical Preservation Rules

Type Annotations

Documentation Standards

Docstrings (PEP 257 Convention)

Comments

Testing Requirements

Test Framework

Test Structure

File and Directory Management

Error Handling and Logging

Configuration Management

Code Quality Checklist

Workflow

Notes

Reviews (0)