PyPA specifications
###################


Package Distribution Metadata
=============================


Names and normalization
-----------------------

规范形式::

    friendly-bard (normalized form)

    以下命名和上面等效:
    friendly_bard
    Friendly-Bard
    FRIENDLY-BARD
    friendly.bard
    friendly--bard
    FrIeNdLy-._.-bArD (a terrible way to write a name, but it is valid)



Version specifiers
==================

Version scheme
--------------

Public version identifiers::

    [N!]N(.N)*[{a|b|rc}N][.postN][.devN]

    说明: 
    1. Epoch segment: N!
    2. Release segment: N(.N)*
    3. Pre-release segment: {a|b|rc}N
    4. Post-release segment: .postN
    5. Development release segment: .devN

Local version identifiers::

    <public version identifier>[+<local version label>]

Final releases::

    N(.N)*

Pre-releases::

    X.YaN   # Alpha release
    X.YbN   # Beta release
    X.YrcN  # Release Candidate
    X.Y     # Final release


Post-releases::

    X.Y.postN    # Post-release

    # Post-releases are also permitted for pre-releases:
    X.YaN.postM   # Post-release of an alpha release
    X.YbN.postM   # Post-release of a beta release
    X.YrcN.postM  # Post-release of a release candidate

Developmental releases::

    X.Y.devN    # Developmental release

    # Developmental releases are also permitted for pre-releases and post-releases:
    X.YaN.devM       # Developmental release of an alpha release
    X.YbN.devM       # Developmental release of a beta release
    X.YrcN.devM      # Developmental release of a release candidate
    X.Y.postN.devM   # Developmental release of a post-release


Version epochs::

    E!X.Y  # Version identifier with epoch

    # 说明:
    大多数版本标识符不会包含 epoch，因为仅当项目更改处理版本编号的方式意味着正常的版本排序规则会给出错误的答案时，才需要显式 epoch
    如:
        如果一个项目正在使用基于日期的版本（如 2014.04），并且希望切换到 1.0 等语义版本
        那么在使用常规排序方案时，新版本将被标识为早于基于日期的版本
            1.0
            1.1
            2.0
            2013.10
            2014.04
        通过指定显式 epoch
            2013.10
            2014.04
            1!1.0
            1!1.1
            1!2.0



排序::

    .devN, aN, bN, rcN, <no suffix>, .postN

    示例:
    1.dev0
    1.0.dev456
    1.0a1
    1.0a2.dev456
    1.0a12.dev456
    1.0a12
    1.0b1.dev456
    1.0b2
    1.0b2.post345.dev456
    1.0b2.post345
    1.0rc1.dev456
    1.0rc1
    1.0
    1.0+abc.5
    1.0+abc.7
    1.0+5
    1.0.post456.dev34
    1.0.post456
    1.0.15
    1.1.dev1


Version specifiers
------------------

比较运算符::

    ~=:     Compatible release clause(兼容版)
    ==:     Version matching clause(版本匹配)
    !=:     Version exclusion clause(版本排除)
    <=, >=: Inclusive ordered comparison clause(包含有序比较)
    <, >:   Exclusive ordered comparison clause(独占有序比较)
    ===:    Arbitrary equality clause(任意相等)


Compatible release::

    ~=V.N
    # 相当于
    >= V.N, == V.*
    # (“,”) is equivalent to a logical and operator

    以下 version 子句组是等效的：
        ~= 2.2
        >= 2.2, == 2.*

        ~= 1.4.5
        >= 1.4.5, == 1.4.*

    如果预发行版本、后发行版本或开发版本，将忽略该后缀：

        ~= 2.2.post3
        >= 2.2.post3, == 2.*

        ~= 1.4.5a4
        >= 1.4.5a4, == 1.4.*


Version matching::

    # 严格匹配
    ==1.1
    # 前缀匹配
    == 1.1.*

    示例:
        匹配语句: == 1.1.*
        1.1.post1   ✅
        1.1a1       ✅
        1.1         ✅


Version exclusion::

    功能与 `Version matching` 类似

    示例:
        匹配语句: != 1.1.*
        1.1.post1       🚫
        1.1             ✅



Inclusive ordered comparison::

    非独占有序比较运算符为 <= 和 >=


Exclusive ordered comparison::

    独占有序比较 >V不得与指定版本的本地版本匹配
    独占有序比较 <V不得允许指定版本的预发布版

    示例:
        匹配语句: >1.7.post2
        1.7.1           ✅
        1.7.0.post3     ✅
        1.7.0           🚫


Arbitrary equality::

    说明:
        任意相等比较是简单的字符串相等操作，它不考虑任何语义信息，例如零填充或本地版本

    注意:
        强烈建议不要使用此运算符，并且工具在使用时可能会显示警告



Direct references
=================

PEP 508 Direct references::

    # PEP 508 允许在 requirements.txt 或 setup.py 文件中使用 Direct references
        some-package @ git+https://github.com/username/repository.git@commit_hash


pyproject.toml 文件允许你通过 direct_url 来指定依赖项的 Direct references::

    [tool.poetry.dependencies]
    my_package = { git = "https://github.com/username/repository.git", rev = "main" }


示例::

    # 本地源存档
    my_package @ file:///localbuilds/my_package-1.3.1.zip
    my_package @ file:///localbuilds/my_package-1.3.1-py33-none-any.whl

    # Remote URL
    my_package @ https://github.com/pypa/my_package/archive/1.3.1.zip#sha1=da9234ee9982d4bbb3c72346a6de940a148ea686
    my_package @ git+https://github.com/pypa/my_package.git@7921be1537eac1e97bc40179a57f0349c2aee67d
    my_package @ git+https://github.com/pypa/my_package.git@1.3.1#7921be1537eac1e97bc40179a57f0349c2aee67d





Platform compatibility tags
===========================

Overview
--------

tag format::

    {python tag}-{abi tag}-{platform tag}

    说明: 
        python tag:
            ‘py27’, ‘cp33’
        abi tag:
            ‘cp32dmu’, ‘none’
        platform tag:
            ‘linux_x86_64’, ‘any’

wheel built package format includes these tags in its filenames::

    {distribution}-{version}(-{build tag})?-{python tag}-{abi tag}-{platform tag}.whl



Python Tag
----------

Python implementations::

    py: Generic Python (does not require implementation-specific features)
    cp: CPython
    ip: IronPython
    pp: PyPy
    jy: Jython



ABI Tag
-------

示例::

    cp33d: CPython 3.3 ABI with debugging
    abi3: CPython stable ABI



Platform Tag
------------

Basic platform tags::

    win32
    linux_i386
    linux_x86_64


manylinux::

    manylinux1 supports glibc 2.5 on x86_64 and i686 architectures.
    manylinux2010 supports glibc 2.12 on x86_64 and i686.
    manylinux2014 supports glibc 2.17 on x86_64, i686, aarch64, armv7l, ppc64, ppc64le, and s390x.


musllinux::

    similar to manylinux, but for Linux platforms that use the musl libc rather than glibc