Core metadata specifications - Python Packaging User Guide
Description#
New in version 1.0.
Changed in version 2.1: This field may be specified in the message body instead.
A longer description of the distribution that can run to several
paragraphs. Software that deals with metadata should not assume
any maximum size for this field, though people shouldn’t include
their instruction manual as the description.
The contents of this field can be written using reStructuredText
markup [1]. For programs that work with the metadata, supporting
markup is optional; programs can also display the contents of the
field as-is. This means that authors should be conservative in
the markup they use.
To support empty lines and lines with indentation with respect to
the RFC 822 format, any CRLF character has to be suffixed by 7 spaces
followed by a pipe (“|”) char. As a result, the Description field is
encoded into a folded field that can be interpreted by RFC822
parser [2].
Example:
Description: This project provides powerful math functions
|For example, you can use `sum()` to sum numbers:
|
|Example::
|
| >>> sum(1, 2)
| 3
|
This encoding implies that any occurrences of a CRLF followed by 7 spaces
and a pipe char have to be replaced by a single CRLF when the field is unfolded
using a RFC822 reader.
Alternatively, the distribution’s description may instead be provided in the
message body (i.e., after a completely blank line following the headers, with
no indentation or other special formatting necessary).
https://packaging.python.org/specifications/core-metadata/
最近の python package の記述の仕方で、 pyproject.toml
なる作法があるのでメモ。
元々、 setup.py
や setup.cfg
で記述していたのだけどこれに変わるものらしい。
setup.py
はともかく setup.cfg
が大変分かりにくいと思っていました。
というか、何か調べにくい。
setup.py
を宣言的に書けるよ、詳しくは setup.py
のリファンンスを見て。みたいになっているのだけど、
書き方がよくわからんことが多かった。
2013年に distribute は setuptools にマージされた
pyproject.toml
- (2019)pyproject.toml とは何か
pyproject.toml は Node.js の package.json などのように、そのプロジェクトに関する様々なことを定義できるファイルとして存在しています
なるほど。
pyproject の build-system
setuptools
- https://packaging.python.org/tutorials/packaging-projects/#creating-pyproject-toml
- (2021)PyPIパッケージのリリースもバージョニングもGitHub単独で完結させる
なるほど。
setup.cfg
と pyproject.toml
の役割が被っていると思うのだが両方要るのだろうか。
- (2021)PyPIにパッケージを公開する手順の整理
pyproject.toml
には build-backend
の指定だけを記述して、 setup.cfg
と併用するということでよさそう。
setup.py & setup.cfg
setup.py
- https://packaging.python.org/guides/distributing-packages-using-setuptools/
- https://github.com/dephell/dephell/blob/master/setup.py
setup.cfg: metadata
setup.cfg: options
setup.cfg: options.entry_points
setup.cfg:
poetry
練習
https://github.com/ousttrue/glglue に使ってみる。
結局、 setup.cfg
を使っているのとあまり変わらず。
setuptools_scm
による git tag を version
化する技を覚えた。
あと、github actions
。
そのうち、 setup.cfg
の内容を pyproject.toml
に書けるようになりそうではある。