项目结构

知识点

创建项目，编写 __init__ 文件
使用 setuptools 模块，编写 setup.py 和 MANIFEST.in 文件
创建源文件的发布版本
项目注册&上传到 PyPI

实验步骤

本实验阐述了一个完整的 Python 项目结构，你可以使用什么样的目录布局以及怎样发布软件到网络上。

我们的实验项目名为 factorial。

$ mkdir factorial

$ cd factorial/

1. 主代码

我们给将要创建的 Python 模块取名为 myfact，因此我们下一步创建 myfact 目录。

$ mkdir myfact

$ cd myfact/

主代码将在 fact.py 文件里面。

"myfact module"

def factorial(num):

    """

    返回给定数字的阶乘值

    :arg num: 我们将计算其阶乘的整数值

    :return: 阶乘值，若传递的参数为负数，则为 -1

    """

    if num >= 0:

        if num == 0:

            return 1

        return num * factorial(num -1)

    else:

        return -1

我们还有模块的 __init__.py 文件，内容如下：

from fact import factorial

__all__ = [factorial, ]

我们还在 factorial 目录下添加了一个 README.rst 文件。因此，目录结构看起来像下面这样：

2. MANIFEST.in

现在我们要写一个 MANIFEST.in 文件，它用来在使用 sdist 命令的时候找出将成为项目源代码压缩包一部分的所有文件。

include *.py

include README.rst

如果你想要排除某些文件，你可以在这个文件中使用 exclude 语句。

3. 安装 python-setuptools 包

我们使用 virtualenv（这里不示范步骤）。

$ sudo pip3 install setuptools

4. setup.py

最终我们需要写一个 setup.py，用来创建源代码压缩包或安装软件。

#!/usr/bin/env python3

"""Factorial project"""

from setuptools import find_packages, setup

setup(name = 'factorial',

    version = '0.1',

    description = "Factorial module.",

    long_description = "A test module for our book.",

    platforms = ["Linux"],

    author="ShiYanLou",

    author_email="support@shiyanlou.com",

    url="https://www.shiyanlou.com/courses/596",

    license = "MIT",

    packages=find_packages()

    )

name 是项目名称，version 是发布版本，description 和 long_description 分别是项目介绍，项目长描述。platforms 是此模块的支持平台列表。find_packages() 是一个能在你源目录下找到所有模块的特殊函数，packaging docs。

4.1. setup.py 用例

要创建一个源文件发布版本，执行以下命令。

$ python3 setup.py sdist

执行完毕会返回类似下面的信息：

running sdist

running egg_info

creating factorial.egg-info

writing factorial.egg-info/PKG-INFO

writing top-level names to factorial.egg-info/top_level.txt

writing dependency_links to factorial.egg-info/dependency_links.txt

writing manifest file 'factorial.egg-info/SOURCES.txt'

reading manifest file 'factorial.egg-info/SOURCES.txt'

reading manifest template 'MANIFEST.in'

writing manifest file 'factorial.egg-info/SOURCES.txt'

running check

creating factorial-0.1

creating factorial-0.1/factorial.egg-info

creating factorial-0.1/myfact

making hard links in factorial-0.1...

hard linking MANIFEST.in -> factorial-0.1

hard linking README.rst -> factorial-0.1

hard linking setup.py -> factorial-0.1

hard linking factorial.egg-info/PKG-INFO -> factorial-0.1/factorial.egg-info

hard linking factorial.egg-info/SOURCES.txt -> factorial-0.1/factorial.egg-info

hard linking factorial.egg-info/dependency_links.txt -> factorial-0.1/factorial.egg-info

hard linking factorial.egg-info/top_level.txt -> factorial-0.1/factorial.egg-info

hard linking myfact/__init__.py -> factorial-0.1/myfact

hard linking myfact/fact.py -> factorial-0.1/myfact

Writing factorial-0.1/setup.cfg

