========================================
  pyfreedom 本地安装 & PyPI 发布指南
========================================


一、本地安装（开发/测试用）
========================================

1. 直接从源码安装：

   cd ~/CODE/pyfreedom
   pip install .

2. 开发模式安装（修改代码后立即生效，无需重装）：

   cd ~/CODE/pyfreedom
   pip install -e .

3. 验证安装：

   python -c "
   import pyfreedom
   from pyfreedom.core import Session
   from pywidevine.cdm import Cdm
   import google.protobuf
   print(f'protobuf: {google.protobuf.__version__}')
   print('pyfreedom + pywidevine 共存正常')
   "

4. 从构建好的 wheel 安装：

   pip install dist/pyfreedom-0.1.0-py3-none-any.whl

注意：pyfreedom 和原版 librespot 的 import name 都是 librespot，
     不能同时安装。安装 pyfreedom 前先卸载原版：pip uninstall librespot


二、发布到 PyPI 的前置条件
========================================

1. 注册 PyPI 账号
   - 正式: https://pypi.org/account/register/
   - 测试: https://test.pypi.org/account/register/  (建议先用测试仓库验证)

2. 创建 API Token
   - 登录 PyPI → Account settings → API tokens → Add API token
   - Scope 选 "Entire account"（首次发布）或指定项目
   - 复制 token（以 pypi- 开头），只显示一次

3. 配置 ~/.pypirc（可选，免得每次输入 token）

   [distutils]
   index-servers =
       pypi
       testpypi

   [pypi]
   username = __token__
   password = pypi-你的正式token

   [testpypi]
   repository = https://test.pypi.org/legacy/
   username = __token__
   password = pypi-你的测试token

4. 安装构建工具

   pip install build twine


三、构建
========================================

   cd ~/CODE/pyfreedom

   # 清理旧构建
   rm -rf dist/ build/ *.egg-info

   # 构建 wheel + sdist
   python -m build

   # 检查包格式
   twine check dist/*

   输出：
     dist/pyfreedom-0.1.0-py3-none-any.whl   (wheel, 安装用)
     dist/pyfreedom-0.1.0.tar.gz              (sdist, 源码备份)

   也可以直接运行：
   bash build.sh


四、发布
========================================

1. 先发到 TestPyPI 验证：

   twine upload --repository testpypi dist/*

   验证安装：
   pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ pyfreedom

2. 确认无误后发到正式 PyPI：

   twine upload dist/*

3. 验证正式发布：

   pip install pyfreedom


五、版本更新流程
========================================

1. 修改 pyproject.toml 中的 version（如 0.1.0 → 0.1.1）
2. 重新构建：python -m build
3. 上传新版本：twine upload dist/*

注意：PyPI 不允许覆盖已发布的版本号，必须递增。
     删除旧版本后也无法重用同一版本号。


六、常见问题
========================================

Q: 提示 externally-managed-environment？
A: Homebrew Python 的限制，加 --break-system-packages 或使用 venv：
   python -m venv venv && source venv/bin/activate && pip install .

Q: twine upload 报 403？
A: Token 过期或 scope 不对，重新生成 API token。

Q: 包名 pyfreedom 被占用？
A: 先到 https://pypi.org/project/pyfreedom/ 检查。
   如果被占，改 pyproject.toml 中的 name 字段。

Q: 如何让别人通过 GitHub 安装（不发 PyPI）？
A: pip install git+https://github.com/你的用户名/pyfreedom.git
