Development

Hopefully, you have landed here because you would like to help out with the development of Beanis. Whether through adding new features, fixing bugs, or extending documentation, your help is really appreciated! Please read this page carefully. If you have any questions, open an issue on GitHub.

Also, please read the Code of Conduct.

Setting up the development environment

We assume you are familiar with the general forking and pull request workflow for submitting to open-source projects. If not, don't worry, there are plenty of good guides available. Maybe check out this one.

All the dependencies and build configs are set in the pyproject.toml file. There are two main dependency sections there:

  • dependencies: for the dependencies required to run Beanis
  • test: for the dependencies required to run tests

To install all required dependencies, including test dependencies, in a virtual environment, run the following command in the root directory of the Beanis project:

pip install -e .[test]

Redis connection

To run tests and use Beanis in general, you will need an accessible Redis database. All tests assume that the database is hosted locally on port 6379 and do not require authentication.

You can run Redis locally using Docker:

docker run -d -p 6379:6379 redis:latest

Or install Redis natively: - macOS: brew install redis && brew services start redis - Linux: sudo apt-get install redis-server && sudo service redis-server start - Windows: Use Redis on Windows

Testing

Beanis uses pytest for unit testing. To ensure the stability of Beanis, each added feature must be tested in a separate unit test, even if it looks like other tests are covering it now. This strategy guarantees that:

  • All the features will be covered and stay covered.
  • There is independence from other features and test cases.

To run the test suite, make sure that you have Redis running and run pytest:

pytest

To run tests with coverage:

pytest --cov=beanis --cov-report=html

Submitting new code

You can submit your changes through a pull request on GitHub. Please take into account the following sections.

Use pre-commit

To ensure code consistency, Beanis uses Black and Ruff through pre-commit. To set it up, run:

pre-commit install

This will add the pre-commit command to your git's pre-commit hooks and make sure you never forget to run these.

Single commit

To make the pull request reviewing easier and keep the version tree clean, your pull request should consist of a single commit. It is natural that your branch might contain multiple commits, so you will need to squash these into a single commit. Instructions can be found here or here.

Add documentation

Please write clear documentation for any new functionality you add. Docstrings will be converted to the API documentation, but more human-friendly documentation might also be needed! See the section below.

Add tests

All new features and bug fixes must include tests. Tests should: - Be isolated and independent - Cover both success and failure cases - Use descriptive names - Clean up after themselves (delete test data)

Working on the documentation

The documentation is located in the docs/ folder and written in Markdown.

Documentation structure

  • docs/index.md - Main documentation landing page
  • docs/getting-started.md - Getting started guide
  • docs/tutorial/ - Step-by-step tutorials
  • docs/api/ - API reference (auto-generated)

Regenerating API documentation

The API documentation in docs/api/ is auto-generated from docstrings in the source code using pydoc-markdown.

To regenerate the API documentation after updating docstrings:

pydoc-markdown

This will: 1. Extract docstrings from the beanis package 2. Generate markdown files in docs/build/content/api-documentation/ 3. Copy the files to docs/api/

The configuration is in pydoc-markdown.yml. If you add new modules, update this file accordingly.

Preview documentation locally

You can preview documentation changes by serving the docs/ folder with any static file server:

# Using Python's built-in server
cd docs && python -m http.server 8000

Then visit http://localhost:8000 in your browser.

Project structure

beanis/
├── beanis/               # Main package
│   ├── odm/              # ODM core
│   │   ├── documents.py  # Document base class
│   │   ├── fields.py     # Field types
│   │   ├── operators/    # Query operators
│   │   ├── queries/      # Query builders
│   │   └── utils/        # Utilities (encoder, decoder)
│   └── executors/        # Background executors
├── tests/                # Test suite
│   ├── odm/              # ODM tests
│   ├── migrations/       # Migration tests (legacy)
│   └── fastapi/          # FastAPI integration tests
├── docs/                 # Documentation
└── benchmarks/           # Performance benchmarks

Contributing guidelines

Code style

  • Follow PEP 8
  • Use type hints for all functions
  • Write docstrings for public APIs
  • Keep functions small and focused

Git commit messages

  • Use present tense ("Add feature" not "Added feature")
  • Use imperative mood ("Move cursor to..." not "Moves cursor to...")
  • First line should be 50 characters or less
  • Reference issues and pull requests liberally

Example:

Add custom encoder support for NumPy arrays

- Register encoders/decoders for custom types
- Store type metadata with encoded values
- Auto-register NumPy and PyTorch types

Fixes #123

Pull request process

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Add tests for your changes
  5. Run tests (pytest)
  6. Run pre-commit checks (pre-commit run --all-files)
  7. Commit your changes
  8. Push to your fork (git push origin feature/amazing-feature)
  9. Open a pull request

Performance considerations

When contributing, keep these performance tips in mind:

  1. Use Redis pipelines - Batch operations when possible
  2. Minimize Redis round trips - Fetch data in bulk
  3. Profile changes - Run benchmarks for performance-critical code
  4. Avoid unnecessary validation - Skip validation on reads when safe
  5. Use msgspec - It's 2x faster than orjson for serialization

Run benchmarks:

python benchmarks/benchmark_vs_plain_redis.py

Questions?

If you have questions about contributing, please:

  1. Check existing GitHub issues
  2. Open a new issue with the question label
  3. Provide context and examples

Thank you for contributing to Beanis! 🎉