Merge pull request #2 from atlasia-ma/chore/dev-tooling

chore: modernise packaging, add CI, fix unconstrained rendering

Author: hBouanane

.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install ruff
+      - run: ruff check src tests
+      - run: ruff format --check src tests
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install
+        run: pip install -e ".[data,dev]"
+      - name: Test
+        run: pytest --cov --cov-report=term-missing

CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Development tooling: ruff lint/format configuration, pytest configuration with
+  `pythonpath = ["src"]` (so a clean clone is testable without installing), coverage
+  settings, and a GitHub Actions CI matrix over Linux/Windows and Python 3.10/3.12.
+- `CONTRIBUTING.md` describing the TDD workflow, branch naming, and release process.
+- Regression tests covering rendering without layout constraints.
+
+### Changed
+
+- `pyproject.toml`: dependency pins relaxed to compatible ranges, heavy tabular and
+  Hugging Face dependencies moved into the `data` extra, project metadata and URLs
+  completed.
+- `HuggingFaceTextLoader` accepts any iterable of mappings, streams records via
+  `iter_texts`, and defers the `datasets` import to call time.
+
+### Fixed
+
+- `wrap_text_by_pixels` raised `TypeError` when `layout.max_width` / `layout.max_height`
+  were unset, which made every sample fail for configs that omit them.
+- Whitespace-only input no longer produces a zero-sized canvas.

CONTRIBUTING.md

