Merge pull request #2 from longway-code/fix/refine-readme

use uv for management

Author: longway-code

.github/workflows/ci.yml

@@ -12,7 +12,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        python-version: ['3.8', '3.9', '3.10', '3.11']
+        python-version: ['3.10', '3.11', '3.12', '3.13']
 
     steps:
     - uses: actions/checkout@v3
@@ -22,19 +22,15 @@ jobs:
       with:
         python-version: ${{ matrix.python-version }}
 
-    - name: Cache pip packages
-      uses: actions/cache@v3
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
       with:
-        path: ~/.cache/pip
-        key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements*.txt') }}
-        restore-keys: |
-          ${{ runner.os }}-pip-
+        enable-cache: true
 
     - name: Install dependencies
       run: |
-        python -m pip install --upgrade pip
-        pip install -e .
-        pip install -r requirements-dev.txt
+        uv pip install --system -e .
+        uv pip install --system -r requirements-dev.txt
 
     - name: Lint with flake8
       run: |
@@ -79,10 +75,12 @@ jobs:
       with:
         python-version: '3.10'
 
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+
     - name: Install build dependencies
       run: |
-        python -m pip install --upgrade pip
-        pip install build twine
+        uv pip install --system build twine
 
     - name: Build package
       run: |

CONTRIBUTING.md

@@ -39,22 +39,45 @@ Enhancement suggestions are tracked as GitHub issues. When creating an enhanceme
 
 ## Development Setup
 
