pyOpenSci Python 包模板

一个支持 pyOpenSci 纯 Python 打包教程的 Python 包模板。本模板可与 copier 配合使用，以初始化一个新的 Python 包项目结构，遵循 pyOpenSci 纯 Python 打包教程中概述的实践。

如果您想进一步了解打包，请查阅我们的 Python 打包指南。

开始使用

要使用此模板：

使用 pipx 或 pip 安装 copier，最好配合虚拟环境使用。

全局安装：
```
pipx install copier
```

或针对特定环境的安装：

```console
pip install copier
```

2. 运行以下 copier 命令。请注意，如果目标目录尚不存在，copier 会创建该目录。它还会在给定目录中创建并可能覆盖文件，即使该目录已存在！ 如果当前目录是目标目录，则包括当前目录。

```console
copier copy gh:pyopensci/pyos-package-template path/here
```

```console
copier copy gh:pyopensci/pyos-package-template .
```

以上述方式使用时，copier 将使用最新的带标签的发布版本，这通常是最安全的选项。您可以提供选项 --vcs-ref 来选择特定分支作为您的源。您可以阅读有关生成您的项目的更多信息在 copier 文档。

运行模板工作流

一旦您安装了 copier，您就可以使用我们的模板创建您的 Python 包。

首先，从您喜欢的 shell 中运行以下命令，并在您想要存储包的目录中运行。请注意，此步骤会从 GitHub 复制我们的模板，因此需要互联网访问。

copier copy gh:pyopensci/pyos-package-template .

如果您希望在另一个目录中创建该包，可以按以下方式指定目录：

copier copy gh:pyopensci/pyos-package-template dirname-here

模板概述

copier 模板会向你提出一系列问题，你可以对此进行回答。这些问题将帮助你自定义模板。

快速入门：一个最小示例包

如果你在模板中使用 minimal 选项，模板问题将简短。此工作流创建一个最简单的 Python 包，包含一个 tests\ 目录和一个使用 Sphinx 的 docs\ 目录。

➜ copier copy gh:pyopensci/pyos-package-template .
🎤 "Welcome to the pyOpenSci package template.
Please select the type of template that you want to create today."
 >> MINIMAL: I want a minimal setup (package, tests and docs; typing); linting not included).
    FULL DEFAULT: I want to use the default settings but I want it setup for me.
    FULL CUSTOM: I want it all but I want to fully customize all template elements.
🎤 What is the name of the project? Used as the README.md title, in the
   pyospackage_juno
🎤 Please provide a short description for the package.
    (Finish with 'Alt+Enter' or 'Esc then Enter')
> A great package that adds and subtracts numbers.

🎤 Who is the author of the package? Used in the package description.
   juno dawg
🎤 Provide you or your organization's GitHub username. Used to generate
   pyopensci

Copying from template version 0.6.4.1
 identical  .
    create  CODE_OF_CONDUCT.md
    create  .gitignore
    create  CHANGELOG.md
    create  LICENSE
    create  README.md
    create  tests
    create  tests/unit
    create  tests/unit/test_example.py
 identical  .editorconfig
    create  .github
    create  .github/workflows
    create  .github/workflows/release.yml
    create  .github/workflows/test.yml
    create  .github/PULL_REQUEST_TEMPLATE.md
    create  .github/ISSUE_TEMPLATE
    create  .github/ISSUE_TEMPLATE/config.yml
    create  .github/ISSUE_TEMPLATE/01-bug-report.yml
    create  CONTRIBUTING.md
    create  docs
    create  docs/conf.py
    create  docs/index.md
    create  pyproject.toml
    create  src
    create  src/pyospackage_juno
    create  src/pyospackage_juno/example.py
    create  src/pyospackage_juno/__init__.py

创建好包之后，您可以使用 pip 或 uv 以可编辑模式安装它。

面向 UV 用户

