ExcelAlchemy 2.0.0rc1__tar.gz → 2.2.2__tar.gz

excelalchemy-2.2.2/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: ExcelAlchemy
+Version: 2.2.2
+Summary: Schema-driven Python library for typed Excel import/export workflows with Pydantic and locale-aware workbooks.
+Keywords: excel,openpyxl,pydantic,minio,schema
+Author: Ray
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+License-File: LICENSE
+Requires-Dist: pydantic[email] >=2.12, <3
+Requires-Dist: openpyxl >=3.1.5, <4
+Requires-Dist: pendulum >=3.2.0, <4
+Requires-Dist: minio >=7.2.20, <8 ; extra == "development"
+Requires-Dist: pre-commit ; extra == "development"
+Requires-Dist: pyright==1.1.408 ; extra == "development"
+Requires-Dist: pytest ; extra == "development"
+Requires-Dist: coverage ; extra == "development"
+Requires-Dist: pytest-cov ; extra == "development"
+Requires-Dist: ruff ; extra == "development"
+Requires-Dist: minio >=7.2.20, <8 ; extra == "minio"
+Project-URL: Documentation, https://github.com/RayCarterLab/ExcelAlchemy#readme
+Project-URL: Home, https://github.com/RayCarterLab/ExcelAlchemy
+Project-URL: Issues, https://github.com/RayCarterLab/ExcelAlchemy/issues
+Project-URL: Repository, https://github.com/RayCarterLab/ExcelAlchemy
+Provides-Extra: development
+Provides-Extra: minio
+
+# 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)
+

excelalchemy-2.2.2/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)

excelalchemy-2.2.2/pyproject.toml

