release: prepare ExcelAlchemy 2.2.5

[ruicore]

Summary

This PR prepares the 2.2.5 release of ExcelAlchemy.

It continues the stable 2.x line with stronger import-failure UX, clearer documentation boundaries, stronger examples and showcase assets, and better smoke coverage for release verification.

What changed

Error UX polish

• add richer workbook-facing error access helpers through CellErrorMap and RowIssueMap
• improve error inspection with helpers such as:
  • at(...)
  • messages_at(...)
  • messages_for_row(...)
  • numbered_messages_for_row(...)
  • flatten()
  • to_dict()
• unify exception boundaries around:
  • ProgrammaticError
  • ConfigError
  • ExcelCellError
  • ExcelRowError
• improve structured error output and repr quality
• normalize common validation messages into more natural workbook-facing messages

Documentation and API guidance

• add docs/getting-started.md as the main onboarding entry point
• strengthen docs/public-api.md
• strengthen docs/examples-showcase.md
• cross-link README, PyPI README, migrations, examples, showcase, and public API docs
• clarify storage=... as the recommended 2.x backend configuration path

Examples and showcase

• expand examples with more realistic workflows:
  • employee import
  • create-or-update import
  • export workflow
  • selection-heavy forms
  • date and range fields
  • Minio configuration
  • FastAPI upload flow
• add examples/README.md with a recommended reading order
• add generated example-output assets for showcase and documentation use

Smoke and release verification

• strengthen installed-package smoke verification
• add repository example smoke coverage
• add generated-output asset smoke coverage
• keep optional dependency paths non-blocking where appropriate

Typing and internal cleanup

• continue consolidating layered metadata usage across internal consumers
• reduce low-value typing gray areas and unnecessary casts in the runtime path
• keep the public 2.x API stable while tightening internal typing boundaries

Compatibility notes

• no public import/export workflow API was removed
• storage=... remains the recommended backend integration path
• legacy built-in Minio fields remain part of the 2.x compatibility surface
• FieldMeta(...) and ExcelMeta(...) remain the stable public metadata entry points

Verification

• ./.venv/bin/ruff check .
• ./.venv/bin/uv run pyright
• ./.venv/bin/pytest -q
• ./.venv/bin/python scripts/smoke_package.py
• ./.venv/bin/python scripts/smoke_examples.py
• ./.venv/bin/python scripts/generate_example_output_assets.py

Release intent

After merge, this branch is intended to be tagged and published as:

• v2.2.5

[codecov]

Codecov Report

❌ Patch coverage is 86.51163% with 29 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.30%. Comparing base (c7c3f14) to head (cd0c9fd).
⚠️ Report is 6 commits behind head on main.

Files with missing lines	Patch %	Lines
src/excelalchemy/helper/pydantic.py	75.00%	6 Missing and 3 partials ⚠️
src/excelalchemy/exceptions.py	88.09%	4 Missing and 1 partial ⚠️
src/excelalchemy/util/file.py	75.00%	3 Missing and 1 partial ⚠️
src/excelalchemy/metadata.py	0.00%	3 Missing ⚠️
src/excelalchemy/core/alchemy.py	77.77%	2 Missing ⚠️
src/excelalchemy/core/schema.py	66.66%	1 Missing and 1 partial ⚠️
src/excelalchemy/core/writer.py	33.33%	2 Missing ⚠️
src/excelalchemy/codecs/date_range.py	50.00%	1 Missing ⚠️
src/excelalchemy/util/converter.py	50.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #65      +/-   ##
==========================================
+ Coverage   87.16%   87.30%   +0.14%     
==========================================
  Files          48       48              
  Lines        3475     3608     +133     
  Branches      379      396      +17     
==========================================
+ Hits         3029     3150     +121     
- Misses        272      281       +9     
- Partials      174      177       +3     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ec77eca822

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Gate FastAPI smoke on multipart dependency

The optional FastAPI example is treated as runnable whenever fastapi is installed, but fastapi_upload.py creates routes with UploadFile, which requires python-multipart at app setup time. In environments that have FastAPI but not python-multipart, _run_example('fastapi_upload.py') will raise during module import (app = create_app()), causing scripts/smoke_examples.py (and release smoke jobs that call it) to fail even though this path is intended to be optional/non-blocking.

Useful? React with 👍 / 👎.