fix: support core metadata 2.5 publishing (#4452)

## Summary

- refresh Python package publishing tooling
- validate distribution artifacts before upload
- support retrying publication from an existing published release tag
- advance the package version and changelog

## Validation

- workflow linting
- version and lockfile checks
- package build and metadata validation

(authored by codex)

Author: cragwolfe

.github/workflows/release.yml

@@ -4,6 +4,12 @@ on:
   release:
     types:
       - published
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Published release tag whose failed package upload should be retried
+        required: true
+        type: string
 
 permissions:
   contents: read
@@ -21,10 +27,25 @@ jobs:
     # Skip opencv wheel releases (tagged 'opencv-*') produced by the
     # build-opencv-wheels workflow - those aren't package releases and would
     # otherwise trigger a spurious PyPI publish failure.
-    if: ${{ !startsWith(github.event.release.tag_name, 'opencv-') }}
+    if: ${{ !startsWith(inputs.tag || github.event.release.tag_name, 'opencv-') }}
     runs-on: ubuntu-latest
     steps:
+      - name: Validate manual release tag
+        if: github.event_name == 'workflow_dispatch'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ inputs.tag }}
+        run: |
+          PUBLISHED_TAG=$(gh api "repos/${GITHUB_REPOSITORY}/releases/tags/${TAG}" \
+            --jq 'select(.draft == false) | .tag_name')
+          if [[ "$PUBLISHED_TAG" != "$TAG" ]]; then
+            echo "Tag '$TAG' does not identify a published GitHub release"
+            exit 1
+          fi
+
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          ref: refs/tags/${{ inputs.tag || github.event.release.tag_name }}
 
       - name: Install uv
         uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5
@@ -34,12 +55,9 @@ jobs:
       - name: Set up Python
         run: uv python install
 
-      - name: Install dependencies
-        run: uv sync --locked --only-group release --no-install-project
-
       - name: Validate version matches release tag
         env:
-          TAG: ${{ github.event.release.tag_name }}
+          TAG: ${{ inputs.tag || github.event.release.tag_name }}
         run: |
           PKG_VERSION=$(uv run --script - <<'PYEOF'
           # /// script
@@ -59,12 +77,21 @@ jobs:
         id: build
         run: uv build
 
+      - name: Validate artifact
+        id: validate
+        run: uvx --from twine==7.0.0 twine check dist/*
+
       - name: Publish package
-        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # release/v1
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          skip-existing: ${{ github.event_name == 'workflow_dispatch' }}
 
-      # Best-effort: attempt Azure upload even if PyPI fails, but only if build succeeded.
+      # Best-effort: attempt Azure upload even if PyPI fails, but only for a valid artifact.
       - name: Create .pypirc for Azure Artifacts
-        if: always() && steps.build.outcome == 'success'
+        if: >-
+          always() &&
+          steps.build.outcome == 'success' &&
+          steps.validate.outcome == 'success'
         run: |
           cat <<EOF > ~/.pypirc
           [distutils]
@@ -78,10 +105,13 @@ jobs:
           EOF
 
       - name: Publish package to Azure Artifacts
-        if: always() && steps.build.outcome == 'success'
+        if: >-
+          always() &&
+          steps.build.outcome == 'success' &&
+          steps.validate.outcome == 'success'
         run: |
           EXIT_CODE=0
-          uv run --no-sync twine upload -r azure dist/* || EXIT_CODE=$?
+          uvx --from twine==7.0.0 twine upload -r azure dist/* || EXIT_CODE=$?
           if [[ $EXIT_CODE -eq 0 ]]; then
             echo "Successfully published to Azure Artifacts (or already existed)"
           else

CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.27.1
+
+### Fixes
+
+- **Support Core Metadata 2.5 package publishing**: Upgrade the PyPI publishing action and Twine release tooling so artifacts produced by Hatchling 1.32 and later pass metadata validation. Release workflows now validate artifacts before upload and can safely retry a failed upload from an existing published GitHub release tag without moving or recreating that tag.
+
 ## 0.27.0
 
 ### Enhancements

pyproject.toml

@@ -188,7 +188,7 @@ lint = [
     "ruff>=0.15.0, <1.0.0",
 ]
 release = [
-    "twine>=6.0.0, <7.0.0",
+    "twine>=7.0.0, <8.0.0",
 ]
 
 [tool.uv]

unstructured/__version__.py

@@ -1 +1 @@
-__version__ = "0.27.0"  # pragma: no cover
+__version__ = "0.27.1"  # pragma: no cover