Python 编写一个自己的包

这个教程将会指导你开发一个属于自己的python包，
还包含如何添加必要的文件以及包的结构，
最后说说如何编译并上传该文件。

简单示例

假定工程的名称为：example_pkg，需要创建下列目录结构：

1
2
3

packaging_tutorial/
  example_pkg/
    __init__.py

下面所有的操作均在目录中packaging_tutorial进行。

example_pkg/init.py is required to import the directory as a package, and can simply be an empty file.

创建package文件

标准package起始最好包含以下文件，

packaging_tutorial/
  example_pkg/
    __init__.py
  tests/
  setup.py
  LICENSE
  README.md

创建test文件夹

tests/主要用来存放unit测试文件，此时先留空。

创建 setup.py

setup.py文件用于编译，内容主要包含package的名字、版本、描述等等信息。

示例如下：

import setuptools

with open("README.md", "r") as fh:
    long_description = fh.read()

setuptools.setup(
    name="example-pkg-YOUR-USERNAME-HERE", # Replace with your own username
    version="0.0.1",
    author="Example Author",
    author_email="author@example.com",
    description="A small example package",
    long_description=long_description,
    long_description_content_type="text/markdown",
    url="https://github.com/pypa/sampleproject",
    packages=setuptools.find_packages(),
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
    python_requires='>=3.6',
)

setup() 的几个最必须的参数如下所示：

name is the distribution name of your package. This can be any name as long as only contains letters, numbers, _ , and -. It also must not already be taken on pypi.org. Be sure to update this with your username, as this ensures you won’t try to upload a package with the same name as one which already exists when you upload the package.

version is the package version see PEP 440 for more details on versions.

author and author_email are used to identify the author of the package.

description is a short, one-sentence summary of the package.

long_description is a detailed description of the package. This is shown on the package detail package on the Python Package Index. In this case, the long description is loaded from README.md which is a common pattern.

long_description_content_type tells the index what type of markup is used for the long description. In this case, it’s Markdown.

url is the URL for the homepage of the project. For many projects, this will just be a link to GitHub, GitLab, Bitbucket, or similar code hosting service.

packages is a list of all Python import packages that should be included in the distribution package. Instead of listing each package manually, we can use find_packages() to automatically discover all packages and subpackages. In this case, the list of packages will be example_pkg as that’s the only package present.

classifiers gives the index and pip some additional metadata about your package. In this case, the package is only compatible with Python 3, is licensed under the MIT license, and is OS-independent. You should always include at least which version(s) of Python your package works on, which license your package is available under, and which operating systems your package will work on. For a complete list of classifiers, see https://pypi.org/classifiers/.

创建README.md

创建 README.md ，写上你准备写入的内容：

# Example Package

This is a simple example package. You can use
[Github-flavored Markdown](https://guides.github.com/features/mastering-markdown/)
to write your content.

创建LICENSE

比如使用MIT

Copyright (c) 2018 The Python Packaging Authority

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

生成发布包

接下来我们生成发布的软件包

1	$ python3 setup.py sdist bdist_wheel

这个命令会生成两个文件：

1
2
3

dist/
  example_pkg_YOUR_USERNAME_HERE-0.0.1-py3-none-any.whl
  example_pkg_YOUR_USERNAME_HERE-0.0.1.tar.gz

其中 tar.gz 文件为源码，.whl为编译的包。

比较新的pip可以直接按照whl格式的编译包。

一般而言，我们都需要上次源码以及编译包。

参考

代码参考 https://www.github.com/shaoguangleo/atas/python