[DevX] Improve dependency management and virtual environment setup guide by Carla232 · Pull Request #277 · Udayraj123/OMRChecker

Carla232 · 2026-04-18T11:10:50Z

Closes #210

qodo-free-for-open-source-projects · 2026-04-18T11:11:06Z

Review Summary by Qodo

✨ Enhancement 📝 Documentation

Walkthroughs

Description

• Add pyproject.toml with project metadata and dependency groups for uv support
• Create comprehensive virtual environment setup guide with uv and pip workflows
• Update contributing guide with modern development setup instructions
• Replace python3 with python in pre-commit hooks for better portability
• Include OpenCV packages in pip fallback requirements

Diagram

flowchart LR
  A["pyproject.toml<br/>Project metadata<br/>& dependencies"] --> B["Virtual Environment<br/>Setup Guide"]
  A --> C["CONTRIBUTING.md<br/>Updated workflows"]
  B --> C
  D["requirements.txt<br/>OpenCV packages"] --> C
  E["pre-commit hooks<br/>python command"] --> C

File Changes

1. pyproject.toml ⚙️ Configuration changes +32/-0

Add project metadata and dependency groups

• Added project metadata including name, version, description, and Python version requirement
• Defined core dependencies (opencv, numpy, pandas, matplotlib, etc.)
• Created dev dependency group with testing and linting tools (pytest, flake8, ruff, pre-commit)

pyproject.toml

2. docs/virtual-environment-setup.md 📝 Documentation +57/-0

Create dedicated virtual environment setup guide

• New comprehensive guide for setting up local development environment
• Documents recommended uv workflow with sync and run commands
• Provides fallback pip + venv workflow for alternative setup
• Includes platform-specific activation instructions (Linux/macOS and Windows PowerShell)

docs/virtual-environment-setup.md

3. CONTRIBUTING.md 📝 Documentation +26/-5

Update contributing guide with modern setup

• Added new "Development setup" section with uv and pip workflows
• Links to comprehensive virtual environment setup guide
• Updated code formatting instructions to use uv run pre-commit
• Simplified test running instructions with uv run pytest

CONTRIBUTING.md

View more (2)

4. .pre-commit-config.yaml ⚙️ Configuration changes +2/-2

Replace python3 with python command

• Changed python3 to python in pytest-on-commit hook entry point
• Changed python3 to python in pytest-on-push hook entry point
• Improves portability across different Python installations

.pre-commit-config.yaml

5. requirements.txt Dependencies +2/-0

Include OpenCV packages in requirements

• Added opencv-contrib-python>=4.6.0 to dependencies
• Added opencv-python>=4.6.0 to dependencies
• Ensures OpenCV packages are available in pip fallback workflow

requirements.txt

qodo-free-for-open-source-projects · 2026-04-18T11:11:07Z

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

1. ~~Dependencies split across files~~ ☑ 📎 Requirement gap ⚙ Maintainability

Description

The PR introduces pyproject.toml as the recommended dependency source, but still documents and
updates requirements*.txt, leaving dependencies duplicated/scattered rather than a single
authoritative definition. This can cause drift between install methods and breaks reproducible setup
expectations.

Code

CONTRIBUTING.md[R17-36]

