fix(python): include JAR and license files in sdist for conda-forge

Objective: conda-forge packagers must bundle Maven + OpenJDK as
build-time dependencies because PyPI only ships a wheel — there is
no sdist with the pre-compiled JAR they can build from. Attempting
to produce one silently fails: hatch drops gitignored files (JAR,
LICENSE, NOTICE, THIRD_PARTY) from the sdist even when they are
listed in 'include', yielding a 32KB tarball that installs but is
missing the CLI it wraps.

Approach: Promote 'artifacts' to top-level [tool.hatch.build] so
both wheel and sdist force-include the gitignored build outputs.
Drop '--wheel' from build-python.sh so 'uv build' produces both
artifacts. Add verify-python-sdist.sh as a standalone check that
runs inside build-python.sh and can also be run locally — this
guards against silent regressions if .gitignore or hatch config
drifts in future. README.md is copied by build-python.sh before
'uv build' because hatchling validates [project.readme] during
metadata parsing, which runs before build hooks.

Evidence: Built from a fresh clean checkout (no prior artifacts
in the package dir) and installed the resulting sdist in a fresh
venv.

| Scenario | Expected | Actual |
|----------|----------|--------|
| uv build on clean checkout | sdist + wheel | 21MB sdist + 21MB wheel |
| sdist contains JAR | yes | yes (tar -tzf confirmed) |
| sdist contains LICENSE/NOTICE/THIRD_PARTY | yes | yes |
| verify-python-sdist.sh | pass | "OK: sdist contains all required files" |
| verify-python-sdist.sh with multiple tarballs | fail with list | fails cleanly |
| pip install from sdist | no mvn call | wheel built in ~1s, mvn not invoked |
| JAR in site-packages | yes | 23MB at .../jar/opendataloader-pdf-cli.jar |
| import opendataloader_pdf | success | success |

Fixes #435

Author: bundolee

python/opendataloader-pdf/hatch_build.py

@@ -19,7 +19,11 @@ def initialize(self, version, build_data):
 
         readme_path = root_dir / "README.md"
 
