Metadata-Version: 2.4
Name: excel-funcs-py
Version: 0.1.0
Summary: Python implementations of common Microsoft Excel functions, layered API and Excel-like error values.
Project-URL: Homepage, https://github.com/your-org/PyExcelFunctionsImpl
Project-URL: Documentation, https://github.com/your-org/PyExcelFunctionsImpl#readme
Project-URL: Repository, https://github.com/your-org/PyExcelFunctionsImpl
Project-URL: Issues, https://github.com/your-org/PyExcelFunctionsImpl/issues
Author: PyExcelFunctionsImpl contributors
License-Expression: MIT
License-File: LICENSE
Keywords: excel,formula,functions,office,spreadsheet
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
Classifier: Typing :: Typed
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: numpy
Requires-Dist: numpy>=1.24.0; extra == 'numpy'
Description-Content-Type: text/markdown

# PyExcelFunctionsImpl / excel-funcs-py

在 Python 中复现常用 **Microsoft Excel 工作表函数** 的行为，提供三层 API：**纯函数（Layer 1）**、**按功能区分类的 Facade（Layer 2）**、**统一入口 `ExcelFunctions`（Layer 3）**。

## 安装

```bash
cd PyExcelFunctionsImpl
pip install -e .
```

仅开发依赖：

```bash
pip install -e ".[dev]"
```

## 快速开始

```python
from excel_funcs import ExcelFunctions, SUM, IF

# 函数式（与 Excel 名称对应的大写别名，见 __init__.py）
print(SUM(1, 2, 3, [4, 5]))  # 15.0
print(IF(True, "yes", "no"))
# 文本转数字请用 VALUE_FROM_TEXT（与错误常量 VALUE 区分）
from excel_funcs import VALUE_FROM_TEXT
print(VALUE_FROM_TEXT("123.45"))

# 分层入口（IDE 友好）
xf = ExcelFunctions()
print(xf.math.sum(1, 2, 3))
print(xf.logical.if_(True, "A", "B"))
```

命令行小演示：

```bash
python -m excel_funcs
```

## 与 Microsoft Excel 的差异（重要）

| 主题 | 说明 |
|------|------|
| 单元格与区域 | Python 使用 `list`、`tuple` 或嵌套列表表示区域；空单元格请显式传 `None` 或 `""`（视函数而定）。 |
| 日期 | 默认使用 `datetime.date` / `datetime.datetime`；部分函数支持 Excel 序列号需查看各函数文档。 |
| 错误值 | `#N/A`、`#VALUE!` 等以不可变对象 `ExcelErrorValue` 表示，可用 `ISERROR` / `ISNA` 判断；与 Excel 完全一致的边缘情况仍在迭代中。 |
| 数组公式 / 动态数组 | `UNIQUE`、`SORT`、`FILTER` 等提供基于列表的简化实现；复杂溢出行为与 Excel 365 可能不同。 |
| 本地化 | 小数点、参数分隔符等以 Python 语法为准，不模拟区域格式。 |

完整函数清单与实现状态见 [docs/function-list.md](docs/function-list.md)。

## 发布到 PyPI

1. 在 [PyPI](https://pypi.org) 搜索并确认发行名 **`excel-funcs-py`**（`pyproject.toml` 里 `[project] name`）未被占用；**import 包名**仍为 `excel_funcs`，二者可以不同。
2. 安装构建工具：`pip install build twine`
3. 构建：`python -m build`
4. 检查：`twine check dist/*`
5. 上传测试索引（可选）：`twine upload --repository testpypi dist/*`
6. 正式上传：`twine upload dist/*`

请使用 **API token** 或可信凭据，切勿将 token 写入仓库。

## 项目布局

```
PyExcelFunctionsImpl/
  src/excel_funcs/   # 可导入包 excel_funcs
  docs/              # 函数列表与设计说明
  tests/             # pytest
```

## 许可证

MIT，见 [LICENSE](LICENSE)。
