Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
344 lines (238 loc) · 8.42 KB

CONTRIBUTING.md

File metadata and controls

344 lines (238 loc) · 8.42 KB

Contributing to Redis OM Python

Thank you for your interest in contributing to Redis OM Python! We welcome contributions from the community and are grateful for any help you can provide.

Table of Contents

Getting Started

Redis OM Python is an object mapping library for Redis that provides declarative models built on Pydantic. Before contributing, please:

  1. Read the README.md to understand the project
  2. Check existing issues and pull requests
  3. Review this contributing guide thoroughly

Development Setup

Prerequisites

  • Python 3.10 or higher (we test on 3.10-3.13)
  • uv for dependency management
  • Docker and Docker Compose for running Redis
  • Make (for running development commands)

Initial Setup

  1. Fork and clone the repository:

    git clone https://github.com/YOUR_USERNAME/redis-om-python.git
cd redis-om-python

  2. Install dependencies:

    make install

    This will use uv to install all dependencies in a virtual environment.

  3. Start Redis containers:

    make redis

    This starts two Redis instances:

    • Redis Stack (port 6380) - includes RediSearch and RedisJSON modules
    • Redis OSS (port 6381) - standard Redis for compatibility testing

Project Architecture

�� Critical: Dual Async/Sync Architecture

This project uses a unique dual-codebase approach:

  • /aredis_om/ - The PRIMARY source code (async implementation)
  • /redis_om/ - GENERATED sync version (DO NOT EDIT DIRECTLY)
  • /tests/ - Async tests
  • /tests_sync/ - GENERATED sync tests

IMPORTANT:

  • Always implement features in /aredis_om/ first
  • Never directly edit files in /redis_om/ or /tests_sync/
  • After making changes, run make sync to generate the sync versions

Key Components

  • Models: HashModel (Redis Hashes) and JsonModel (RedisJSON documents)
  • Query System: Expression-based queries with Django ORM-like syntax
  • Field System: Pydantic fields extended with Redis-specific features
  • Migration System: Automatic RediSearch index management

Development Workflow

1. Making Code Changes

For any new feature or bug fix:

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

# 2. Make changes in /aredis_om/ (async code)
# Edit files...

# 3. Generate sync version
make sync

# 4. Format your code
make format

# 5. Run linters
make lint

# 6. Run tests
make test

2. Common Development Commands

make install    # Install dependencies
make redis      # Start Redis containers
make sync       # Generate sync code from async
make format     # Format code with black and isort
make lint       # Run all linters (flake8, mypy, bandit)
make test       # Run full test suite against Redis Stack
make test_oss   # Run tests against OSS Redis
make clean      # Remove generated files and containers
make all        # Run lint, format, and test

3. Development Cycle Example

Here's a typical development cycle for adding a new feature:

# 1. Start Redis
make redis

# 2. Create your feature in /aredis_om/
vim aredis_om/model/model.py

# 3. Generate sync version
make sync

# 4. Write tests in /tests/
vim tests/test_your_feature.py

# 5. Run tests iteratively
uv run pytest tests/test_your_feature.py -vv

# 6. Format and lint
make format
make lint

# 7. Run full test suite
make test

Testing

Running Tests

# Run all tests
make test

# Run specific test file
uv run pytest tests/test_hash_model.py -vv

# Run specific test
uv run pytest tests/test_hash_model.py::test_saves_model -vv

# Run with coverage
uv run pytest --cov=aredis_om --cov=redis_om --cov-report=term-missing

# Run tests in parallel
uv run pytest -n auto

# Test against OSS Redis (without modules)
make test_oss

Writing Tests

  1. Write async tests in /tests/

  2. Use fixtures from conftest.py for Redis connections

  3. Mark module-dependent tests appropriately:

    @pytest.mark.asyncio
async def test_json_model_feature():
    # Test requiring RedisJSON
    pass

  4. Ensure tests work with both Redis Stack and OSS Redis where applicable

Test Coverage

We aim for high test coverage. New features should include comprehensive tests covering:

  • Happy path scenarios
  • Edge cases
  • Error conditions
  • Both async and sync versions (sync tests are auto-generated)

Code Style

Formatting and Linting

We use several tools to maintain code quality:

  • black - Code formatting
  • isort - Import sorting
  • flake8 - Style guide enforcement
  • mypy - Static type checking
  • bandit - Security linting

Run all checks with:

make format  # Auto-format code
make lint    # Check for issues

Style Guidelines

  1. Type Hints: Use type hints for all function signatures
  2. Docstrings: Add docstrings to public methods and classes
  3. Async First: Implement in async (/aredis_om/) first
  4. Pydantic Models: Leverage Pydantic's validation features
  5. Error Messages: Provide clear, actionable error messages

Example Code Style

from typing import Optional, List
from pydantic import Field
from aredis_om import HashModel

class Customer(HashModel):
    """A customer model stored as a Redis Hash."""

    first_name: str = Field(index=True)
    last_name: str = Field(index=True)
    email: str = Field(index=True)
    age: int = Field(index=True, ge=0, le=120)

    class Meta:
        database = get_redis_connection()

Submitting Changes

Pull Request Process

  1. Ensure all tests pass:

    make test

  2. Update documentation:

    • Add docstrings for new functions/classes
    • Update README.md if adding major features
    • Add examples for new functionality

  3. Create Pull Request:

    • Use a clear, descriptive title
    • Reference any related issues
    • Describe what changes you made and why
    • Include examples of how to use new features

Pull Request Checklist

  • Code is in /aredis_om/ (async implementation)
  • Ran make sync to generate sync version
  • All tests pass (make test)
  • Code is formatted (make format)
  • Linters pass (make lint)
  • Added/updated tests for changes
  • Added docstrings for public APIs
  • Commits are logical and well-described

Commit Messages

Use clear, descriptive commit messages:

  • Start with a verb (Add, Fix, Update, Remove)
  • Keep the first line under 50 characters
  • Reference issues when applicable

Examples:

Add support for vector similarity search
Fix index creation for nested JSON models
Update dependencies to support Python 3.13
Remove deprecated query methods

Reporting Issues

Bug Reports

When reporting bugs, please include:

  1. Environment details:

    • Python version
    • Redis OM version
    • Redis server version
    • OS and version

  2. Minimal reproducible example:

    # Your code that demonstrates the issue

  3. Expected vs actual behavior

  4. Full error messages and stack traces

Feature Requests

For feature requests, please describe:

  • The use case you're trying to solve
  • How you envision the feature working
  • Code examples of the proposed API

Additional Resources

Getting Help

License

By contributing to Redis OM Python, you agree that your contributions will be licensed under the MIT License.

Thank You

Thank you for contributing to Redis OM Python! Your efforts help make this library better for everyone in the Redis community.