-        # Check if all required files already exist (building from sdist)
+        # sdist-install code path: when users `pip install <sdist>.tar.gz`,
+        # the extracted sdist already contains JAR/LICENSE/NOTICE/THIRD_PARTY
+        # (force-included via [tool.hatch.build] artifacts in pyproject.toml),
+        # and there is no java/ tree to rebuild from. Do not remove — sdist
+        # installs would break with a spurious "mvn package" error.
         if (
             dest_jar_path.exists()
             and license_path.exists()
@@ -52,10 +56,12 @@ def initialize(self, version, build_data):
         print(f"Copying JAR to {dest_jar_path}")
         shutil.copy(source_jar_path, dest_jar_path)
 
-        # --- Copy LICENSE, NOTICE, README ---
+        # --- Copy LICENSE, NOTICE ---
+        # README is copied by build-python.sh before this hook runs, because
+        # hatchling validates [project.readme] during metadata parsing, which
+        # happens before build hooks. Do not copy README here.
         shutil.copy(root_dir / "../../LICENSE", license_path)
         shutil.copy(root_dir / "../../NOTICE", notice_path)
-        shutil.copy(root_dir / "../../README.md", readme_path)
         third_party_src = root_dir / "../../THIRD_PARTY"
         print(f"Copying THIRD_PARTY directory to {third_party_dest}")
         if third_party_dest.exists():

python/opendataloader-pdf/pyproject.toml

@@ -33,15 +33,19 @@ Homepage = "https://github.com/opendataloader-project/opendataloader-pdf"
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
-[tool.hatch.build.targets.wheel]
-packages = ["src/opendataloader_pdf"]
+# Shared by wheel and sdist: force-include gitignored build outputs
+# (JAR, LICENSE, NOTICE, THIRD_PARTY) that hatch_build.py copies at build time.
+[tool.hatch.build]
 artifacts = [
     "src/opendataloader_pdf/jar/*.jar",
     "src/opendataloader_pdf/LICENSE",
     "src/opendataloader_pdf/NOTICE",
     "src/opendataloader_pdf/THIRD_PARTY/**",
 ]
 
+[tool.hatch.build.targets.wheel]
+packages = ["src/opendataloader_pdf"]
+
 [tool.hatch.build.targets.sdist]
 include = [
     "src/opendataloader_pdf/**",

scripts/build-python.sh

@@ -16,11 +16,18 @@ command -v uv >/dev/null || { echo "Error: uv not found. Install with: curl -LsS
 # Clean previous build
 rm -rf dist/
 
-# Copy README.md from root (gitignored in package dir)
+# Copy README.md from repo root *before* build. hatchling validates [project.readme]
+# during metadata parsing, which runs BEFORE hatch_build.py's build hook — so we
+# cannot rely on the hook to provide it. Clean up on exit so branch switches
+# don't leave a stale copy in the package dir.
 cp "$ROOT_DIR/README.md" "$PACKAGE_DIR/README.md"
+trap 'rm -f "$PACKAGE_DIR/README.md"' EXIT
 
-# Build wheel package
-uv build --wheel
+# Build sdist and wheel packages (hatch_build.py copies JAR/LICENSE/NOTICE/THIRD_PARTY)
+uv build
+
+# Verify sdist contains required artifacts (JAR, LICENSE, NOTICE, THIRD_PARTY)
+"$SCRIPT_DIR/verify-python-sdist.sh"
 
 # Install and run tests (include hybrid extras for full test coverage)
 uv sync --extra hybrid

scripts/verify-python-sdist.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+
+# Verify the Python sdist contains all required files (JAR, LICENSE, etc).
+# The files listed below are gitignored in the package dir and only exist in
+# the dist because [tool.hatch.build] artifacts force-includes them. This
+# script guards against silent regressions if that config ever drifts.
+#
+# Usage: ./scripts/verify-python-sdist.sh
+# Prerequisite: run 'uv build' (or scripts/build-python.sh) first.
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT_DIR="$SCRIPT_DIR/.."
+DIST_DIR="$ROOT_DIR/python/opendataloader-pdf/dist"
+
+shopt -s nullglob
+SDIST_CANDIDATES=("$DIST_DIR"/*.tar.gz)
+shopt -u nullglob
+
+if [ ${#SDIST_CANDIDATES[@]} -eq 0 ]; then
+  echo "Error: no sdist found in $DIST_DIR. Run 'uv build' first." >&2
+  exit 1
+fi
+if [ ${#SDIST_CANDIDATES[@]} -gt 1 ]; then
+  echo "Error: multiple sdists found in $DIST_DIR. Remove stale ones first:" >&2
+  printf '  - %s\n' "${SDIST_CANDIDATES[@]}" >&2
+  exit 1
+fi
+SDIST="${SDIST_CANDIDATES[0]}"
+
+echo "Verifying sdist: $(basename "$SDIST")"
+
+REQUIRED=(
+  "jar/opendataloader-pdf-cli.jar"
+  "LICENSE"
+  "NOTICE"
+  "THIRD_PARTY/"
+)
+
+CONTENTS=$(tar -tzf "$SDIST")
+MISSING=()
+for path in "${REQUIRED[@]}"; do
+  # Directory prefixes (trailing '/') match any entry under that prefix.
+  # File paths are anchored to end-of-line so "LICENSE" does not match "LICENSE.bak".
+  # (^|/) prefix keeps the check layout-tolerant if hatchling ever emits
+  # a differently-rooted sdist (e.g., without the top-level pkgname-version/ dir).
+  if [[ "$path" == */ ]]; then
+    pattern="(^|/)src/opendataloader_pdf/${path}"
+  else
+    pattern="(^|/)src/opendataloader_pdf/${path}\$"
+  fi
+  if ! echo "$CONTENTS" | grep -qE "$pattern"; then
+    MISSING+=("$path")
+  fi
+done
+
+if [ ${#MISSING[@]} -gt 0 ]; then
+  echo "Error: sdist is missing required files:" >&2
+  printf '  - src/opendataloader_pdf/%s\n' "${MISSING[@]}" >&2
+  echo "" >&2
+  echo "Fix: ensure [tool.hatch.build] in pyproject.toml lists these under 'artifacts'." >&2
+  echo "(They are gitignored, so hatch drops them unless force-included.)" >&2
+  exit 1
+fi
+
+echo "OK: sdist contains all required files."