$ cd my_directory
$ uv sync # Run uv sync to create a venv and install your dependencies
$ UV run python # Open a python prompt using the UV managed environment

### For pip users

First, CD to the directory where your new package lives, and install the package in editable mode:

```console
$ cd my_directory
$ conda activate myenv # 使用你喜欢的环境管理器激活你的环境
$ pip install -e . # 以可编辑模式安装你的包
$ python # 打开一个 python 提示符

We have included a small module in the package template in case you want to test drive that package in an environment before adding to it.

>>> from your_package import example # 我们已将示例模块命名为 example.py
>>> example.add_numbers(1,2) # 该模块有一个简单的函数，用于将两个数字相加
3
>>> quit() # 退出 python 提示符并返回到你的 shell

Build your package

The template has Hatch environments setup.

You can build your package using Hatch which is included in the template. First, make sure you have Hatch installed in your environment. Then, run hatch build.

$ hatch build
─────────────────── sdist ────────────────
dist/yourpackage-0.1.0.tar.gz
─────────────────── wheel ──────────────────
dist/yourpackage-0.1.0-py2.py3-none-any.whl

To use the hatch build environment run:

hatch run build:check

This will create a new venv environment and build your package's wheel and source distributions.

Full customization: A more complex example package

If you want to fully customize your package, then the template workflow will look like the example below:

➜ copier copy gh:pyopensci/pyos-package-template .
🎤 版权持有人是谁，例如你自己或你的组织？用于许可证
   pyos
🎤 包的作者是谁？用于包描述。
   pyos
🎤 作者的电子邮件地址。用于包描述。
   youremail@youremail.com
🎤 项目名称是什么？用作 README.md 和其他地方的标题。
   mypkg
🎤 请为包提供一个简短的描述。
    (使用 'Alt+Enter' 或 'Esc 然后 Enter' 结束)
> 描述在此处
🎤 你是否想跳过所有剩余问题并直接使用提供的默认值？
   不，我想完全自定义模板。
🎤 项目 slug 是什么？用于超链接。
   mypkg
🎤 Python 包的名称是什么？用作包名和顶级导入名称。
   mypkg
🎤 您希望使用动态版本管理还是静态版本管理？动态意味着版本
   No
🎤 您是否希望使用 git 配合开发平台，例如 GitHub 或 GitLab？
   Yes
🎤 您计划使用哪个开发平台？用于生成某些文档和
   GitHub
🎤 您或您的组织在 GitHub 上的用户名。用于生成某些文档和超
   pyopensci
🎤 您是否希望为项目包含文档，以及希望使用哪个框架？
   Sphinx (https://www.pyopensci.org/pyos-sphinx-theme)
🎤 您是否希望使用 hatch 环境来运行隔离命令，例如 linting、构建文档
   Yes
🎤 您是否希望对代码进行 linting 并检查文件的格式？
   Yes
🎤 您是否希望使用类型注解并对代码进行类型检查？
   No
🎤 您是否希望测试您的代码？通常，我们强烈建议您这样做，但对于快速
   Yes
🎤 您希望使用哪种许可证？用于许可证文件。
   MIT
🎤 项目的起始年份是什么？用于版权声明。
   2024

保持最新

社区很可能会继续开发此模板。如果任何时候，您希望将那些更改应用到您的项目中，您可以进行更新。有关该流程的更多信息，请参阅 copier 文档。

贡献者 ✨

感谢这些出色的人（表情符号说明）：

_{Moritz E. Beber} 💻 👀 🤔	_{Steven Silvester} 💻 👀 🤔	_{Jonny Saunders} 💻 👀	_{Jeremy Paige} 💻 👀	_{Leah Wasser} 💻 👀	_{Agriya Khetarpal} 👀	_{Yuvi Panda} 💻 👀
_{Michael-Howes} 🐛	_{Erik Whiting} 💻 👀	_{Michael Pilosov, PhD} 👀

本项目遵循 all-contributors 规范。欢迎任何形式的贡献！