creating dist

Creating tar archive

removing 'factorial-0.1' (and everything under it)

我们能在 dist 目录下看到一个 tar 压缩包。

$ ls dist/

factorial-0.1.tar.gz

记住尝试安装代码时使用 virtualenv。

执行下面的命令从源代码安装。

$ sudo python3 setup.py install

学习更多可前往 packaging.python.org。

5. Python Package Index (PyPI)

你还记得我们经常使用的 pip 命令吗？有没有想过这些包是从哪里来的？答案是 PyPI。这是 Python 的软件包管理系统。

为了实验，我们会使用 PyPI 的测试服务器 https://testpypi.python.org/pypi。

5.1. 创建账号

首先在这个链接注册账号。你会收到带有链接的邮件，点击这个链接确认你的注册。

创建 ~/.pypirc 文件，存放你的账号详细信息，其内容格式如下：

[distutils]

index-servers =

    pypi

[pypi]

repository: https://testpypi.python.org/pypi

username: <username>

password: <password>

替换 <username> 和 <password> 为您新创建的帐户的详细信息。

记得在 setup.py 中更改项目的名称为其它的名字来测试下面的指令。

5.2. 注册项目

下一步我们会注册我们的项目到 PyPI 服务。这通过 register 命令完成。

我们也会使用 -r 把它指向测试服务器。

$ python3 setup.py register -r https://testpypi.python.org/pypi

执行完毕会返回类似下面的信息：

running register

running egg_info

writing factorial.egg-info/PKG-INFO

writing top-level names to factorial.egg-info/top_level.txt

writing dependency_links to factorial.egg-info/dependency_links.txt

reading manifest file 'factorial.egg-info/SOURCES.txt'

reading manifest template 'MANIFEST.in'

writing manifest file 'factorial.egg-info/SOURCES.txt'

running check

Registering factorial to https://testpypi.python.org/pypi

Server response (200): OK

5.3. 上传项目

最后我们使用 upload 命令把我们的项目上传到 PyPI 服务器。记住此命令需要您生成源代码/二进制分发文件后立即调用。

$ python3 setup.py sdist upload -r https://testpypi.python.org/pypi

返回如下信息：

running sdist

running egg_info

writing factorial.egg-info/PKG-INFO

writing top-level names to factorial.egg-info/top_level.txt

writing dependency_links to factorial.egg-info/dependency_links.txt

reading manifest file 'factorial.egg-info/SOURCES.txt'

reading manifest template 'MANIFEST.in'

writing manifest file 'factorial.egg-info/SOURCES.txt'

running check

creating factorial-0.1

creating factorial-0.1/factorial.egg-info

creating factorial-0.1/myfact

making hard links in factorial-0.1...

hard linking MANIFEST.in -> factorial-0.1

hard linking README.rst -> factorial-0.1

hard linking setup.py -> factorial-0.1

hard linking factorial.egg-info/PKG-INFO -> factorial-0.1/factorial.egg-info

hard linking factorial.egg-info/SOURCES.txt -> factorial-0.1/factorial.egg-info

hard linking factorial.egg-info/dependency_links.txt -> factorial-0.1/factorial.egg-info

hard linking factorial.egg-info/top_level.txt -> factorial-0.1/factorial.egg-info

hard linking myfact/__init__.py -> factorial-0.1/myfact

hard linking myfact/fact.py -> factorial-0.1/myfact

Writing factorial-0.1/setup.cfg

Creating tar archive

removing 'factorial-0.1' (and everything under it)

running upload

Submitting dist/factorial-0.1.tar.gz to https://testpypi.python.org/pypi

Server response (200): OK

现在如果你浏览这个页面，你会发现你的项目已经准备好被别人使用了。

总结

本实验使用了 setuptools 包，并完成了较为完整的项目创建&发布流程，最后还将项目发布到了网络（PyPI）上。

巴特西

python的项目结构