+# Development setup
+Project dependencies are managed via `pyproject.toml` (recommended with `uv`).
+See the full environment guide: [docs/virtual-environment-setup.md](docs/virtual-environment-setup.md).
+
+Recommended workflow (using `uv`):
+
+```.sh
+uv sync --group dev
+uv run pre-commit install --hook-type pre-commit --hook-type pre-push
+```
+
+Fallback workflow (`pip` + virtualenv):
+
+```.sh
+python3 -m venv .venv
+source .venv/bin/activate  # Windows PowerShell: .\.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+python -m pip install -r requirements.txt
+python -m pip install -r requirements.dev.txt
+pre-commit install --hook-type pre-commit --hook-type pre-push

Evidence
Compliance ID 1 requires a single, standardized dependency definition; the PR adds dependencies in
pyproject.toml while also keeping and instructing installs from
requirements.txt/requirements.dev.txt, and even updates requirements.txt, demonstrating
multiple authoritative sources.
Provide standardized Python dependency management (e.g., Poetry/pyproject.toml or equivalent)
CONTRIBUTING.md[17-36]
docs/virtual-environment-setup.md[45-51]
pyproject.toml[1-31]
requirements.txt[6-7]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The PR introduces `pyproject.toml` as the recommended dependency source but still relies on and updates `requirements*.txt`, creating multiple authoritative dependency definitions.
## Issue Context
Compliance requires a standardized, single authoritative dependency management approach for reproducible installs.
## Fix Focus Areas
- CONTRIBUTING.md[17-36]
- docs/virtual-environment-setup.md[45-51]
- pyproject.toml[1-31]
- requirements.txt[6-7]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

2. ~~Python version guidance conflicts~~ ☑ 🐞 Bug ⚙ Maintainability

Description

pyproject.toml now enforces requires-python = ">=3.10", but the README still advertises Python
3.5+ support, creating conflicting onboarding guidance and failed installs for users on older
Python. This inconsistency is introduced by the new packaging metadata and should be resolved by
updating docs and/or adjusting the Python requirement.

Code

pyproject.toml[R7-8]
+requires-python = ">=3.10"
+dependencies = [

Evidence

The new requires-python constraint is explicit in pyproject.toml, while the README claims a much
lower Python version requirement; these two statements cannot both be true for users following the
new uv/pyproject workflow.

pyproject.toml[1-19]
README.md[111-116]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`pyproject.toml` sets `requires-python = ">=3.10"` but README still claims Python 3.5+ support. This creates contradictory onboarding instructions and will block users on Python <3.10 when using `uv sync`/pyproject-based installation.
## Issue Context
This PR explicitly introduces `pyproject.toml` as the source of truth for dependency management. That makes `requires-python` an externally visible contract.
## Fix Focus Areas
- Choose one of:
- Update README to state Python 3.10+ (and adjust any other docs that mention older versions).
- Lower `requires-python` to match the actual supported range (only if the codebase truly supports it).
- pyproject.toml[1-19]
- README.md[111-116]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

3. Hooks depend on python ☑ 🐞 Bug ☼ Reliability

Description

The local pre-commit hooks now invoke python -m pytest with language: system, which relies on a
python executable being available on PATH at hook runtime and is inconsistent with the repo docs
that use python3. This can cause pre-commit to fail for contributors who follow the documented
python3-based workflow or whose environment lacks a python shim.

Code

.pre-commit-config.yaml[R44-46]

+        entry: python -m pytest -rfpsxEX --disable-warnings --verbose -k sample1
    language: system
    pass_filenames: false

Evidence

The PR changes local hook entries to python -m pytest while keeping language: system, so the
hook uses whatever python is on PATH. The repository’s setup instructions predominantly use
python3, creating an inconsistent and potentially broken contributor workflow.

.pre-commit-config.yaml[40-59]
CONTRIBUTING.md[17-37]
README.md[113-122]
README.md[175-199]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Local pre-commit hooks run pytest via `python` (PATH-dependent) under `language: system`, while project docs primarily instruct `python3`. This mismatch can break hooks for contributors depending on platform/PATH configuration.
## Issue Context
- Hooks are local and intended to run tests automatically.
- Documentation and other instructions in the repo consistently reference `python3`.
## Fix Focus Areas
- Decide on a single, documented interpreter strategy for hooks:
- Option A: revert entries back to `python3 -m pytest ...` for Unix consistency, and document Windows expectations.
- Option B: make hooks environment-managed (e.g., call `uv run pytest ...` if uv is the recommended path) and update docs accordingly.
- .pre-commit-config.yaml[40-59]
- CONTRIBUTING.md[17-48]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

4. ~~Duplicate OpenCV dependencies~~ ☑ 🐞 Bug ➹ Performance

Description

Both opencv-python and opencv-contrib-python are declared in requirements.txt and
pyproject.toml, which increases install size/time and makes the intended OpenCV distribution
ambiguous. The dependency set should be clarified by selecting the single wheel the project expects
contributors/users to install.

Code

requirements.txt[R6-7]
+opencv-contrib-python>=4.6.0
+opencv-python>=4.6.0

Evidence

The PR adds both OpenCV wheels to multiple dependency manifests, so a standard install will pull
both packages unless curated by the installer, increasing install cost and ambiguity.

requirements.txt[1-10]
pyproject.toml[8-19]
README.md[137-143]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Both `opencv-python` and `opencv-contrib-python` are listed as dependencies (in both requirements and pyproject). This increases install size/time and makes it unclear which OpenCV distribution is the canonical dependency.
## Issue Context
The README also instructs installing both, but the project should ideally declare one canonical OpenCV package to avoid redundancy.
## Fix Focus Areas
- Decide which OpenCV wheel is required:
- If contrib features are required, keep `opencv-contrib-python` and remove `opencv-python`.
- If contrib features are not required, keep `opencv-python` and remove `opencv-contrib-python`.
- Apply consistently across manifests and docs.
- requirements.txt[1-10]
- pyproject.toml[8-19]
- README.md[137-143]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Udayraj123

thanks for the PR, please address the comments added

Carla232 · 2026-04-18T11:41:29Z

Addressed all requested changes: switched docs to uv-only workflow, removed pip/venv fallback, deleted requirements.txt, and updated README accordingly.

Udayraj123

looks good. Can you please add a recording/screenshot of a pre-commit hook working the new setup?

Carla232 · 2026-04-21T17:33:13Z

Added screenshot proof for the updated hook setup on Windows.

Command run:
uv run pre-commit run pytest-on-commit --all-files

Result:
Running single sample test...............................................Passed

Udayraj123 · 2026-05-04T12:02:16Z

        for file in glob(os.path.join(_dir, EXT)):
-            relative_path = os.path.relpath(file, output_dir)
-            sample_outputs[relative_path] = read_file(file)
+            relative_path = os.path.relpath(file, output_dir).replace(os.sep, "/")


I guess this is useful for passing snapshots

Udayraj123 · 2026-05-04T12:03:26Z

-            sample_outputs[relative_path] = read_file(file)
+            relative_path = os.path.relpath(file, output_dir).replace(os.sep, "/")
+            sample_outputs[relative_path] = (
+                read_file(file).replace("\\", "/").replace("\r\n", "\n")


maybe introduce a small util read_and_process_output_file()

Udayraj123 · 2026-05-04T12:05:11Z

    mock_wait_key.return_value = ord("q")

+    # Stabilize snapshot file names across local timezones.
+    mock_time_suffix = mocker.patch("src.utils.file.strftime")


was this needed explicitly? we are already using freezegun for mocking time

Udayraj123

approved with minor comments, please check

Carla232 added 7 commits April 18, 2026 14:04

chore: add pyproject metadata and uv dependency groups

900f3a1

chore: include OpenCV packages in pip fallback requirements

90c7892

docs: add uv-based contributor setup and test workflow

980eeab

chore: make local pytest hooks use python command

9251093

chore: ignore modern local env and cache directories

36d0c74

docs: add dedicated virtual environment setup guide

9a536f1

docs: link virtual environment setup guide from contributing

478d3d5

chore: keep hidden-directory ignore pattern unchanged

aba38b3

Udayraj123 reviewed Apr 18, 2026

View reviewed changes

Comment thread docs/virtual-environment-setup.md Outdated

Comment thread CONTRIBUTING.md Outdated

Comment thread requirements.txt Outdated

qodo-free-for-open-source-projects Bot reviewed Apr 18, 2026

View reviewed changes

Comment thread CONTRIBUTING.md Outdated

Comment thread pyproject.toml

Carla232 added 4 commits April 18, 2026 14:26

docs(contributing): switch to uv-only development workflow

d1f84a1

docs: keep virtual environment setup guide uv-only

bef84e8

docs(readme): switch setup instructions to uv workflow

a184887

chore: remove requirements.txt in favor of pyproject dependencies

74d78c4

Udayraj123 reviewed Apr 21, 2026

View reviewed changes

Comment thread .pre-commit-config.yaml Outdated

Udayraj123 reviewed Apr 21, 2026

View reviewed changes

Comment thread docs/virtual-environment-setup.md Outdated

Carla232 added 2 commits April 21, 2026 20:08

Use uv run python in hooks and remove redundant env doc

04a611b

Stabilize sample tests for Windows pre-commit runs

93b98dd

Udayraj123 reviewed May 4, 2026

View reviewed changes

Udayraj123 approved these changes May 4, 2026

View reviewed changes

Uh oh!

Conversation

Carla232 commented Apr 18, 2026

Uh oh!

qodo-free-for-open-source-projects Bot commented Apr 18, 2026

Review Summary by Qodo

Walkthroughs

File Changes

Uh oh!

qodo-free-for-open-source-projects Bot commented Apr 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Review by Qodo

Uh oh!

Udayraj123 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Carla232 commented Apr 18, 2026

Uh oh!

Uh oh!

Udayraj123 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Carla232 commented Apr 21, 2026

Uh oh!

Udayraj123 May 4, 2026

Choose a reason for hiding this comment

Uh oh!

Udayraj123 May 4, 2026

Choose a reason for hiding this comment

Uh oh!

Udayraj123 May 4, 2026

Choose a reason for hiding this comment

Uh oh!

Udayraj123 left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

qodo-free-for-open-source-projects Bot commented Apr 18, 2026 •

edited

Loading