@@ -0,0 +1,155 @@
+[build-system]
+requires = ['flit_core >=3.12,<4']
+build-backend = 'flit_core.buildapi'
+
+[project]
+name = 'ExcelAlchemy'
+description = 'Schema-driven Python library for typed Excel import/export workflows with Pydantic and locale-aware workbooks.'
+authors = [{ name = 'Ray' }]
+readme = { file = 'README-pypi.md', content-type = 'text/markdown' }
+license = { file = 'LICENSE' }
+keywords = ['excel', 'openpyxl', 'pydantic', 'minio', 'schema']
+classifiers = [
+    'Development Status :: 5 - Production/Stable',
+    'Intended Audience :: Developers',
+    'License :: OSI Approved :: MIT License',
+    'Operating System :: OS Independent',
+    'Programming Language :: Python',
+    'Programming Language :: Python :: 3',
+    'Programming Language :: Python :: 3 :: Only',
+    'Programming Language :: Python :: 3.12',
+    'Programming Language :: Python :: 3.13',
+    'Programming Language :: Python :: 3.14',
+    'Topic :: Office/Business :: Financial :: Spreadsheet',
+    'Topic :: Software Development :: Libraries :: Python Modules',
+]
+dynamic = ['version']
+requires-python = '>=3.12'
+dependencies = [
+    'pydantic[email] >=2.12, <3',
+    'openpyxl >=3.1.5, <4',
+    'pendulum >=3.2.0, <4',
+]
+
+[tool.flit.module]
+name = 'excelalchemy'
+
+[project.urls]
+Home = 'https://github.com/RayCarterLab/ExcelAlchemy'
+Repository = 'https://github.com/RayCarterLab/ExcelAlchemy'
+Documentation = 'https://github.com/RayCarterLab/ExcelAlchemy#readme'
+Issues = 'https://github.com/RayCarterLab/ExcelAlchemy/issues'
+
+[project.optional-dependencies]
+minio = [
+    'minio >=7.2.20, <8',
+]
+development = [
+    'minio >=7.2.20, <8',
+    'pre-commit',
+    'pyright==1.1.408',
+    'pytest',
+    'coverage',
+    'pytest-cov',
+    'ruff',
+]
+
+[tool.pyright]
+include = ['src/excelalchemy', 'tests']
+exclude = [
+    '.venv',
+    'venv',
+    '.git',
+    '**/.mypy_cache',
+    '**/__pycache__',
+    '**/.pytest_cache',
+    'src/excelalchemy/types/field.py',
+]
+enableTypeIgnoreComments = false
+reportAbstractUsage = false
+reportAttributeAccessIssue = false
+reportCallIssue = false
+reportPrivateImportUsage = false
+reportRedeclaration = false
+strict = [
+    'src/excelalchemy/_primitives/constants.py',
+    'src/excelalchemy/_primitives/deprecation.py',
+    'src/excelalchemy/_primitives/header_models.py',
+    'src/excelalchemy/_primitives/identity.py',
+    'src/excelalchemy/_primitives/payloads.py',
+    'src/excelalchemy/artifacts.py',
+    'src/excelalchemy/codecs/base.py',
+    'src/excelalchemy/codecs/boolean.py',
+    'src/excelalchemy/codecs/date.py',
+    'src/excelalchemy/codecs/date_range.py',
+    'src/excelalchemy/codecs/email.py',
+    'src/excelalchemy/codecs/money.py',
+    'src/excelalchemy/codecs/multi_checkbox.py',
+    'src/excelalchemy/codecs/number.py',
+    'src/excelalchemy/codecs/number_range.py',
+    'src/excelalchemy/codecs/organization.py',
+    'src/excelalchemy/codecs/phone_number.py',
+    'src/excelalchemy/codecs/radio.py',
+    'src/excelalchemy/codecs/staff.py',
+    'src/excelalchemy/codecs/string.py',
+    'src/excelalchemy/codecs/tree.py',
+    'src/excelalchemy/codecs/url.py',
+    'src/excelalchemy/config.py',
+    'src/excelalchemy/core/alchemy.py',
+    'src/excelalchemy/core/abstract.py',
+    'src/excelalchemy/core/executor.py',
+    'src/excelalchemy/core/rendering.py',
+    'src/excelalchemy/core/schema.py',
+    'src/excelalchemy/core/storage.py',
+    'src/excelalchemy/core/storage_minio.py',
+    'src/excelalchemy/core/storage_protocol.py',
+    'src/excelalchemy/core/table.py',
+    'src/excelalchemy/core/writer.py',
+    'src/excelalchemy/exceptions.py',
+    'src/excelalchemy/core/headers.py',
+    'src/excelalchemy/core/rows.py',
+    'src/excelalchemy/helper/pydantic.py',
+    'src/excelalchemy/i18n/messages.py',
+    'src/excelalchemy/metadata.py',
+    'src/excelalchemy/results.py',
+    'src/excelalchemy/util/convertor.py',
+    'src/excelalchemy/util/file.py',
+]
+typeCheckingMode = 'basic'
+
+[tool.ruff]
+line-length = 120
+target-version = 'py312'
+src = ['src', 'tests']
+extend-exclude = ['files']
+
+[tool.ruff.lint]
+select = ['E', 'F', 'I', 'UP', 'B', 'SIM', 'C4', 'RUF', 'PERF']
+ignore = ['E501', 'RUF001', 'RUF002', 'RUF003']
+
+[tool.ruff.lint.per-file-ignores]
+'**/__init__.py' = ['F401']
+'src/excelalchemy/const.py' = ['RUF100']
+'src/excelalchemy/exc.py' = ['E402', 'RUF100']
+'src/excelalchemy/header_models.py' = ['E402', 'RUF100']
+'src/excelalchemy/identity.py' = ['E402', 'RUF100']
+'src/excelalchemy/types/*.py' = ['E402', 'RUF100']
+'src/excelalchemy/types/**/*.py' = ['E402', 'RUF100']
+
+[tool.ruff.format]
+quote-style = 'preserve'
+indent-style = 'space'
+line-ending = 'auto'
+
+[tool.pytest.ini_options]
+addopts = ['--import-mode=importlib']
+testpaths = ['tests']
+
+[tool.coverage.run]
+branch = true
+source = ['excelalchemy']
+
+[tool.coverage.report]
+fail_under = 85
+skip_covered = true
+show_missing = true

