Contributing

Tip

This document is synchronized with CONTRIBUTING.md in the GitHub repository. The upstream repository is authoritative; this copy may not always be current.

Thank you for your interest in RapidOCR Python. This guide explains how to prepare an environment, develop code, run tests and submit contributions in the Python directory.

Prerequisites¶

Python >= 3.6 (3.8+ recommended)
Git
A registered GitHub account

1. Clone the source¶

git clone https://github.com/RapidAI/RapidOCR.git
cd RapidOCR

If the network is restricted, use a mirror or proxy, or fork the repository first and clone your fork as described below.

2. Enter the Python directory and configure the environment¶

cd python

Use a virtual environment to avoid conflicts with the system Python:

# venv
python -m venv .venv
source .venv/bin/activate   # Linux/macOS
# .venv\Scripts\activate    # Windows

# or conda
conda create -n rapidocr python=3.10
conda activate rapidocr

Install dependencies. Editable installation is recommended during development:

pip install -r requirements.txt
pip install pytest
pip install -e .

For ONNX Runtime and other inference backends, follow the installation guide and inference engine guide.

3. Install formatting tools and pre-commit hooks¶

pip install pre-commit
cd ..
pre-commit install

The configured formatters, such as Black and autoflake, run automatically on git commit. You can run them manually from the repository root:

pre-commit run --all-files

4. Run unit tests¶

Run these commands from the python directory:

pytest tests/ -v
pytest tests/test_input.py -v
pytest tests/test_det_cls_rec.py -v
pytest tests/ -v --cov=rapidocr

The coverage command requires pytest-cov. Confirm that the baseline branch passes locally before making changes.

5. Reproduce issues or add features¶

Reproduce a bug¶

Select or create an issue in Issues.
Reproduce it locally using the code under python.
Locate the issue in rapidocr/ or tests/ and modify the code until it is resolved.

Add a feature¶

Discuss the requirement and implementation with a maintainer or in an existing issue when practical.
Implement the logic under rapidocr/, following the project style (including Black).
Add unit-test coverage for the new behavior.

6. Write corresponding unit tests¶

Put tests in python/tests/ and use the test_*.py naming convention.
Test images and other resources belong in tests/test_files/.
Tests should reliably reproduce the bug or feature and should not depend on undocumented external services. Use mocks or skips when necessary.

Example:

# tests/test_xxx.py
import pytest
from pathlib import Path

root_dir = Path(__file__).resolve().parent.parent
tests_dir = root_dir / "tests" / "test_files"

@pytest.fixture()
def engine():
    from rapidocr import RapidOCR
    return RapidOCR()

def test_your_new_feature(engine):
    img_path = tests_dir / "ch_en_num.jpg"
    result = engine(img_path)
    assert result is not None

7. Run all unit tests again¶

pytest tests/ -v

If tests are skipped because an inference backend is unavailable, confirm that your modified or new tests actually ran and passed in the current environment.

8. Prepare a submission¶

8.1 Fork the RapidOCR repository¶

Open the RapidOCR repository and click Fork.

8.2 Commit and push to your fork¶

git remote add myfork https://github.com/your-name/RapidOCR.git
git checkout -b fix/xxx
git add python/
git status
git commit -m "fix(python): short description"
git push myfork fix/xxx

Use Conventional Commits for commit messages:

<type>[optional scope]: <short description>

[optional body]
[optional footer]

Common types include feat, fix, docs, style, refactor, test and chore.

8.3 Open a pull request¶

Open your fork and click Compare & pull request, or create a pull request from the Branches page.
Set the base repository to RapidAI/RapidOCR, base branch to main, and the head to your fork and branch.
Include the issue number, reason for the change, main modifications and verification steps in the description.
Submit the pull request and push follow-up changes to the same branch after review.

Summary¶

Step	Description
1	Clone RapidOCR
2	Configure the Python environment and install dependencies
3	Install pre-commit
4	Run the baseline tests
5	Reproduce an issue or implement a feature
6	Add or update tests
7	Run the full test suite again
8	Fork, commit and push, then open a pull request

Additional notes¶

Code style: use Black, autoflake and the configured pre-commit hooks. Run pre-commit run --all-files before submitting.
Documentation: see the RapidOCR documentation for installation and usage details.
Issues and discussions: report bugs and feature requests through GitHub Issues.