manageprojects - 管理Python / Django项目

将Ansible的概念与CookieCutter模板和Django迁移混合，以管理和更新您的Python包和Django项目...

主要思想是将CookieCutter模板的更改转移回创建的项目。manageprojects使用git创建模板更改的补丁，并将其应用到创建的项目。

除此之外，manageprojects还包括其他Python包的通用辅助工具

• publish_package() - 构建并上传到PyPi的新版本，但带有许多预检查。
• format-file - 使用Darker & Co.格式/检查Python源文件，作为IDE操作的用途。
• install_python.py - 一个文件，无依赖关系，需要时可以从官方Python FTP服务器安装Python，经过验证。
• setup_python.py - 一个文件，无依赖关系，需要时可以下载并设置可重新分发的Python。

请参阅下面的辅助部分。

文档： docs/ (WIP)

安装

目前只需克隆项目并启动cli（这将创建虚拟环境和安装所有依赖项）

例如：

~$ git clone https://github.com/jedie/manageprojects.git
~$ cd manageprojects
~/manageprojects$ ./cli.py --help

./cli.py --help的输出如下

Usage: ./cli.py [OPTIONS] COMMAND [ARGS]...

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ --help      Show this message and exit.                                                          │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────╮
│ clone-project          Clone existing project by replay the cookiecutter template in a new       │
│                        directory.                                                                │
│ format-file            Format and check the given python source code file with                   │
│                        darker/autoflake/isort/pyupgrade/autopep8/mypy etc.                       │
│ reverse                Create a cookiecutter template from a managed project.                    │
│ start-project          Start a new "managed" project via a CookieCutter Template. Note: The      │
│                        CookieCutter Template *must* be use git!                                  │
│ update-project         Update a existing project.                                                │
│ update-readme-history  Update project history base on git commits/tags in README.md              │
│ version                Print version and exit                                                    │
│ wiggle                 Run wiggle to merge *.rej in given directory.                             │
│                        https://github.com/neilbrown/wiggle                                       │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯

最重要的命令

start-project

从./cli.py start-project --help获得帮助

Usage: ./cli.py start-project [OPTIONS] TEMPLATE OUTPUT_DIR

 Start a new "managed" project via a CookieCutter Template. Note: The CookieCutter Template *must*
 be use git!
 e.g.:
 ./cli.py start-project https://github.com/jedie/cookiecutter_templates/ --directory
 piptools-python ~/foobar/

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ --directory             TEXT  Cookiecutter Option: Directory within repo that holds              │
│                               cookiecutter.json file for advanced repositories with multi        │
│                               templates in it                                                    │
│ --checkout              TEXT  Cookiecutter Option: branch, tag or commit to checkout after git   │
│                               clone                                                              │
│ --input/--no-input            Cookiecutter Option: Do not prompt for parameters and only use     │
│                               cookiecutter.json file content                                     │
│                               [default: input]                                                   │
│ --replay/--no-replay          Cookiecutter Option: Do not prompt for parameters and only use     │
│                               information entered previously                                     │
│                               [default: no-replay]                                               │
│ --password              TEXT  Cookiecutter Option: Password to use when extracting the           │
│                               repository                                                         │
│ --config-file           FILE  Cookiecutter Option: Optional path to "cookiecutter_config.yaml"   │
│ --help                        Show this message and exit.                                        │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯

update-project

从./cli.py update-project --help获得帮助

Usage: ./cli.py update-project [OPTIONS] PROJECT_PATH

 Update a existing project.
 e.g. update by overwrite (and merge changes manually via git):
 ./cli.py update-project ~/foo/bar/

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ --overwrite/--no-overwrite          Overwrite all Cookiecutter template files to the last        │
│                                     template state and do not apply the changes via git patches. │
│                                     The developer is supposed to apply the differences manually  │
│                                     via git. Will be aborted if the project git repro is not in  │
│                                     a clean state.                                               │
│                                     [default: overwrite]                                         │
│ --password                    TEXT  Cookiecutter Option: Password to use when extracting the     │
│                                     repository                                                   │
│ --config-file                 FILE  Cookiecutter Option: Optional path to                        │
│                                     "cookiecutter_config.yaml"                                   │
│ --input/--no-input                  Cookiecutter Option: Do not prompt for parameters and only   │
│                                     use cookiecutter.json file content                           │
│                                     [default: no-input]                                          │
│ --cleanup/--no-cleanup              Cleanup created temporary files [default: cleanup]           │
│ --help                              Show this message and exit.                                  │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯

工作流程

1. 创建一个新项目

使用start-project命令和一个github URL作为Cookiecutter模板，例如

