Contributing

Thank you for your interest in contributing to the EMDB Python Client! We welcome contributions in the form of bug reports, feature requests, documentation improvements, and code enhancements.

Getting Started

To contribute, you will need to:

  1. Fork the repository on GitHub.

  2. Clone your fork:

    git clone git@github.com/your-username/emdb-api-wrapper.git
cd emdb-api-wrapper

  3. Set up a virtual environment and install the package in editable mode:

    python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[test]"

  4. Create a new branch for your feature or fix:

    git checkout -b my-feature

Development Guidelines

  • Follow PEP8 and existing code style.

  • Include type hints and docstrings where applicable.

  • Keep pull requests focused: one change per PR.

  • Write or update unit tests for any new functionality.

Testing

This project uses pytest for unit testing. Before submitting a pull request, make sure all tests pass:

# Run all tests
pytest

# Run tests with verbose output
pytest -v

# Run tests with coverage report
pytest --cov=emdb --cov-report=html

# Run specific test file
pytest tests/test_client.py

# Run specific test class or function
pytest tests/test_client.py::TestEMDBClient::test_get_entry_success

Test files are located in the tests/ directory. Each module has a corresponding test file:

  • tests/test_client.py - Tests for the EMDB client

  • tests/test_exceptions.py - Tests for exception classes

  • tests/test_utils.py - Tests for utility functions

  • tests/test_search.py - Tests for search and lazy entry loading

When adding new features, please include comprehensive unit tests that cover:

  • Normal operation cases

  • Edge cases

  • Error conditions

Documentation

Documentation is built using Sphinx. To build it locally:

sphinx-build -b html docs/source docs/build/html

Then open docs/build/html/index.html in your browser.

Submitting a Pull Request

  1. Push your changes to your fork:

    git push origin my-feature

  2. Open a Pull Request on GitHub.

  3. The maintainers will review your PR. Please respond to any feedback.

Code of Conduct

All contributors are expected to follow our Code of Conduct. Be respectful, collaborative, and inclusive in all interactions.

—

Happy coding and thank you for making the EMDB Python Client better!