excelalchemy-2.2.2/src/excelalchemy/__init__.py

@@ -0,0 +1,126 @@
+"""A Python Library for Reading and Writing Excel Files"""
+
+__version__ = '2.2.2'
+from excelalchemy._primitives.constants import CharacterSet, DataRangeOption, DateFormat, Option
+from excelalchemy._primitives.deprecation import ExcelAlchemyDeprecationWarning
+from excelalchemy._primitives.identity import (
+    Base64Str,
+    ColumnIndex,
+    DataUrlStr,
+    Key,
+    Label,
+    OptionId,
+    RowIndex,
+    UniqueKey,
+    UniqueLabel,
+    UrlStr,
+)
+from excelalchemy.artifacts import ExcelArtifact
+from excelalchemy.codecs.base import CompositeExcelFieldCodec, ExcelFieldCodec
+from excelalchemy.codecs.boolean import Boolean, BooleanCodec
+from excelalchemy.codecs.date import Date, DateCodec
+from excelalchemy.codecs.date_range import DateRange, DateRangeCodec
+from excelalchemy.codecs.email import Email, EmailCodec
+from excelalchemy.codecs.money import Money, MoneyCodec
+from excelalchemy.codecs.multi_checkbox import MultiCheckbox, MultiChoiceCodec
+from excelalchemy.codecs.number import Number, NumberCodec
+from excelalchemy.codecs.number_range import NumberRange, NumberRangeCodec
+from excelalchemy.codecs.organization import (
+    MultiOrganization,
+    MultiOrganizationCodec,
+    SingleOrganization,
+    SingleOrganizationCodec,
+)
+from excelalchemy.codecs.phone_number import PhoneNumber, PhoneNumberCodec
+from excelalchemy.codecs.radio import Radio, SingleChoiceCodec
+from excelalchemy.codecs.staff import MultiStaff, MultiStaffCodec, SingleStaff, SingleStaffCodec
+from excelalchemy.codecs.string import String, StringCodec
+from excelalchemy.codecs.tree import (
+    MultiTreeNode,
+    MultiTreeNodeCodec,
+    SingleTreeNode,
+    SingleTreeNodeCodec,
+)
+from excelalchemy.codecs.url import Url, UrlCodec
+from excelalchemy.config import ExporterConfig, ImporterConfig, ImportMode
+from excelalchemy.core.alchemy import ExcelAlchemy
+from excelalchemy.core.storage_protocol import ExcelStorage
+from excelalchemy.exceptions import ConfigError, ExcelCellError, ExcelRowError, ProgrammaticError
+from excelalchemy.helper.pydantic import extract_pydantic_model
+from excelalchemy.metadata import ExcelMeta, FieldMeta, PatchFieldMeta
+from excelalchemy.results import ImportResult, ValidateHeaderResult, ValidateResult, ValidateRowResult
+from excelalchemy.util.file import flatten
+
+__all__ = [
+    'Base64Str',
+    'Boolean',
+    'BooleanCodec',
+    'ColumnIndex',
+    'CompositeExcelFieldCodec',
+    'ConfigError',
+    'DataRangeOption',
+    'DataUrlStr',
+    'Date',
+    'DateCodec',
+    'DateFormat',
+    'DateRange',
+    'DateRangeCodec',
+    'Email',
+    'EmailCodec',
+    'ExcelAlchemy',
+    'ExcelAlchemyDeprecationWarning',
+    'ExcelArtifact',
+    'ExcelCellError',
+    'ExcelFieldCodec',
+    'ExcelMeta',
+    'ExcelRowError',
+    'ExcelStorage',
+    'ExporterConfig',
+    'FieldMeta',
+    'ImportMode',
+    'ImportResult',
+    'ImporterConfig',
+    'Key',
+    'Label',
+    'Money',
+    'MoneyCodec',
+    'MultiCheckbox',
+    'MultiChoiceCodec',
+    'MultiOrganization',
+    'MultiOrganizationCodec',
+    'MultiStaff',
+    'MultiStaffCodec',
+    'MultiTreeNode',
+    'MultiTreeNodeCodec',
+    'Number',
+    'NumberCodec',
+    'NumberRange',
+    'NumberRangeCodec',
+    'Option',
+    'OptionId',
+    'PatchFieldMeta',
+    'PhoneNumber',
+    'PhoneNumberCodec',
+    'ProgrammaticError',
+    'Radio',
+    'RowIndex',
+    'SingleChoiceCodec',
+    'SingleOrganization',
+    'SingleOrganizationCodec',
+    'SingleStaff',
+    'SingleStaffCodec',
+    'SingleTreeNode',
+    'SingleTreeNodeCodec',
+    'String',
+    'StringCodec',
+    'UniqueKey',
+    'UniqueLabel',
+    'Url',
+    'UrlCodec',
+    'UrlStr',
+    'ValidateHeaderResult',
+    'ValidateResult',
+    'ValidateRowResult',
+    'extract_pydantic_model',
+    'flatten',
+]

