Skip to content

Commit ee5008c

Browse files
AhzyuanAhzyuan
committed
Add 🐍 pyproject.toml support
1 parent 2af6991 commit ee5008c

File tree

2 files changed

+176
-12
lines changed

2 files changed

+176
-12
lines changed

‎CHANGELOG.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,17 @@
1+
<!-- # v1.4.0 -->
2+
3+
![](https://img.shields.io/badge/Version-v1.4.0-green)
4+
5+
## 🎉 Support `pyproject.toml`
6+
7+
see assets below.
8+
9+
## 🔄 Change
10+
11+
- `.github/CONTRIBUTING.md`: add suggestion for creating a new branch to submit PR.
12+
13+
---
14+
115
<!-- # v1.3.1 -->
216

317
![](https://img.shields.io/badge/Version-v1.3.1-green)

‎README.md

Lines changed: 162 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
## 📦 A Project Template for Self-developed Python Package
22

3-
[![Package Version](https://img.shields.io/badge/Version-v1.3.1-green)](https://github.com/Ahzyuan/Python-package-template/releases/tag/v1.3.1)
3+
[![Package Version](https://img.shields.io/badge/Version-v1.4.0-green)](https://github.com/Ahzyuan/Python-package-template/releases/tag/v1.4.0)
44
[![License](https://img.shields.io/badge/License-MIT-khaki)](https://opensource.org/license/MIT)
55
![Pypi Template](https://img.shields.io/badge/PyPI-Package_pattern-yellow?logo=pypi&labelColor=%23FAFAFA)
66

@@ -25,7 +25,7 @@ This repo provides an 𝐨𝐮𝐭-𝐨𝐟-𝐭𝐡𝐞-𝐛𝐨𝐱 𝐩𝐫
2525
2626
We provide:
2727

28-
1. **A fully configured package-setup file**, i.e., [`setup.cfg`](setup.cfg)
28+
1. **A fully configured package-setup file**, i.e., [`setup.cfg`](setup.cfg) or [`pyproject.toml`](https://github.com/Ahzyuan/Python-package-template/releases/download/v1.4.0/pyproject.toml).
2929
- It covers most common config items, allows dynamic access to `version`, `README`, and project dependencies at build time.
3030
- It is well commented, so you don't need to look up [documents](https://setuptools.pypa.io/en/latest/references/keywords.html) to understand each item's meaning.
3131

@@ -94,8 +94,144 @@ Python-package-template/
9494
## 🔨 Usage
9595

9696
> [!IMPORTANT]
97-
> In demo below, we assume that your github ID is `me` and project name is `my-project`.
98-
> **❗️❗️❗️ Remember to replace them with your own ID and project name when using ❗️❗️❗️**
97+
> - In demo below, we assume that your github ID is `me` and project name is `my-project`.
98+
> **❗️❗️❗️ Remember to replace them with your own ID and project name when using ❗️❗️❗️**
99+
>
100+
> - This template uses `setup.cfg` to manage all metadata by default. While `pyproject.toml` is an officially recommended alternative, I find it more complicated, so I prefer `setup.cfg`. But if you really want to use `pyproject.toml`, please **replace the `setup.cfg` with following file**.
101+
>
102+
> - [Download `pyproject.toml`](https://github.com/Ahzyuan/Python-package-template/releases/download/v1.4.0/pyproject.toml)
103+
> - <details>
104+
> <summary>𝚙𝚢𝚙𝚛𝚘𝚓𝚎𝚌𝚝.𝚝𝚘𝚖𝚕</summary>
105+
>
106+
> ```toml
107+
> # refer to https://packaging.python.org/en/latest/guides/writing-pyproject-toml
108+
> # See https://docs.astral.sh/ruff/settings for configuring ruff
109+
>
110+
> [build-system] # define build backend and dependencies needed to build your project
111+
> requires = ["setuptools>=66.0", "cython", "wheel", "isort", "ruff"] # dependencies needed to build your project
112+
> build-backend = "setuptools.build_meta" # build backend
113+
>
114+
> [project] # define metadata of your project
115+
>
116+
> # ---------------- Dynamic info ----------------
117+
> dynamic = ["version","dependencies"] # dynamic info will be filled in by the build backend
118+
>
119+
> # ---------------- Basic info ----------------
120+
> name = "your-package" # package name
121+
> authors = [
122+
> { name="your-name", email="your-email@mail.com" },
123+
> ]
124+
> maintainers = [
125+
> { name="your-name", email="your-email@mail.com" },
126+
> ]
127+
> description = "Package test" # one-line description of your project
128+
> readme = {file = "README.md", content-type = "text/markdown"} # specify README file
129+
>
130+
> # ---------------- Dependency info ----------------
131+
> requires-python = ">=3.7" # Python version requirement
132+
>
133+
> # ---------------- Other ----------------
134+
> keywords = ["A","B","c"] # keywords of your project, will help to suggest your project when people search for these keywords.
135+
> classifiers = [ # Trove classifiers, Full list: https://pypi.python.org/pypi?%3Aaction=list_classifiers
136+
> "Development Status :: 4 - Beta",
137+
> "Intended Audience :: Developers",
138+
> "Topic :: Software Development :: Build Tools",
139+
> "License :: OSI Approved :: MIT License",
140+
> "Programming Language :: Python :: 3",
141+
> "Programming Language :: Python :: 3.7",
142+
> "Programming Language :: Python :: 3.8",
143+
> "Programming Language :: Python :: 3.9",
144+
> "Programming Language :: Python :: 3.10",
145+
> "Programming Language :: Python :: 3.11",
146+
> "Programming Language :: Python :: 3.12",
147+
> ]
148+
>
149+
> # ---------------- Optional dependency ----------------
150+
> [project.optional-dependencies]
151+
> docs = ["sphinx>=7.0.0"]
152+
>
153+
> test = [
154+
> "pytest",
155+
> "pytest-sugar"]
156+
>
157+
> cli = [
158+
> "rich",
159+
> "click",
160+
> ]
161+
>
162+
> # Install a command as part of your package
163+
> [project.gui-scripts] # use [project.gui-scripts] to compatiable with differernt system
164+
> your-package = "your-package.cli:app" # command = package:func
165+
>
166+
>
167+
> # URLs associated with your project
168+
> [project.urls]
169+
> Homepage = "https://github.com/your-name/your-package"
170+
> Repository = "https://github.com/your-name/your-package.git"
171+
> Issues = "https://github.com/your-name/your-package/issues"
172+
> Changelog = "https://github.com/your-name/your-package/blob/master/CHANGELOG.md"
173+
>
174+
> [tool.setuptools.dynamic]
175+
> version = {attr = "your-package.__version__"} # automatically obtain the value by `my_package.__version__`.
176+
> dependencies = {file = ["requirements.txt", "requirement.txt", > "requirement"]}
177+
>
178+
> # -------------------------------- Tools Setting --------------------------------
179+
> [tool.setuptools]
180+
> license-files = ['LICEN[CS]E*', 'COPYING*', 'NOTICE*', 'AUTHORS*'] # specify License files
181+
>
182+
> [tool.setuptools.packages]
183+
> find = {} # Scan the project directory with the default parameters
184+
>
185+
> [tool.ruff]
186+
> # Allow lines to be as long as 120.
187+
> line-length = 120
188+
>
189+
> [tool.ruff.format]
190+
> # Enable reformatting of code snippets in docstrings.
191+
> docstring-code-format = true
192+
>
193+
> [tool.ruff.lint]
194+
> # Skip unused variable rules
195+
> ignore = [
196+
> "ANN101", # Missing type annotation for `self` in method
197+
> "ANN102", # Missing type annotation for `cls` in classmethod
198+
> "ANN401", # Dynamically typed expressions (typing.Any) are disallowed
199+
> "C901", # function is too complex (12 > 10)
200+
> "COM812", # Trailing comma missing
201+
> "D", # Docstring rules
202+
> "EM101", # Exception must not use a string literal, assign to variable first
203+
> "EM102", # Exception must not use an f-string literal, assign to variable first
204+
> "ERA001", # Found commented-out code
205+
> "FBT001", # Boolean positional arg in function definition
206+
> "FBT002", # Boolean default value in function definition
207+
> "FBT003", # Boolean positional value in function call
208+
> "FIX002", # Line contains TODO
209+
> "ISC001", # Isort
210+
> "PLR0911", # Too many return statements (11 > 6)
211+
> "PLR2004", # Magic value used in comparison, consider replacing 2 with a constant variable
212+
> "PLR0912", # Too many branches
213+
> "PLR0913", # Too many arguments to function call
214+
> "PLR0915", # Too many statements
215+
> "S101", # Use of `assert` detected
216+
> "S311", # Standard pseudo-random generators are not suitable for cryptographic purposes
217+
> "T201", # print() found
218+
> "T203", # pprint() found
219+
> "TD002", # Missing author in TODO; try: `# TODO(<author_name>): ...`
220+
> "TD003", # Missing issue link on the line following this TODO
221+
> "TD005", # Missing issue description after `TODO`
222+
> "TRY003", # Avoid specifying long messages outside the exception class
223+
> "PLW2901", # `for` loop variable `name` overwritten by assignment target
224+
> "SLF001", # Private member accessed: `_modules`
225+
> ]
226+
>
227+
> [tool.ruff.lint.isort]
228+
> length-sort = true # sort imports by their string length
229+
> combine-as-imports = true # combines as imports on the same line
230+
> known-first-party = ["your-package"]
231+
> lines-after-imports = 1 # Use a single line after each import block.
232+
> single-line-exclusions = ["os", "json", "re"] # modules to exclude from the single line rule
233+
> ```
234+
> </details>
99235
100236
1. <details>
101237
<summary>🚀 𝐂𝐫𝐞𝐚𝐭𝐞 𝐲𝐨𝐮𝐫 𝐫𝐞𝐩𝐨</summary>
@@ -169,17 +305,17 @@ Python-package-template/
169305
<summary>📄 𝐌𝐨𝐝𝐢𝐟𝐲 𝐭𝐡𝐞 𝐟𝐨𝐥𝐥𝐨𝐰𝐢𝐧𝐠 𝐟𝐢𝐥𝐞𝐬</summary>
170306

171307
<details>
172-
<summary>① 𝚜𝚎𝚝𝚞𝚙.𝚌𝚏𝚐 (𝚖𝚘𝚜𝚝 𝚒𝚖𝚙𝚘𝚛𝚝𝚊𝚗𝚝)</summary>
308+
<summary>① 𝚜𝚎𝚝𝚞𝚙.𝚌𝚏𝚐 / 𝚙𝚢𝚙𝚛𝚘𝚓𝚎𝚌𝚝.𝚝𝚘𝚖𝚕 (𝚖𝚘𝚜𝚝 𝚒𝚖𝚙𝚘𝚛𝚝𝚊𝚗𝚝)</summary>
173309

174310
> 💡 Tips
175311
>
176-
> • If your `README` is in `rst` format, you need to change `long_description_content_type` to `"text/x-rst"` instead.
312+
> • If your `README` is in `rst` format, you need to replace `"text/markdown"` with `"text/x-rst"` in `long_description_content_type`(`setup.cfg`) or `readme`(`pyproject.toml`).
177313
>
178-
> • If you want to create a CLI command for your package, enable `[options.entry_points]` option. See more [here](https://packaging.python.org/en/latest/guides/creating-command-line-tools/).
314+
> • If you want to create a CLI command for your package, enable `[options.entry_points]` option in `setup.cfg` or `[project.gui-scripts]` in `pyproject.toml`. See more [here](https://packaging.python.org/en/latest/guides/creating-command-line-tools/).
179315
>
180-
> • If you want more configuration, refer to [here](https://setuptools.pypa.io/en/latest/references/keywords.html)
316+
> • If you want more configuration, refer to [keywords of `setup.cfg`](https://setuptools.pypa.io/en/latest/references/keywords.html) or [keywords of `pyproject.toml`](https://setuptools.pypa.io/en/latest/userguide/pyproject_config.html)
181317

182-
**Look for the following variables in the file and modify as per comments.**
318+
**Look for the following variables in `setup.cfg` and modify as per comments.**
183319

184320
| Basic | Requirement related | Package structure related |
185321
|:------------------:|:--------------------------:|:-------------------------:|
@@ -194,6 +330,20 @@ Python-package-template/
194330
| `license` | | |
195331
| `classifiers` | | |
196332

333+
**If you are using `pyproject.toml`, you may need to replace `your-package` with `my-package` in file first, then check out and modify following variables.**
334+
335+
| Basic | Requirement related | Package structure related |
336+
|:----------------:|:---------------------------------:|:-------------------------:|
337+
| `name` | `requires` | `find` |
338+
| `version` | `requires-python` | |
339+
| `authors` | `[project.optional-dependencies]` | |
340+
| `maintainers` | | |
341+
| `description` | | |
342+
| `readme` | | |
343+
| `[project.urls]` | | |
344+
| `keywords` | | |
345+
| `classifiers` | | |
346+
197347
</details>
198348

199349
<details>
@@ -363,7 +513,7 @@ Python-package-template/
363513
> • Also, don't forget to generate a token for uploading your package. See more [here](https://pypi.org/help/#apitoken).
364514
365515
> 📋 **𝖲𝗎𝗀𝗀𝖾𝗌𝗍𝗂𝗈𝗇**
366-
> You likely have many commits to `PyPI` or `TestPyPI` to familiarize yourself with the process. In this case, you can maintain a **forged `PyPI` server locally**, see [`🧰 Tools Recommended -> pypi-server` below](#tools-recommended).
516+
> You likely have many commits to `PyPI` or `TestPyPI` to familiarize yourself with the process. In this case, you can maintain a **forged `PyPI` server locally**, see [`🧰 Tools Recommended -> pypi-server` below](#-tools-recommended).
367517
368518
```bash
369519
# pwd: .../MYPROJECT
@@ -379,7 +529,7 @@ Python-package-template/
379529
380530
- Sure, you can paste your token in terminal to go through the process.
381531
382-
- But if you are tired of doing this, you can use `.pypirc` and `keyring` to automatically access your token whenever needed. Follow the step in [`configure .pypirc and keyring 🔐` below](#tools-recommended).:
532+
- But if you are tired of doing this, you can use `.pypirc` and `keyring` to automatically access your token whenever needed. Follow the step in [`configure .pypirc and keyring 🔐` below](#-tools-recommended).:
383533
384534
</details>
385535
@@ -574,7 +724,7 @@ Standardizing project participation cuts communication costs and boosts developm
574724
575725
- [x] Add full pipeline of package development, from project preparation to maintaining.
576726
- [x] Add CI/CD support, such as GitHub Actions
577-
- [ ] Add `pyproject.toml` support
727+
- [x] Add `pyproject.toml` support
578728
- [x] Add linter
579729
580730
## 👀 See More

0 commit comments

Comments
 (0)