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

# Python dependencies using UV (recommended)
uv sync

# Or using pip
pip install -e ".[cli]"

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

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

Use the CLI tools or run directly:

# Format code
s0 sdk format

# Lint code
s0 sdk lint --fix

# Type check
s0 sdk check

Or use individual commands:

# Using ruff
ruff format src tests
ruff check --fix src tests

# Using mypy
mypy --strict src

4. Run Tests

# Run all tests
s0 sdk test

# Run with coverage
s0 sdk test --coverage

# Run specific test file
s0 sdk test tests/test_vault.py

# Run with verbose output
s0 sdk test -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
│   └── cli/                  # CLI tools
├── tests/                    # Test suite
├── docs/                     # Documentation
├── pyproject.toml            # Project configuration
└── mkdocs.yml               # Documentation config

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
s0 sdk format && s0 sdk lint --fix && s0 sdk check && s0 sdk test

# 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
s0 sdk format && \
  s0 sdk lint --fix && \
  s0 sdk check && \
  s0 sdk test --coverage

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 the package
pip install -e ".[cli]"

# Or with UV
uv sync

Type Errors

# Check type errors
s0 sdk check --path src

# Or with mypy
mypy --strict src/socket0

Test Failures

# Run with verbose output
s0 sdk test -v

# Or with pytest
pytest -v tests/

Pre-commit Failures

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

# Fix issues
s0 sdk format
s0 sdk lint --fix

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.