Python 包索引可以在PyPI 门户的包页面中显示一个项目的readme 或者long_
description 的值。你可以用reStructuredText 标记来编写这个说明，它在上传时会转换为
HTML 格式。不幸的是，目前PyPI 上的文档标记只能使用reStructuredText。这在短期内也
不太可能改变。更有可能的是，如果warehouse 项目完全取代了当前的PyPI 实现，那么
将会支持其他标记语言。不幸的是，我们仍然不知道warehouse 的最终发布时间。
但是，许多开发者想要使用不同的标记语言，原因有很多。最常见的选择是Markdown，
它是GitHub 上默认的标记语言—目前大多数开源的Python 开发都是在GitHub 上。因此，
GitHub 和Markdown 的粉丝通常要么忽略这个问题，要么就提供两份独立的文档文本。提
供给PyPI 的说明要么是项目GitHub 页面上说明的简短版本，要么是在PyPI 上无法正常显
示的普通的无格式Markdown。
如果你想使用除了reStructuredText 之外的标记语言来编写项目的README，你仍然
可以用可读的形式将它作为PyPI 页面上的项目说明。诀窍是在将包上传到Python 包索引
时使用pypandoc 包将你使用的其他脚本语言转换成reStructuredText。同时准备readme
文件的简单内容作为备用（fallback）也很重要，这样即使用户没有安装pypandoc，安装
也不会失败，代码如下：
try:
from pypandoc import convert
def read_md(f):
return convert(f, ‘rst’)
except ImportError:
convert = None
print(
“warning: pypandoc module not found, could not convert
Markdown to RST”
)
def read_md(f):
return open(f, ‘r’).read() # noqa
README = os.path.join(os.path.dirname(file), ‘README.md’)
setup(
name=‘some-package’,
long_description=read_md(README),
…
)
管理依赖
许多项目需要安装和/或使用一些外部包。如果依赖列表很长的话，就会出现一个问题：
如何管理依赖？在大多数情况下答案很简单。不要过度设计（over-engineer）问题。保持简
单，并在setup.py 脚本中明确提供依赖列表，代码如下：
from setuptools import setup
setup(
name=‘some-package’,
install_requires=[‘falcon’, ‘requests’, ‘delorean’]
…
)
有些Python 开发者喜欢使用requirements.txt 文件来追踪包的依赖列表。在某些
情况下，你可能会找到这么做的原因，但在大多数情况下，这是项目代码没有正确打包的
时代遗留的问题。无论如何，即使像Celery 这样著名的项目也仍然坚持使用这一约定。因
此，如果你不愿意改变习惯或者不知何故被迫使用requirements.txt 文件，那么至少
要将其做对。下面是从requirements.txt 文件读取依赖列表的常见做法之一：
from setuptools import setup
import os
def strip_comments(l):
return l.split(‘#’, 1)[0].strip()
def reqs(*f):
return list(filter(None, [strip_comments(l) for l in open(
os.path.join(os.getcwd(), *f)).readlines()]))
setup(
name=‘some-package’,
install_requires=reqs(‘requirements.txt’)
…
)