@@ -0,0 +1,66 @@
+# Contributing to OCRSmith
+
+Thanks for helping build OCRSmith. This document describes how the project is
+developed so that contributions land smoothly.
+
+## Development setup
+
+```bash
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e ".[data,dev]"
+pytest
+```
+
+`pytest` works from a clean clone without an install because `pythonpath = ["src"]`
+is set in `pyproject.toml`.
+
+## Test-driven workflow
+
+Every behavioural change starts with a test.
+
+1. Write a failing test under `tests/` that expresses the desired behaviour.
+2. Run it and watch it fail for the right reason.
+3. Write the smallest implementation that makes it pass.
+4. Refactor with the suite green.
+
+Rendering code is tested against *properties*, not golden images: bounding boxes
+must sit inside the page, text must round-trip through shaping, generated
+samples must carry a label. Golden-image tests are brittle across FreeType
+versions and are avoided.
+
+## Code style
+
+- `ruff check src tests` and `ruff format src tests` must pass.
+- Strategy classes live one-per-file under the subsystem they belong to and are
+  re-exported from the package `__init__.py`.
+- Public functions carry type hints. Domain objects are frozen dataclasses.
+- Prefer generators over materialised lists on any path that can see a large
+  dataset.
+
+## Branch and commit conventions
+
+Branches are named `<type>/<slug>`:
+
+| Type       | Use                                        |
+| ---------- | ------------------------------------------ |
+| `feat/`    | new capability                             |
+| `fix/`     | bug fix                                    |
+| `refactor/`| behaviour-preserving restructure           |
+| `perf/`    | performance work                           |
+| `docs/`    | documentation only                         |
+| `chore/`   | tooling, CI, dependencies                  |
+
+Commits follow [Conventional Commits](https://www.conventionalcommits.org/):
+`feat(text): add bidi-aware line segmentation`.
+
+## Pull requests
+
+One PR per branch, one concern per PR. The description states what changed, why,
+and how it was verified. CI (lint + tests on Linux/Windows, Python 3.10 and 3.12)
+must be green before merge.
+
+## Releasing
+
+1. Update `CHANGELOG.md` under a new version heading.
+2. Bump `version` in `pyproject.toml`.
+3. Tag `vX.Y.Z` on `main` and publish the GitHub release.

pyproject.toml

@@ -5,31 +5,111 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "ocrsmith"
 version = "0.1.0"
-description = "A versatile OCR dataset generator for Arabic and Latin text, with synthetic text generation and dataset export."
+description = "Synthetic document and OCR dataset forge for Arabic, Darija and Latin scripts."
 readme = "README.md"
 authors = [
     { name = "Haitam Bouanane", email = "bouananehaitam03@gmail.com" }
 ]
 license = { file = "LICENSE" }
-keywords = ["OCR", "synthetic data", "Arabic OCR", "dataset generator"]
-requires-python = ">=3.11"
+keywords = [
+    "OCR",
+    "synthetic data",
+    "Arabic OCR",
+    "document AI",
+    "dataset generator",
+    "document understanding",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Image Processing",
+]
+requires-python = ">=3.10"
 dependencies = [
-    "pydantic>=2.11.7",
-    "PyYAML==6.0.2",
-    "pillow==11.3.0",
-    "numpy==2.3.1",
-    "pandas==2.3.1",
-    "datasets==3.6.0"
+    "pydantic>=2.7",
+    "PyYAML>=6.0",
+    "pillow>=10.0",
+    "numpy>=1.24",
+    "arabic-reshaper>=3.0",
+    "python-bidi>=0.4.2",
+    "typer>=0.12",
+    "rich>=13.0",
+    "tqdm>=4.66",
 ]
 
 [project.optional-dependencies]
+# Tabular / HuggingFace text sources and dataset export targets.
+data = [
+    "pandas>=2.0",
+    "pyarrow>=14.0",
+    "datasets>=2.19",
+    "huggingface-hub>=0.23",
+]
 dev = [
-    "pytest==8.4.1",
-    "pytest-cov==6.2.1"
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.5",
+]
+all = [
+    "ocrsmith[data,dev]",
 ]
 
+[project.urls]
+Homepage = "https://github.com/atlasia-ma/OCRSmith"
+Repository = "https://github.com/atlasia-ma/OCRSmith"
+Issues = "https://github.com/atlasia-ma/OCRSmith/issues"
+
 [project.scripts]
 ocrsmith = "ocrsmith.cli:main"
 
 [tool.setuptools.packages.find]
 where = ["src"]
+
+[tool.setuptools.package-data]
+ocrsmith = ["config/*.yaml", "config/presets/*.yaml"]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+# Makes `pytest` work straight from a clone, without an editable install.
+pythonpath = ["src"]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers"
+markers = [
+    "slow: tests that render many samples or touch the network",
+    "network: tests that require internet access",
+]
+filterwarnings = ["ignore::DeprecationWarning"]
+
+[tool.coverage.run]
+branch = true
+source = ["src/ocrsmith"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+]
+
+[tool.ruff]
+line-length = 110
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "C4", "SIM"]
+ignore = [
+    "E501",   # line length is handled by the formatter
+    "B008",   # typer uses callables in argument defaults by design
+    "SIM108", # ternaries are not always clearer
+]
+
+[tool.ruff.lint.per-file-ignores]
+# Re-exporting is what an __init__.py is for; the packages that care declare __all__.
+"__init__.py" = ["F401"]
+"tests/*" = ["B011"]

src/ocrsmith/cli.py

@@ -2,8 +2,8 @@
 
 
 def main() -> None:
-	app_main()
+    app_main()
 
 
 if __name__ == "__main__":
-	main()
+    main()

src/ocrsmith/config/__init__.py

@@ -1,3 +1,3 @@
 # src/ocrsmith/config/__init__.py
-from .schema import AppConfig
 from .loader import load_config
+from .schema import AppConfig

src/ocrsmith/config/loader.py

@@ -1,13 +1,16 @@
 # src/ocrsmith/config/loader.py
-from .schema import AppConfig
-import yaml
 import os
 
+import yaml
+
+from .schema import AppConfig
+
+
 def load_config(config_path=None):
     if config_path is None:
         config_path = os.path.join(os.path.dirname(__file__), "default_config.yaml")
-    with open(config_path, "r") as f:
+    with open(config_path) as f:
         config_dict = yaml.safe_load(f)
 
     config = AppConfig(**config_dict)
-    return config
+    return config