Skip to content

Latest commit

 

History

History
142 lines (121 loc) · 7.99 KB

README.md

File metadata and controls

142 lines (121 loc) · 7.99 KB

Exercises for Publishing Python Packages: Test, share, and automate your projects 🐍 📦 ⬆️

Documentation Status

Fork of 《Publishing Python Packages》book.

笔记

目录说明:

  • .github

    • issue template
    • pr template
    • contributing guideline
    • workflow files
    • dependabot.yml
  • ch05

    初具模型,基础的 tox 的使用

  • ch06

    重构解耦代码,模块化,SOLID 原则。增加 typecheck(mypy)、lint(flake8,ruff )、format(black) 、测试 hello 配置。

  • ch08/

    • 增加 sphinx 文档构建配置。默认主题 alabaster 非常简陋。** 添加自定义 sphinx-rtd-theme 主题后,注意在 cfg 文件中添加对应依赖 **。
    • 托管到 read the docs 网站。注册 read the docs 账号,可以使用 github 互联。
      1. 保证 project 根目录下存在正确配置的.readthedocs.yaml
      2. import 特定的 github project;
      3. 填写元信息,勾选 advanced setting。
      4. 填写 Project Extra Details。
    • Running sphinx-apidoc on Read the Docs。配置对应 conf.py,利用 build doc 的生命周期的 builder-inited
    • update per pull-request:
    • sphinx 出来 rst 格式,也可以通过扩展支持 markdown 格式。也可以考虑 mkdocs
    • doctest(文档驱动的测试)/pytest(用例驱动的测试)
  • ch09/

    • 关于依赖库版本和自身版本。
      • 不固定特定版本: package-a==1.0.0。
      • 限定上下界版本范围: package-a>=1.0.0,<2。
      • 限定下界: package-a>=1.0.0。
      • 不限范围: package-a。
    • 依赖库就是在寻找合适的交集。有时,会陷入依赖 diamond 地狱。参阅
    • 限制下界的意义:某个 package 在某个版本才引入某个你需要的功能,因此需要指定下界。
    • 限制上界的意义:一般是基于兼容性考虑,版本过高的库可能 API 大改,会破坏你已有的代码库。
    • 利用 github 的代码扫描服务(Code security and analysis)。
      • Dependabot alerts surface known security vulnerabilities in some dependency manifest files.
      • Dependabot security updates automatically keep your application up-to-date by updating dependencies in response to these alerts.
      • Dependabot version updates can also help keep dependencies updated.
      • Code scanning: scan your project code for vulnerabilities as well.
      • Secret scanning: scans your code for potentially leaked passwords, API keys, and so on to protect you from attackers who scrape and use the information.
  • use pre-commit hook in .pre-commit-config.yaml

    • pre-commit 一般是作用于 working --(git add)--> staged --(pre-commit 位于这里)--> commit 这个阶段。 如果文件变更还没有 staged(还没有 git add),那么 pre-commit 会先:

      • Stashing unstaged files.
      • do tasks.
      • Restore changes.

      如果文件更改都已经 git add,那么pre-commit不会执行git add,而是直接开始检测。 也就是说pre-commit检测的是working和staged 阶段的代码,这就是pre-commit的含义,保证了进入commit阶段的变更,都是经过检测的。

    • pyupgrade for python syntax up to date

    • install: pip install pre-commit

    • setup git hooks: pre-commit install => .git\hooks\pre-commit

    • manually run all pre-commit hooks on a repository: pre-commit run --all-files

    • temporarily disabling hooks: SKIP=[hook-id] prep-commit run

    • run single hook: pre-commit run [hook-id]

    • uninstall pre-commit: docs: https://pre-commit.com/#pre-commit-uninstall

  • git command:

    • git revert XXX :

      假设当前提交为意外的提交,想要撤销,可以使用 revert,但是会新增一个 commit 记录(表示撤销)。 审查需要保留撤销记录时可以使用, 其余时刻不建议使用。

    • git reset --soft vs --mixed vs --hard: https://stackoverflow.com/a/3528483

  • 让 pre-commit 通过:

    • 当 pre-commit 定义的检测范围的文件格式混乱,此时 pre-commit 或者 git commit + run hooks(例如使用 IDE 勾选框 ) 都会无限失败。
    • 使用 tox 任务执行格式化,然后重试 commit,直到通过。
    • 这里会遇到 pre-commit 中例如 black 和 flake8 的配置问题。
    • flake8: args: ['--config=ch09/first-python-package/setup.cfg', '--ignore=E303'] 可以读取配置。
    • black:
      black....................................................................Failed
      - hook id: black
      - files were modified by this hook
      
      reformatted ch08\first-python-package\docs\conf.py
      
      All done! \u2728 \U0001f370 \u2728
      1 file reformatted.
      
      [WARNING] Stashed changes conflicted with hook auto-fixes... Rolling back fixes...
      • 问题分析:black8 指定了 ch09 的配置,但是却检测了 ch08 的代码。
      • 参阅 这个问题 ,可以手动 git add 出现冲突的文件,之后再次检测。
      • 或者指定 black 排除的检测范围:在 pre-commit 中 1. 使用 exclude 排除部分文件夹。2. 使用 files 指定文件夹。
  • ch10 的项目模板生成不实用,暂缓。

alternatives

  • dev env

    • virtualenv 时代的眼泪
    • venv python 3.x 官方支持,推荐。
  • build system backend:

  • multi environments config:

    • tox => 侧重于测试。较旧,兼容hatch后端,可以迁移。
    • hatch => 侧重于构建。和hatch backend完美兼容。

migrate setuptools to hatch, migrate tox to hatch.

other enhancements