excelalchemy-2.2.2/src/excelalchemy/_primitives/__init__.py

@@ -0,0 +1 @@
+"""Private primitive building blocks used by ExcelAlchemy internals."""

excelalchemy-2.0.0rc1/src/excelalchemy/const.py → excelalchemy-2.2.2/src/excelalchemy/_primitives/constants.py

@@ -1,24 +1,24 @@
 from dataclasses import dataclass
-from enum import Enum
+from enum import StrEnum
 from typing import Any
 
+from excelalchemy._primitives.identity import Key, Label, OptionId
 from excelalchemy.i18n.messages import MessageKey
 from excelalchemy.i18n.messages import display_message as dmsg
-from excelalchemy.types.identity import Key, Label, OptionId
 
 HEADER_HINT = dmsg(MessageKey.HEADER_HINT, locale='zh-CN')
 
 EXCEL_COMMENT_FORMAT = {'height': 100, 'width': 300, 'font_size': 7}
 CHARACTER_WIDTH = 1.3
 DEFAULT_SHEET_NAME = 'Sheet1'
-# 连接符
+# Connector used when flattening merged workbook headers.
 UNIQUE_HEADER_CONNECTOR: str = '·'
 
-# 数据导出结果列
+# Result workbook status column.
 RESULT_COLUMN_LABEL: Label = Label(dmsg(MessageKey.RESULT_COLUMN_LABEL, locale='zh-CN'))
 RESULT_COLUMN_KEY: Key = Key('__result__')
 
-# 数据导出原因列
+# Result workbook reason column.
 REASON_COLUMN_LABEL: Label = Label(dmsg(MessageKey.REASON_COLUMN_LABEL, locale='zh-CN'))
 REASON_COLUMN_KEY: Key = Key('__reason__')
 
@@ -26,15 +26,15 @@ BACKGROUND_REQUIRED_COLOR = 'FDAFB5'
 BACKGROUND_ERROR_COLOR = 'FEC100'
 FONT_READ_COLOR = 'FF0000'
 
-# 多选分隔符
+# Display separator used for multi-choice workbook cells.
 MULTI_CHECKBOX_SEPARATOR = '，'
 
 FIELD_DATA_KEY = Key('fieldData')
 
-# 毫秒转换为秒
+# Millisecond to second conversion factor.
 MILLISECOND_TO_SECOND = 1000
 
-# options 最多允许的选项数量
+# Soft option-count limit used for warning logs.
 MAX_OPTIONS_COUNT = 100
 
 DEFAULT_FIELD_META_ORDER = -1
@@ -45,7 +45,7 @@ type ListStr = list[str]
 type IntStr = int | str
 
 
-class CharacterSet(str, Enum):
+class CharacterSet(StrEnum):
     CHINESE = 'CHINESE'
     NUMBER = 'NUMBER'
     LOWERCASE_LETTERS = 'LOWERCASE_LETTERS'
@@ -53,14 +53,14 @@ class CharacterSet(str, Enum):
     SPECIAL_SYMBOLS = 'SPECIAL_SYMBOLS'
 
 
