Contributing

We welcome contributions to the Socket0 Python SDK! This guide covers how to set up your development environment and contribute to the project.

Development Setup

Prerequisites

• Python 3.10 or higher
• Git
• UV package manager (recommended) or pip

Clone Repository

git clone https://github.com/socket0/socket0-python-sdk.git
cd socket0-python-sdk

Install Development Environment

For complete local development (including CLI, dev tools, and documentation):

# Install all Python dependencies (dev tools + CLI features)
uv sync --all-extras

# Install Node.js dependencies for documentation (VitePress)
npm install

For minimal development (without CLI features):

uv sync

Manual alternative using pip:

pip install -e ".[cli]"
pip install -r requirements-dev.txt

Prerequisites for documentation:

• Node.js 18.0+ (download)
• npm 9.0+ (comes with Node.js)

Development Workflow

1. Create a Feature Branch

git checkout -b feature/my-feature

2. Make Changes

Follow the existing code style and conventions:

• Type Hints: All code must be fully typed
• Documentation: Add docstrings to functions and classes
• Tests: Write tests for new functionality
• No Comments: Avoid code comments (use clear naming instead)

3. Format and Lint

# Format code
ruff format src tests

# Lint code
ruff check --fix src tests

# Type check
mypy --strict src

4. Run Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=src/socket0 --cov-report=html

# Run specific test file
pytest tests/test_vault.py

# Run with verbose output
pytest -v

5. Commit Changes

# Pre-commit hooks will run automatically
git commit -m "Add new feature: description"

6. Create Pull Request

Push your branch and create a PR on GitHub:

git push origin feature/my-feature

Testing Guidelines

Test Organization

• Tests are in tests/ directory
• Each module has a corresponding test file
• Test files start with test_ prefix
• Test classes start with Test prefix

Writing Tests

import pytest
from socket0.vault.base import SecretBucket

class TestMyFeature:
    def test_feature_works(self):
        """Clear description of what this tests"""
        # Arrange
        vault = SecretBucket.create_with_rsa(...)

        # Act
        result = vault.reveal(...)

        # Assert
        assert result == expected

Running Specific Tests

# Run single test file
pytest tests/test_vault.py

# Run specific test class
pytest tests/test_vault.py::TestVault

# Run specific test
pytest tests/test_vault.py::TestVault::test_method

# Run tests matching pattern
pytest -k "vault"

# Run with coverage
pytest --cov=src/socket0 --cov-report=html

Code Style

Naming Conventions

• Classes: PascalCase
• Functions/Methods: snake_case
• Constants: UPPER_SNAKE_CASE
• Private: Start with _

Type Hints

from typing import Optional, List, Dict

def process_data(
    data: str,
    count: int = 10,
    options: Optional[Dict[str, str]] = None,
) -> List[str]:
    """Process data and return results."""
    pass

Docstrings

def my_function(name: str) -> str:
    """One-line summary.

    Longer description explaining the function's behavior,
    parameters, return value, and any exceptions.

    Args:
        name: Description of the name parameter.

    Returns:
        Description of the return value.

    Raises:
        ValueError: When something goes wrong.
    """

Project Structure

socket0-python-sdk/
├── src/socket0/              # Main package
│   ├── vault/                # Vault module
│   └── api/                  # API client
├── tests/                    # Test suite
├── docs/                     # Documentation
└── pyproject.toml            # Project configuration

Common Tasks

Add a New Feature

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

# 2. Implement feature in src/socket0/
# 3. Add tests in tests/
# 4. Run quality checks
ruff format src tests && \
ruff check --fix src tests && \
mypy --strict src && \
pytest

# 5. Commit and push
git commit -m "Add new feature"
git push origin feature/new-feature

Add Documentation

# 1. Add markdown file to docs/
# 2. Update .vitepress/config.ts navigation if needed
# 3. Build docs locally
npm run docs:dev

# 4. Visit http://localhost:5173 to preview

Update sidebar navigation in .vitepress/config.ts:

sidebar: {
  '/your-section/': [
    {
      text: 'Section Name',
      items: [
        { text: 'Page Title', link: '/your-section/page' },
      ],
    },
  ],
}

For VitePress documentation details, see VitePress Setup Guide.

Run Full Quality Check

# One-liner to check everything
ruff format src tests && \
  ruff check --fix src tests && \
  mypy --strict src && \
  pytest --cov=src/socket0 --cov-report=html

Pre-commit Hooks

The project uses pre-commit hooks to ensure code quality. They run automatically before commits:

# Install pre-commit (if not already installed)
pip install pre-commit

# Install hooks
pre-commit install

# Run manually
pre-commit run --all-files

Hooks check:

• Code formatting (ruff)
• Linting (ruff)
• Type safety (mypy)
• No large files
• No debug statements

Troubleshooting

Import Errors

# Reinstall dependencies
uv sync

# Or for complete setup with all features
uv sync --all-extras

Type Errors

# Check type errors with mypy
mypy --strict src/socket0

Test Failures

# Run with verbose output
pytest -v tests/

Pre-commit Failures

# Run pre-commit to see issues
pre-commit run --all-files

# Fix issues
ruff format src tests
ruff check --fix src tests

Questions?

• Open an issue on GitHub
• Check existing documentation
• Review similar code in the project

License

By contributing, you agree that your contributions will be licensed under the same license as the project (Socket0 Python SDK Custom Proprietary License). See License for details.

Note: This project is not open source. While we welcome contributions, the code cannot be modified or redistributed externally. Contributions are accepted for internal development only.