~/manageprojects$ ./cli.py start-project https://github.com/jedie/cookiecutter_templates/ --directory piptools-python ~/my_new_project/
~/manageprojects$ cd ~/my_new_project/your_cool_package/
~/my_new_project/your_cool_package/$ git init
~/my_new_project/your_cool_package/$ git add .
~/my_new_project/your_cool_package/$ git commit --message "my cool new project"

注意：[https://github.com/jedie/cookiecutter_templates](https://github.com/jedie/cookiecutter_templates) 是一个多模板仓库，其中 piptools-python 模板位于此处：[https://github.com/jedie/cookiecutter_templates/tree/main/piptools-python](https://github.com/jedie/cookiecutter_templates/tree/main/piptools-python)

运行 start-project 命令后，查看创建的文件。Manage projects 将所需的所有元信息存储到 pyproject.toml 中，例如：

~/manageprojects$ cat ~/my_new_project/your_cool_package/pyproject.toml
...
[manageprojects] # https://github.com/jedie/manageprojects
initial_revision = "6e4c875"
initial_date = 2022-11-10T12:37:20+01:00
cookiecutter_template = "https://github.com/jedie/cookiecutter_templates/"
cookiecutter_directory = "piptools-python"

[manageprojects.cookiecutter_context.cookiecutter]
...

2. 更新现有项目

如果源 Cookiecutter 发生了变化，则可以将这些更改应用到您的创建项目中，例如：

~/manageprojects$ ./cli.py update-project ~/my_new_project/your_cool_package/

之后，manageproject 将通过添加 applied_migrations 来更新 pyproject.toml 中的元信息，其中包含当前 Cookiecutter 版本的信息，例如：

~/manageprojects$ cat ~/my_new_project/your_cool_package/pyproject.toml
...
[manageprojects] # https://github.com/jedie/manageprojects
initial_revision = "6e4c875"
initial_date = 2022-11-10T12:37:20+01:00
cookiecutter_template = "https://github.com/jedie/cookiecutter_templates/"
cookiecutter_directory = "piptools-python"
applied_migrations = [
    "dd69dcf", # 2022-11-22T19:48:28+01:00
]
...

如何？

一切基于 git ;)

• manageprojects 在创建时知道所使用的 Cookiecutter 模板的 git hash 和当前的 git hash。
• 它在这两个提交之间构建一个 git 补丁。
• 此补丁将应用到创建的项目源中。

因此，理论上模板中的更改已应用到项目中。

然而，这并不总是有效，因为 git 无法匹配这些更改。

见下文

缺点

一个问题在于 git 无法应用所有更改。

但是，使用带有 --reject 的 git apply。它应用补丁中可应用的部分，并将拒绝的块保留在相应的 *.rej 文件中。

有一个很酷的工具，叫做 wiggle：[https://github.com/neilbrown/wiggle](https://github.com/neilbrown/wiggle)

它通过执行逐词差异来尝试应用拒绝的补丁。

只需通过 manageproject CLI 运行 wiggle，例如：

~/manageprojects$ ./cli.py wiggle ~/my_new_project/your_cool_package/

通过覆盖更新

更新项目的另一种方法

1. 只需用当前的 Cookiecutter 模板输出覆盖所有文件
2. 手动通过 git 合并更改

因此，您不会有无法应用的 git 补丁的问题 ;)

只需添加 --overwrite，例如：

~/manageprojects$ ./cli.py update-project --overwrite ~/my_new_project/your_cool_package/

助手

以下是针对 Python 软件包的一些通用工具。

install_python.py

一个脚本，用于下载、构建和安装 Python 解释器，但前提是系统 Python 不是所需的较大版本。这是一个独立的脚本，没有依赖项。适用于 Python 3.9+。

更多信息：[docs/install_python.md](https://github.com/jedie/manageprojects/blob/main/docs/install_python.md)

"reverse" - 将项目转换为 Cookiecutter 模板

一个现有的管理项目可以转换回 Cookiecutter 模板，例如：

~/manageprojects$ ./cli.py reverse ~/my_new_project/ ~/cookiecutter_template/

"format-file" - 格式化和检查给定的 Python 源代码文件

您可以使用 format-file 作为 IDE 中的“保存时操作”或手动操作来修复代码风格 ;)