+### Prerequisites
+
+- Python 3.10 or higher
+- [uv](https://github.com/astral-sh/uv) package manager
+
+### Setup Steps
+
 1. Clone your fork:
 ```bash
 git clone https://github.com/yourusername/ContrastCheck.git
 cd ContrastCheck
 ```
 
-2. Create a virtual environment:
+2. Install uv if you haven't already:
 ```bash
-python -m venv venv
-source venv/bin/activate  # On Windows: venv\Scripts\activate
+# On macOS and Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# On Windows
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+3. Create a virtual environment with Python 3.10+:
+```bash
+uv venv --python 3.10
+```
+
+4. Activate the virtual environment:
+```bash
+# On macOS/Linux:
+source .venv/bin/activate
+
+# On Windows:
+.venv\Scripts\activate
 ```
 
-3. Install development dependencies:
+5. Install development dependencies:
 ```bash
-pip install -e .
-pip install -r requirements-dev.txt
+uv pip install -e ".[dev]"
 ```
 
 ## Coding Standards

Makefile

@@ -1,9 +1,10 @@
-.PHONY: help install install-dev test test-cov lint format clean build upload docs
+.PHONY: help venv install install-dev test test-cov lint format clean build upload docs
 
 help:
 	@echo "ContrastCheck - Development Commands"
 	@echo ""
 	@echo "Available targets:"
+	@echo "  venv          - Create virtual environment with uv"
 	@echo "  install       - Install package in production mode"
 	@echo "  install-dev   - Install package with development dependencies"
 	@echo "  test          - Run tests with pytest"
@@ -15,12 +16,17 @@ help:
 	@echo "  upload        - Upload package to PyPI"
 	@echo "  docs          - Generate documentation"
 
+venv:
+	uv venv --python 3.10
+	@echo "Virtual environment created. Activate it with:"
+	@echo "  source .venv/bin/activate  (macOS/Linux)"
+	@echo "  .venv\\Scripts\\activate     (Windows)"
+
 install:
-	pip install -e .
+	uv pip install -e .
 
 install-dev:
-	pip install -e .
-	pip install -r requirements-dev.txt
+	uv pip install -e ".[dev]"
 
 test:
 	pytest

README.md

@@ -1,6 +1,6 @@
 # ContrastCheck
 
-[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 A powerful tool for analyzing text-background contrast ratios in UI screenshots using PaddleOCR and K-means clustering to ensure WCAG accessibility compliance.
@@ -18,36 +18,60 @@ A powerful tool for analyzing text-background contrast ratios in UI screenshots
 
 ### Prerequisites
 
-- Python 3.8 or higher
-- pip package manager
+- Python 3.10 or higher
+- [uv](https://github.com/astral-sh/uv) - Fast Python package and project manager
 
-### Install from source
+### Install uv
+
+If you don't have uv installed:
 
 ```bash
-git clone https://github.com/longweillw-blip/ContrastCheck.git
-cd ContrastCheck
-pip install -e .
+# On macOS and Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# On Windows
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+
+# Or via pip
+pip install uv
 ```
 
-### Install dependencies
+### Install from source
 
 ```bash
-pip install -r requirements.txt
+git clone https://github.com/longway-code/ContrastCheck.git
+cd ContrastCheck
+
+# Create virtual environment with uv (Python 3.10+)
+uv venv --python 3.10
+
+# Activate virtual environment
+# On macOS/Linux:
+source .venv/bin/activate
+# On Windows:
+.venv\Scripts\activate
+
+# Install the package
+uv pip install -e .
 ```
 
-For development:
+### Install dependencies
 
 ```bash
-pip install -r requirements-dev.txt
+# Production dependencies
+uv pip install -r requirements.txt
+
+# Development dependencies
+uv pip install -r requirements-dev.txt
 ```
 
 ### GPU Support (Optional)
 
 For faster OCR processing with GPU:
 
 ```bash
-pip uninstall paddlepaddle
-pip install paddlepaddle-gpu
+uv pip uninstall paddlepaddle
+uv pip install paddlepaddle-gpu
 ```
 
 ## Quick Start
@@ -227,6 +251,19 @@ ContrastCheck/
 
 ## Development
 
+### Setup Development Environment
+
+```bash
+# Create virtual environment with Python 3.10+
+uv venv --python 3.10
+
+# Activate virtual environment
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install in development mode with dev dependencies
+uv pip install -e ".[dev]"
+```
+
 ### Running Tests
 
 Run all tests:
@@ -310,15 +347,15 @@ If you use ContrastCheck in your research or project, please cite:
   title = {ContrastCheck: UI Screenshot Contrast Ratio Analyzer},
   author = {ContrastCheck Contributors},
   year = {2026},
-  url = {https://github.com/longweillw-blip/ContrastCheck}
+  url = {https://github.com/longway-code/ContrastCheck}
 }
 ```
 
 ## Support
 
 If you encounter any issues or have questions:
 
-- Open an issue on [GitHub](https://github.com/yourusername/ContrastCheck/issues)
+- Open an issue on [GitHub](https://github.com/longway-code/ContrastCheck/issues)
 - Check the [examples](examples/) directory for usage examples
 - Read the [WCAG 2.1 documentation](https://www.w3.org/WAI/WCAG21/quickref/) for accessibility guidelines
 

contrast_check/__init__.py

@@ -8,8 +8,8 @@
 __version__ = "0.1.0"
 __author__ = "ContrastCheck Contributors"
 
-from .ocr_extractor import OCRExtractor
 from .color_extractor import ColorExtractor
 from .contrast_checker import ContrastChecker
+from .ocr_extractor import OCRExtractor
 
 __all__ = ["OCRExtractor", "ColorExtractor", "ContrastChecker"]

contrast_check/color_extractor.py

@@ -2,10 +2,10 @@
 Color extraction module using K-means clustering.
 """
 
-import numpy as np
-from typing import Tuple, List
-from PIL import Image
+from typing import List, Tuple
+
 import cv2
+import numpy as np
 from sklearn.cluster import KMeans
 
 
@@ -26,9 +26,7 @@ def __init__(self, n_text_colors: int = 3, n_bg_colors: int = 3):
         self.n_bg_colors = n_bg_colors
 
     def extract_text_color(
-        self,
-        image: np.ndarray,
-        text_mask: np.ndarray
+        self, image: np.ndarray, text_mask: np.ndarray
     ) -> Tuple[int, int, int]:
         """
         Extract dominant text color from the masked region.
@@ -48,15 +46,14 @@ def extract_text_color(
 
         # Convert BGR to RGB
         text_pixels_rgb = cv2.cvtColor(
-            text_pixels.reshape(-1, 1, 3),
-            cv2.COLOR_BGR2RGB
+            text_pixels.reshape(-1, 1, 3), cv2.COLOR_BGR2RGB
         ).reshape(-1, 3)
 
         # Use K-means to find dominant colors
         kmeans = KMeans(
             n_clusters=min(self.n_text_colors, len(text_pixels)),
             random_state=42,
-            n_init=10
+            n_init=10,
         )
         kmeans.fit(text_pixels_rgb)
 
@@ -73,7 +70,7 @@ def extract_background_color(
         image: np.ndarray,
         text_mask: np.ndarray,
         bbox: List[List[float]],
-        margin: int = 10
+        margin: int = 10,
     ) -> Tuple[int, int, int]:
         """
         Extract background color around the text region.
@@ -109,15 +106,12 @@ def extract_background_color(
 
         # Convert BGR to RGB
         bg_pixels_rgb = cv2.cvtColor(
-            bg_pixels.reshape(-1, 1, 3),
-            cv2.COLOR_BGR2RGB
+            bg_pixels.reshape(-1, 1, 3), cv2.COLOR_BGR2RGB
         ).reshape(-1, 3)
 
         # Use K-means to find dominant colors
         kmeans = KMeans(
-            n_clusters=min(self.n_bg_colors, len(bg_pixels)),
-            random_state=42,
-            n_init=10
+            n_clusters=min(self.n_bg_colors, len(bg_pixels)), random_state=42, n_init=10
         )
         kmeans.fit(bg_pixels_rgb)
 
@@ -140,4 +134,4 @@ def rgb_to_hex(rgb: Tuple[int, int, int]) -> str:
         Returns:
             Hex color code string
         """
-        return '#{:02x}{:02x}{:02x}'.format(int(rgb[0]), int(rgb[1]), int(rgb[2]))
+        return "#{:02x}{:02x}{:02x}".format(int(rgb[0]), int(rgb[1]), int(rgb[2]))