Metadata-Version: 2.4
Name: package-test-jak
Version: 0.0.2
Summary: A test package
Author-email: John Doe <john.doe@example.com>
License-Expression: MIT
Requires-Python: >=3.14
Requires-Dist: markdown>=3.5.1
Description-Content-Type: text/markdown

# package-test

一个用于学习 Python 包结构与打包的示例项目，提供日期处理、Markdown 转换和问候语等简单工具函数。

## 项目结构

```
package-test/
├── src/
│   └── package_test/          # 主包
│       ├── __init__.py        # 包入口，汇总对外 API
│       ├── greeter.py         # 问候语
│       ├── date/              # 日期工具
│       │   └── __init__.py
│       └── markdown/          # Markdown 工具
│           └── __init__.py
├── pyproject.toml             # 项目配置（待完善）
└── README.md
```

## 环境要求

- Python 3.14+
- 依赖第三方库：[Markdown](https://python-markdown.github.io/)（`markdown` 模块使用）

## 安装

### 1. 创建并激活虚拟环境

```bash
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
```

### 2. 安装依赖

```bash
pip install markdown
```

如需打包与发布，可额外安装：

```bash
pip install build twine
```

### 3. 安装本项目

当前 `pyproject.toml` 尚未配置完成。开发阶段可临时将 `src` 加入 Python 路径：

```bash
export PYTHONPATH=src
```

配置好 `pyproject.toml` 后，可使用可编辑模式安装：

```bash
pip install -e .
```

## 快速开始

```python
import datetime
from package_test import (
    format_date,
    days_until,
    days_since,
    to_html,
    strip_markdown,
    greet,
)

# 问候
print(greet("张三"))  # 你好, 张三!

# 日期
today = datetime.date.today()
print(format_date(today))           # 2026-06-26
print(days_until(datetime.date(2026, 12, 31)))  # 距离目标日期的天数
print(days_since(datetime.date(2026, 1, 1)))  # 距今天数

# Markdown
print(to_html("**Hello**"))         # <p><strong>Hello</strong></p>
print(strip_markdown("**Hello**"))  # <strong>Hello</strong>
```

也可以按子模块导入：

```python
from package_test.date import format_date
from package_test.markdown import to_html
from package_test.greeter import greet
```

## API 参考

### `package_test.greeter`

| 函数 | 说明 |
|------|------|
| `greet(name: str) -> str` | 返回中文问候语 |

### `package_test.date`

| 函数 | 说明 |
|------|------|
| `format_date(date) -> str` | 将 `datetime.date` 格式化为 `YYYY-MM-DD` |
| `days_until(target_date) -> int` | 计算从今天到目标日期还剩多少天 |
| `days_since(target_date) -> int` | 计算从目标日期到今天已过去多少天 |

### `package_test.markdown`

| 函数 | 说明 |
|------|------|
| `to_html(text: str) -> str` | 将 Markdown 文本转换为 HTML |
| `strip_markdown(text: str) -> str` | 转换后去掉外层 `<p>` 标签 |

## 包的导出方式

`__init__.py` 通过显式导入将各子模块的函数汇总到包顶层，并用 `__all__` 声明公开 API：

```python
from .date import format_date, days_until, days_since
from .markdown import to_html, strip_markdown
from .greeter import greet

__all__ = [
    "format_date", "days_until", "days_since",
    "to_html", "strip_markdown", "greet",
]
```

因此可以直接 `from package_test import greet`，也可以使用 `from package_test import *` 导入上述全部公开函数。

## 构建与发布

完善 `pyproject.toml` 后，可执行：

```bash
# 构建分发包
python -m build

# 检查包元数据
twine check dist/*
```

## 许可证

暂未指定。
