Metadata-Version: 2.4
Name: hlvv
Version: 0.1.0
Summary: A little love letter and a beginner-friendly Python learning companion.
Keywords: python,learning,birthday,love
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Education
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# hlvv

藏在 Python 里的小情书，也是一个带中文讲解的 Python 入门工具箱。

我们的故事开始于 **2024 年 12 月 16 日**，她的生日是 **2007 年 12 月 31 日**。

## 安装

需要 Python 3.9 或更新版本，无第三方运行依赖，支持 Windows、macOS、Linux。

从 PyPI 安装：

```bash
python -m pip install hlvv
```

也可以安装构建好的 wheel 文件：

```bash
python -m pip install ./dist/hlvv-0.1.0-py3-none-any.whl
```

在源码目录中也可以安装：

```bash
python -m pip install .
```

## 开始使用

```python
import hlvv as love
from hlvv import learn

love.hello()
love.days()
love.help()

result = learn.total([1, 2, 3, 4, 5])
print(result)  # 15

learn.explain("total")
learn.practice("total")
learn.hint("total")
learn.answer("total")
```

计算函数返回结果而不自动打印，在脚本中用 `print(...)` 显示。欢迎语、讲解、练习和帮助会直接显示，同时返回文字，便于保存。

## 恋爱惊喜

| 函数 | 用途 |
| --- | --- |
| `love.hello()` | 本次 Python 会话首次显示字符爱心和完整欢迎语，之后显示随机小纸条 |
| `love.days()` | 查看已过去的天数和在一起的第几天；返回信息字典 |
| `love.birthday()` | 显示生日倒计时或当天祝福，每次打开 `https://bty.pexam.asia` |
| `love.cheer(mood=None)` | 随机鼓励，或针对指定心情显示留言 |
| `love.miss_you()` | 一封想念的小短信 |
| `love.ddays()` | 打开记录你们经历的 `https://love.pexam.asia`，返回网址 |
| `love.help(topic=None)` | 查看所有函数、分类或单个函数的详细说明 |

```python
love.cheer("报错了")
love.cheer("考试前")
love.cheer("作业太难")
love.cheer("今天好累")
love.cheer("终于写出来了")

love.birthday()  # 是否生日都打开生日网站
love.ddays()

# 不方便打开浏览器时，可只查看信息。
birthday_info = love.birthday(open_browser=False)
print(birthday_info["countdown_days"])
love.ddays(open_browser=False)
```

日期按照电脑本地日期计算，不需要手动更新年龄、倒计时或恋爱天数。恋爱开始当天算第 1 天，已过去 0 天。生日当天倒计时为 0，`age` 表示当前周岁，`celebrating_age` 表示下次生日（当天包含在内）要庆祝的年龄。

两个网站由你另行制作；包只负责显示文字并调用系统浏览器打开网址。没有自动播放的声音，也不会在导入时打开浏览器。浏览器无法自动打开时，终端会显示可直接访问的网址。

`birthday()` 返回 `today`、`next_birthday`、`countdown_days`、`age`、`celebrating_age`、`is_birthday`、`relationship_start`、`url`、`browser_opened`。其中日期是 ISO 格式字符串。

## 基础计算与算法

```python
from hlvv import learn

print(learn.total([1, 2, 3]))                  # 6
print(learn.square(-5))                       # 25
print(learn.average([80, 90, 100]))            # 90.0
print(learn.max_min([3, 8, 1]))                # (8, 1)
print(learn.sort_numbers([3, 1, 2]))           # [1, 2, 3]
print(learn.sort_numbers([3, 1, 2], reverse=True))  # [3, 2, 1]
print(learn.bubble_sort([3, 1, 2]))            # [1, 2, 3]
print(learn.factorial(5))                     # 120
print(learn.fibonacci(7))                     # [0, 1, 1, 2, 3, 5, 8]
print(learn.is_prime(17))                     # True
print(learn.linear_search([4, 7, 9], 7))       # 1
```

- 数字支持 Python 整数和有限小数；不接受字符串、布尔值、NaN 或无穷大。
- 数字集合可以使用列表、元组或生成器。两个排序函数都返回新列表，保留重复值，不修改原列表。
- 空列表求和得到 `0`，排序得到 `[]`；求平均值、最大最小值会抛出带中文说明的 `ValueError`。
- 阶乘、斐波那契接受非负整数：`factorial(0)` 是 `1`，`fibonacci(0)` 是 `[]`。
- `fibonacci(n)` 的 `n` 是项数，不是某个数值的上限。
- `is_prime(n)` 接受整数，小于 2 都返回 `False`。
- 顺序查找返回第一次出现的下标，从 0 开始；找不到返回 `-1`。拿结果索引列表前先检查是否为 `-1`。

## 讲解与练习

所有 10 个基础函数都有独立的讲解、练习、提示和带注释参考答案。

```python
learn.explain("bubble_sort")  # 展示包内实际运行的源码、逐步解释和注意事项
learn.practice("bubble_sort")
learn.hint("bubble_sort")
learn.answer("bubble_sort")
learn.cheer("作业太难")      # 与 love.cheer 相同
```

课程名称可以写 `"total"`、`"learn.total"` 或 `"hlvv.learn.total"`。题目中的参考答案展示解题主体，按题目要求的合法输入运行；调用包内算法时还会进行参数检查。

## 帮助

```python
love.help()                      # 全部 22 个函数入口，包含用途和使用示例
love.help("love")                # 恋爱功能
love.help("learn")               # 学习功能
love.help("learn.bubble_sort")    # 参数、默认值、返回值、示例与注意事项
love.help("birthday")            # 单个恋爱函数
love.help("total")               # 可以省略 learn. 前缀
```

## 开发验证与打包

```bash
python -m pip install -e .
python -m unittest discover -s tests -v
python -m pip install build
python -m build
```

构建产物位于 `dist/`。安装 wheel 后直接使用 `import hlvv`，不需要源码目录。