-class DateFormat(str, Enum):
+class DateFormat(StrEnum):
     YEAR = 'YEAR'
     MONTH = 'MONTH'
     DAY = 'DAY'
     MINUTE = 'MINUTE'
 
 
-class DataRangeOption(str, Enum):
+class DataRangeOption(StrEnum):
     NONE = 'NONE'
     PRE = 'PRE'
     NEXT = 'NEXT'

excelalchemy-2.2.2/src/excelalchemy/_primitives/deprecation.py

@@ -0,0 +1,22 @@
+"""Deprecation helpers for public compatibility layers."""
+
+from __future__ import annotations
+
+import warnings
+
+DEPRECATION_REMOVAL_VERSION = '3.0'
+
+
+class ExcelAlchemyDeprecationWarning(FutureWarning):
+    """Warning emitted for deprecated public APIs that still have a compatibility shim."""
+
+
+def warn_compat_import(import_path: str, replacement: str) -> None:
+    warnings.warn(
+        (
+            f'`{import_path}` is deprecated and will be removed in ExcelAlchemy '
+            f'{DEPRECATION_REMOVAL_VERSION}. Import from `{replacement}` instead.'
+        ),
+        category=ExcelAlchemyDeprecationWarning,
+        stacklevel=2,
+    )

excelalchemy-2.2.2/src/excelalchemy/_primitives/header_models.py

@@ -0,0 +1,27 @@
+"""Internal workbook header models."""
+
+from pydantic import BaseModel
+from pydantic.fields import Field
+
+from excelalchemy._primitives.constants import UNIQUE_HEADER_CONNECTOR
+from excelalchemy._primitives.identity import Label, UniqueLabel
+
+
+class ExcelHeader(BaseModel):
+    """Normalized workbook header extracted from user input."""
+
+    label: Label = Field(description='Workbook header label.')
+    parent_label: Label = Field(
+        description='Parent workbook header label. Falls back to the label itself for flat headers.'
+    )
+    offset: int = Field(default=0, description='Child-column offset under a merged parent header.')
+
+    @property
+    def unique_label(self) -> UniqueLabel:
+        """Return the fully qualified workbook header label."""
+        label = (
+            f'{self.parent_label}{UNIQUE_HEADER_CONNECTOR}{self.label}'
+            if self.parent_label != self.label
+            else self.label
+        )
+        return UniqueLabel(label)

{excelalchemy-2.0.0rc1/src/excelalchemy/types → excelalchemy-2.2.2/src/excelalchemy/_primitives}/identity.py

@@ -1,4 +1,4 @@
-"""定义了一些用于标识的类型"""
+"""Internal typed primitives used across the ExcelAlchemy core layer."""
 
 from typing import Any
 
@@ -27,36 +27,40 @@ class _IntegerIdentity(int):
 
 
 class Label(_StringIdentity):
-    """Excel 的列名"""
+    """Workbook header label."""
 
 
 class UniqueLabel(Label):
-    """Excel 唯一的列名"""
+    """Fully qualified workbook header label."""
 
 
 class Key(_StringIdentity):
-    """Python 模型的键名"""
+    """Schema key used by the Python model."""
 
 
 class UniqueKey(Key):
-    """Python 模型唯一的键名"""
+    """Fully qualified schema key."""
 
 
 class RowIndex(_IntegerIdentity):
-    """Excel 的行索引, 从 0 开始"""
+    """Zero-based workbook row index."""
 
 
 class ColumnIndex(_IntegerIdentity):
-    """Excel 的列索引, 从 0 开始"""
+    """Zero-based workbook column index."""
 
 
 class OptionId(_StringIdentity):
-    """选项 ID"""
+    """Selection option identifier."""
 
 
-class Base64Str(_StringIdentity):
-    """Base64 编码的字符串"""
+class DataUrlStr(_StringIdentity):
+    """Data URL string."""
+
+
+class Base64Str(DataUrlStr):
+    """Deprecated compatibility alias for the legacy data URL string return type."""
 
 
 class UrlStr(_StringIdentity):
-    """URL 字符串"""
+    """Generic URL string."""