diff --git a/.github/workflows/python-publish.yml b/.github/workflows/python-publish.yml index 1bf25e7..9e9c397 100644 --- a/.github/workflows/python-publish.yml +++ b/.github/workflows/python-publish.yml @@ -34,7 +34,9 @@ jobs: uv.lock - name: Build package - run: uv build + run: | + rm -rf dist + uv build - name: Check package metadata run: uvx twine check dist/* diff --git a/CHANGELOG.md b/CHANGELOG.md index 4e313b2..d933256 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,18 @@ All notable changes to this project will be documented in this file. The format is inspired by Keep a Changelog and versioned according to PEP 440. +## [2.0.0.post1] - 2026-03-28 + +This post-release updates the package presentation and release metadata for the +stable ExcelAlchemy 2.0 line without changing the core import/export behavior. + +### Changed + +- Added a dedicated PyPI-friendly long description via `README-pypi.md` +- Switched package metadata to use the PyPI-specific README +- Replaced relative README assets with PyPI-safe absolute image and document links +- Tuned Codecov status behavior for large release PRs and compatibility shim files + ## [2.0.0] - 2026-03-28 This release promotes the validated 2.0 release candidate to the first stable public diff --git a/README-pypi.md b/README-pypi.md new file mode 100644 index 0000000..f8ec226 --- /dev/null +++ b/README-pypi.md @@ -0,0 +1,91 @@ +# ExcelAlchemy + +Schema-driven Python library for typed Excel import/export workflows with Pydantic and locale-aware workbooks. + +ExcelAlchemy turns Pydantic models into typed workbook contracts: + +- generate Excel templates from code +- validate uploaded workbooks +- map failures back to rows and cells +- render workbook-facing output in `zh-CN` or `en` +- keep storage pluggable through `ExcelStorage` + +[GitHub Repository](https://github.com/RayCarterLab/ExcelAlchemy) · [Full README](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/README.md) · [Architecture](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/architecture.md) · [Migration Notes](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/MIGRATIONS.md) + +## Screenshots + +### Template + +![Excel template screenshot](https://raw.githubusercontent.com/RayCarterLab/ExcelAlchemy/main/images/portfolio-template-en.png) + +### Import Result + +![Excel import result screenshot](https://raw.githubusercontent.com/RayCarterLab/ExcelAlchemy/main/images/portfolio-import-result-en.png) + +## Install + +```bash +pip install ExcelAlchemy +``` + +Optional Minio support: + +```bash +pip install "ExcelAlchemy[minio]" +``` + +## Minimal Example + +```python +from pydantic import BaseModel + +from excelalchemy import ExcelAlchemy, FieldMeta, ImporterConfig, Number, String + + +class Importer(BaseModel): + age: Number = FieldMeta(label='Age', order=1) + name: String = FieldMeta(label='Name', order=2) + + +alchemy = ExcelAlchemy(ImporterConfig(Importer, locale='en')) +template = alchemy.download_template_artifact(filename='people-template.xlsx') + +excel_bytes = template.as_bytes() +``` + +## Modern Annotated Example + +```python +from typing import Annotated + +from pydantic import BaseModel, Field + +from excelalchemy import Email, ExcelAlchemy, ExcelMeta, ImporterConfig + + +class Importer(BaseModel): + email: Annotated[ + Email, + Field(min_length=10), + ExcelMeta(label='Email', order=1, hint='Use your work email'), + ] + + +alchemy = ExcelAlchemy(ImporterConfig(Importer, locale='en')) +template = alchemy.download_template_artifact(filename='people-template.xlsx') +``` + +## Why ExcelAlchemy + +- Pydantic v2-based schema extraction and validation +- locale-aware workbook comments and result workbooks +- pluggable storage instead of a hard-coded backend +- `openpyxl`-based runtime path without pandas +- contract tests, Ruff, and Pyright in the development workflow + +## Learn More + +- [Full project README](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/README.md) +- [Architecture notes](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/architecture.md) +- [Locale policy](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/locale.md) +- [Migration notes](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/MIGRATIONS.md) diff --git a/README.md b/README.md index 7a89458..8e91e32 100755 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ ![Lint](https://img.shields.io/badge/lint-ruff-D7FF64) ![Typing](https://img.shields.io/badge/typing-pyright-2C6BED) -[中文 README](./README_cn.md) · [About](./ABOUT.md) · [Architecture](./docs/architecture.md) · [Locale Policy](./docs/locale.md) · [Changelog](./CHANGELOG.md) · [Migration Notes](./MIGRATIONS.md) +[中文 README](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/README_cn.md) · [About](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/ABOUT.md) · [Architecture](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/architecture.md) · [Locale Policy](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/locale.md) · [Changelog](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/CHANGELOG.md) · [Migration Notes](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/MIGRATIONS.md) ExcelAlchemy is a schema-driven Python library for Excel import and export workflows. It turns Pydantic models into typed workbook contracts: generate templates, validate uploads, map failures back to rows @@ -16,7 +16,7 @@ This repository is also a design artifact. It documents a series of deliberate engineering choices: `src/` layout, Pydantic v2 migration, pandas removal, pluggable storage, `uv`-based workflows, and locale-aware workbook output. -The current stable release line is `2.0.0`, the first public stable release of ExcelAlchemy 2.0. +The current stable release line is `2.0.0.post1`, the first post-release update to the stable ExcelAlchemy 2.0 line. ## At a Glance @@ -31,7 +31,7 @@ The current stable release line is `2.0.0`, the first public stable release of E | Template | Import Result | | --- | --- | -| ![Excel template screenshot](./images/portfolio-template-en.png) | ![Excel import result screenshot](./images/portfolio-import-result-en.png) | +| ![Excel template screenshot](https://raw.githubusercontent.com/RayCarterLab/ExcelAlchemy/main/images/portfolio-template-en.png) | ![Excel import result screenshot](https://raw.githubusercontent.com/RayCarterLab/ExcelAlchemy/main/images/portfolio-import-result-en.png) | ## Minimal Example @@ -126,7 +126,7 @@ flowchart TD E --> M[Runtime Error Messages] ``` -See the full breakdown in [docs/architecture.md](./docs/architecture.md). +See the full breakdown in [docs/architecture.md](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/architecture.md). ## Workflow @@ -146,7 +146,7 @@ flowchart LR ## Design Principles This repository is guided by explicit design principles rather than accidental convenience. -The full mapping is in [ABOUT.md](./ABOUT.md); the short version is: +The full mapping is in [ABOUT.md](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/ABOUT.md); the short version is: 1. Schema first. 2. Explicit metadata over implicit conventions. @@ -182,7 +182,7 @@ pip install "ExcelAlchemy[minio]" - result workbook column titles - row validation status labels -The public locale policy is documented in [docs/locale.md](./docs/locale.md). +The public locale policy is documented in [docs/locale.md](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/locale.md). In short: - runtime exceptions are standardized in English @@ -293,7 +293,7 @@ This repository intentionally records its evolution: - i18n foundation and locale-aware workbook text These are not incidental refactors; they are the story of the codebase. -See [ABOUT.md](./ABOUT.md) for the migration rationale behind each step. +See [ABOUT.md](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/ABOUT.md) for the migration rationale behind each step. ## Pydantic v1 vs v2 @@ -306,14 +306,14 @@ The short version: | Validation integration | Deep reliance on internals | Adapter + explicit runtime validation | | Upgrade path | Brittle | Layered | -More detail is documented in [ABOUT.md](./ABOUT.md). +More detail is documented in [ABOUT.md](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/ABOUT.md). ## Docs Map -- [README.md](./README.md): product + design overview -- [README_cn.md](./README_cn.md): Chinese usage-oriented guide -- [ABOUT.md](./ABOUT.md): engineering rationale and evolution notes -- [docs/architecture.md](./docs/architecture.md): component map and boundaries +- [README.md](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/README.md): product + design overview +- [README_cn.md](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/README_cn.md): Chinese usage-oriented guide +- [ABOUT.md](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/ABOUT.md): engineering rationale and evolution notes +- [docs/architecture.md](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/docs/architecture.md): component map and boundaries ## Development @@ -330,4 +330,4 @@ uv build ## License -MIT. See [LICENSE](./LICENSE). +MIT. See [LICENSE](https://github.com/RayCarterLab/ExcelAlchemy/blob/main/LICENSE). diff --git a/README_cn.md b/README_cn.md index e59330c..054bce8 100644 --- a/README_cn.md +++ b/README_cn.md @@ -5,7 +5,7 @@ ExcelAlchemy 是一个面向 Excel 导入导出的 schema-first Python 库。 它的核心思路不是“读写表格文件”,而是“把 Excel 当成一种带约束的业务契约”。 -当前稳定发布版本是 `2.0.0`,也就是 ExcelAlchemy 2.0 的首个公开正式版。 +当前稳定发布版本是 `2.0.0.post1`,也就是 ExcelAlchemy 2.0 稳定线的首个 post-release 更新。 你用 Pydantic 模型定义结构,用 `FieldMeta` 定义 Excel 元数据,用显式的导入/导出流程去完成模板生成、数据校验、错误回写和后端集成。 diff --git a/docs/releases/2.0.0.md b/docs/releases/2.0.0.md index 42b78f3..6d5ff89 100644 --- a/docs/releases/2.0.0.md +++ b/docs/releases/2.0.0.md @@ -23,6 +23,7 @@ uv sync --extra development uv run ruff check . uv run pyright uv run pytest tests +rm -rf dist uv build uvx twine check dist/* ``` diff --git a/pyproject.toml b/pyproject.toml index 26e085e..8a0f71e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,7 +6,7 @@ build-backend = 'flit_core.buildapi' name = 'ExcelAlchemy' description = 'Schema-driven Python library for typed Excel import/export workflows with Pydantic and locale-aware workbooks.' authors = [{ name = 'Ray' }] -readme = 'README.md' +readme = { file = 'README-pypi.md', content-type = 'text/markdown' } license = { file = 'LICENSE' } keywords = ['excel', 'openpyxl', 'pydantic', 'minio', 'schema'] classifiers = [ diff --git a/src/excelalchemy/__init__.py b/src/excelalchemy/__init__.py index c727830..6a9550e 100644 --- a/src/excelalchemy/__init__.py +++ b/src/excelalchemy/__init__.py @@ -1,6 +1,6 @@ """A Python Library for Reading and Writing Excel Files""" -__version__ = '2.0.0' +__version__ = '2.0.0.post1' from excelalchemy._primitives.constants import CharacterSet, DataRangeOption, DateFormat, Option from excelalchemy._primitives.deprecation import ExcelAlchemyDeprecationWarning from excelalchemy._primitives.identity import (