setupmeta 2.6.5

简化设置。py

编写setup.py通常涉及大量样板文件和从一个项目到另一个项目的复制粘贴。

这个包旨在简化这个过程，并为pythonpackaging带来一些DRY原则。 以下是您的（完整的，准备好发送到pypi的）setup.py在使用setupmeta时的样子：

from setuptools import setup

setup(
    name="myproject",
    versioning="distance",          # Optional, would activate tag-based versioning
    setup_requires="setupmeta"      # This is where setupmeta comes in
)

应该是这样-setupmeta将从那里获取它，从项目的其余部分提取所有其他内容 （遵循常用的典型惯例）。

您可以使用explain命令（请参见commands）查看从项目中推断出的setupmeta， 对于上面的内容，它看起来像这样（您可以看到每个设置来自哪个文件和哪个行， 请注意，如果遵循常规，通常会从项目中提取大量信息：

~/myproject: python setup.py explain

          author: (auto-adjust     ) Your Name
              \_: (myproject.py:7  ) Your Name<your@email.com>
    author_email: (auto-adjust     ) your@email.com
     classifiers: (classifiers.txt ) 6 items: ["Development Status :: ...
     description: (README.rst:1    ) First line of your README
    entry_points: (entry_points.ini) [console_scripts] ...
install_requires: (requirements.txt) ["click", ...
         license: (auto-fill       ) MIT
long_description: (README.rst      ) Long description would be your inlined README
            name: (explicit        ) myproject
      py_modules: (auto-fill       ) ["myproject"]
  setup_requires: (explicit        ) ["setupmeta"]
         version: (git             ) 1.2.3.post2
      versioning: (explicit        ) distance

有关详细信息，请参见examples。

目标

本项目的目标是：

• 允许写得很短（但很完整）setup.py-s，不使用样板，并鼓励良好的公共实践packaging
• 指出setup.py explain
中缺少的重要信息（例如：版本）
• 支持基于标签的versioning（类似于setuptools_scm，但具有超级简单的配置/默认值和自动化的bump功能）
• 提供有用的Commands以查看元数据（explain），version（包括对缓冲版本的支持）。 cleanall，tween等

它是怎么工作的？

• 在最初的setuptools.setup()调用中显式提供的所有内容都被视为（从未更改过）。 内部标记为explicit。 所以如果你不喜欢setupmeta推断出来的东西，你总是可以显式地声明它。

• name是从您的setup.py的__title__中自动填充的（如果有，有时有一个常量非常方便…）

• ^如果有<name>/__init__.py或src/<name>/__init__.py文件，则{tt10}$和package_dir会相应地自动填充

• py_modules是自动填充的，如果您有<name>.py文件

• classifiers是从文件classifiers.txt自动填充的（每行一个分类，忽略空行和python样式的注释）

• entry_points是从文件中自动填充的entry_points.ini（另外：像pycharm这样的工具有一个很好的语法高亮显示器）

• install_requires是自动填充的，如果您有requirements.txt（或pinned.txt）文件， 默认情况下，按community recommendation提取固定，有关详细信息，请参见requirements。

• tests_require是自动填充的，如果您有tests/requirements.txt或requirements-dev.txt， 或dev-requirements.txt，或test-requirements.txt文件

• description将是自述文件的第一行（除非第1行太短，或者只是项目名称）。 或扫描文件中找到的第一个docstring的第一行（请参见下面的列表）

• long_description是从自述文件中自动填充的（查找README.rst，README.md， 然后README*，第一个找到wins）。 可以使用特殊的标记（针对它们的标记很容易成为rst comments）：

  • ^{tt33}$ as end marker, so you don’t have to use the entire file as long description
  • ^{tt34}$ if you want another file included as well (for example, people like to add ^{tt35}$ as well)
  • these tokens must appear either at beginning/end of line, or be after/before at least one space character

• version可以显式声明，也可以使用versioning=...从git标记计算（有关详细信息，请参见versioning）：

  • With ^{tt38}$, your git tags will be of the form ^{tt39}$, the number of commits since latest version tag will be used to auto-fill the “patch” part of the version:

    • tag “v1.0.0”, no commits since tag -> version is “1.0.0”
    • tag “v1.0.0”, 5 commits since tag -> version is “1.0.5”
    • if checkout is dirty, a marker is added -> version would be “1.0.5.post5.dirty”

  • 使用versioning="post"，git标记的格式将为v{major}.{minor}.{patch}， 如果有自最新版本标记之后的提交，则会出现“post”附录：

    • tag “v1.0.0”, no commits since tag -> version is “1.0.0”
    • tag “v1.0.0”, 5 commits since tag -> version is “1.0.0.post5”
    • if checkout is dirty, a marker is added -> version would be “1.0.0.post5.dirty”

  • 使用versioning="build-id"，git标记的格式将为v{major}.{minor}.0， 自最新版本标记以来提交的次数将用于自动填充版本的“修补程序”部分：

    • tag “v1.0.0”, no commits since tag, ^{tt44}$ -> version is “1.0.0+h12.g123”
    • tag “v1.0.0”, no commits since tag, ^{tt45}$ not defined -> version is “1.0.0+hlocal.g123”
    • tag “v1.0.0”, 5 commits since tag, ^{tt44}$ -> version is “1.0.5+h12.g456”
    • tag “v1.0.0”, 5 commits since tag, ^{tt45}$ not defined -> version is “1.0.5+hlocal.g456”
    • if checkout is dirty, a marker is added -> version would be “1.0.5+hlocal.g456.dirty”

  • 使用bump命令（请参见commands）轻松地进行bump（即：增加major、minor或patch+apply git标记）

  • 版本格式可以自定义，有关详细信息，请参见versioning

• ^{TT36}$，^{TT49}$，^{TT50}$，^{TT51}$，^{TT52}$，^{TT53}$，^{TT54}$，^{TT55}$，^{TT56}$，^{TT57}$， 和platforms将从以下位置自动填充：

  • Lines of the form ^{tt59}$ in your modules (simple constants only, expressions are ignored - the modules are not imported but scanned using regexes)

  • Lines of the form ^{tt60}$ in your docstring

  • Files are examined in this order (first find wins):

    • ^{tt1}$
    • ^{tt62}$ (mccabe for example)
    • ^{tt63}$ (cryptography for example)
    • ^{tt64}$ (requests for example)
    • ^{tt65}$ (changes, arrow for example)
    • ^{tt66}$ is also examined (for those who like to have their packages under ^{tt67}$)

  • 网址可以简化：

    • if ^{tt50}$ points to your general github repo (like: https://github.com/zsimic), the ^{tt8}$ of your project is auto-appended to it
    • relative urls are auto-filled by prefixing them with ^{tt50}$
    • urls may use ^{tt71}$ and/or ^{tt72}$ markers, it will be expanded appropriately

  • author、maintainer和contact名称和电子邮件可以组合成一行 （setupmeta将找出电子邮件部分并自动正确填写）

    • i.e.: ^{tt76}$ will yield the proper ^{tt55}$ and ^{tt78}$ settings

希望这对绝大多数python项目都能很好地工作。 如果您需要高级的东西，您仍然可以利用setupmeta来处理上面所有的常规东西，并在需要的地方显式地进行处理。