Usage: ./cli.py format-file [OPTIONS] FILE_PATH

 Format and check the given python source code file with
 darker/autoflake/isort/pyupgrade/autopep8/mypy etc.
 The optional fallback values will be only used, if we can't get them from the project meta files
 like ".editorconfig" and "pyproject.toml"

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ --py-version                     TEXT     Fallback Python version for darker/pyupgrade, if       │
│                                           version is not defined in pyproject.toml               │
│                                           [default: 3.10]                                        │
│ --max-line-length            -l  INTEGER  Fallback max. line length for darker/isort etc., if    │
│                                           not defined in .editorconfig                           │
│                                           [default: 119]                                         │
│ --darker-prefixes                TEXT     Apply prefixes via autopep8 before calling darker.     │
│                                           [default: E301,E302,E303,E305,W391]                    │
│ --remove-all-unused-imports               Remove all unused imports (not just those from the     │
│                                           standard library) via autoflake                        │
│                                           [default: True]                                        │
│ --help                                    Show this message and exit.                            │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯

发布

manageprojects.utilities.publish.publish_package() 专为外部包设计。

构建和上传（使用 twine）项目到 PyPi，并进行许多预检查

• 版本号正确吗？
• 是否位于主分支并与 origin 保持最新？
• 检查当前版本是否已发布
• 根据当前包版本构建 git 标签
• 将自上次发布以来的更改消息添加到 git 标签消息中

某些检查会导致程序退出，但某些可以手动由用户确认以继续发布。

开发

对于开发 manageprojects，有 dev-cli.py。

./dev-cli.py --help 的输出如下

Usage: ./dev-cli.py [OPTIONS] COMMAND [ARGS]...

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ --help      Show this message and exit.                                                          │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────╮
│ check-code-style            Check code style by calling darker + flake8                          │
│ coverage                    Run tests and show coverage report.                                  │
│ fix-code-style              Fix code style of all manageprojects source code files via darker    │
│ git-hooks                   Setup our "pre-commit" git hooks                                     │
│ install                     Run pip-sync and install 'manageprojects' via pip as editable.       │
│ mypy                        Run Mypy (configured in pyproject.toml)                              │
│ pip-audit                   Run pip-audit check against current requirements files               │
│ publish                     Build and upload this project to PyPi                                │
│ run-git-hooks               Run the installed "pre-commit" git hooks                             │
│ test                        Run unittests                                                        │
│ tox                         Run tox                                                              │
│ update                      Update "requirements*.txt" dependencies files                        │
│ update-readme-history       Update project history base on git commits/tags in README.md         │
│ update-test-snapshot-files  Update all test snapshot files (by remove and recreate all snapshot  │
│                             files)                                                               │
│ version                     Print version and exit                                               │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯

开发 git 钩子

要安装 git 钩子，请运行

~/manageprojects$ ./dev-cli.py git-hooks

历史

另见 git 标签：[https://github.com/jedie/manageprojects/tags](https://github.com/jedie/manageprojects/tags)

• v0.19.2
  • 2024-09-24 - 添加 piwheels 哈希。
  • 2024-09-24 - 应用来自 cookiecutter 模板的更新。
  • 2024-09-24 - 更新需求。
• v0.19.1
  • 2024-09-15 - 修复并增强 "setup_python.py" 的错误。
• v0.19.0
  • 2024-09-15 - 新增：setup_python.py
  • 2024-09-15 - 更新需求。
• v0.18.0
  • 2024-08-29 - 修复在发布调用中错误的 "module"。
  • 2024-08-29 - 修复在发布命令中错误的 "distribution_name"。
  • 2024-08-29 - 更新 typeannotations。
  • 2024-08-29 - 修复错误的类型注解
  • 2024-08-29 - 添加 IncludeInstallPythonBaseTestCase 以自动更新 'install_python.py'
  • 2024-08-29 - 添加：.pre-commit-hooks.yaml
  • 2024-08-29 - 新增：install_python.py
  • 2024-08-29 - 修复 CI + tox
  • 2024-08-29 - 更新 tox envlist 到 github action 矩阵
  • 2024-08-29 - Bugfix：通过 cookiecutter 模板更新 pyproject_toml.py
  • 2024-08-29 - 更新 requirements + 应用模板更新
  • 2024-03-08 - 也运行 "refurb"。
  • 2024-01-16 - 在测试中添加并使用 typeguard
  • 2024-07-09 - 分离 CLI
  • 2024-02-22 - 更新 requirements
  • 2023-12-30 - 修复拼写错误

链接

• 自己的Cookiecutter模板： https://github.com/jedie/cookiecutter_templates
• https://github.com/cookiecutter/cookiecutter
• GitHub上的可用Cookiecutters模板： https://github.com/search?q=cookiecutter&type=Repositories
• Python项目的打包： https://packaging.pythonlang.cn/en/latest/tutorials/packaging-projects/