六个步骤,封装你喜爱的Python代码包

开发 后端
假设你很喜欢用同一段Python代码,里面有几个相关的小型函数,或者是含有几百行代码的中型模块。程序员可能会把它复制到不同的项目或存储库中,或者从特别设置的实用工具代码文件夹中导入这段代码。

 假设你很喜欢用同一段Python代码,里面有几个相关的小型函数,或者是含有几百行代码的中型模块。程序员可能会把它复制到不同的项目或存储库中,或者从特别设置的实用工具代码文件夹中导入这段代码。

[[278378]]

这很正常。程序员在编写代码的过程中都会不断积累这些个性化的小工具。相比其他编程语言来说,Python更容易积累这些语句——这些代码非常实用。

如果无需复制,就可以轻松导入自己开发的小工具,并进行更新和维护,岂不是更好吗?如果不依赖于特定的文件或路径,让这些代码在不同的环境、机器和语境中都适用?如果可以将这些个性化工具版本化,并使相关代码清楚地反映出其依赖性呢?如果这个工具能为大众所用呢?

没错,它都可以做到。

当然,这个概念不是第一次提了。这就是通常在编程语言中使用模块、包和库的原因,特别是在Python的开发环境中。它的实现可使Python功能更加强大;只需简单的pip install 和 import就能获得BeautifulSoup的html解析功能或pandas的数据帧处理功能。

另外,人人都可以将自己的代码在PyPI上编写和发布(PyPI是Python包的官方索引:http://pypi.python.org/pypi),使它们与sklearn、requests或delorean(都是非常实用、流行的Python包)一样简单易得。以下是它的几点优势:

  • 即使只有很少人使用,共享自己的代码仍是一件很有趣的事;程序员可以在工作、社群活动或求职面试中分享并展示自己的劳动成果。
  • 通过强制性地整理和记录代码,公开给同行进行评价,从而改进代码。
  • 它还能弥补社群的不足。你会惊讶地发现,很多人会注意到你的序列化十分高效,比如将HTTP报头序列化到JSON。或者发现自己创建的用来验证输入MongoDB查询文档修饰符的工具有多么实用。

心动了吗?忘记那个旧的Python模块,开始制作小型Python包吧。

 

图1: Python dust

 

步骤一:命名

首先是命名。好的名字通常比较简短,便于在pip install 或 import 完成之后输入(尽管现在已经出现了“自动输入”);还要包含足够的信息便于理解,或者在安装完成后之后提示其中的内容。

requests负责处理HTTP请求、delorean负责日期和时间,sklearn负责提供机器学习框架,这些都是很好的例子。在为pandas管道包(由于pandas 通常以pd这样较短别名导入,故使用pdpipe:https://github.com/shaypal5/pdpipe)和缓存包(cachier:https://github.com/shaypal5/cachier)命名时,笔者也尝试过这些例子。

不过老实说,这些并不是固守的规则。流行的Python包都有pandas、 keras、 django、 boto、 jinja、 flask 和 pytorch等名称,大家能记住这些名字,所以读者也可以使用任何简短且可读的名称(例如,由于可读性问题,笔者将“Scikit-Learn Wrappers for FastText”缩写成了skift)。本文以chocobo为例。

步骤二:确定代码包的基本结构

接下来,通过几个简短的步骤,制作一种通用的结构:

1.用代码包的准确名称创建一个Github存储库,不要使用驼峰式或过多的个人发挥。然后在本地进行复制。

2.在该存储库中新建一个文件夹,用代码包的准确名称命名;这就是保存代码包的文件夹。这是一种规范,只需记住外部的chocobo 文件夹(在本例中)就是存储库的文件夹,而内部的chocobo 文件夹是包的文件夹。

3.将自己的模块和涉及到的任何其他模块放在内部的chocobo文件夹中。如果存在缺失的部分,请添加__init__.py 文件。

4.将用户直接调用的重要对象(通常是函数)从各自的模块中导入至__init__.py文件。有了代码包的命名空间,就可以使用这些函数、分类和变量了。如果愿意,也可以使用代码包的API。

5.虽然不是强制规定,笔者强烈建议在代码包或在存储库的根目录中都应包含一个 .gitignore 文件。

示例:https://github.com/github/gitignore/blob/master/Python.gitignore

现在有了一个结构,可以添加不同类型的文件组成代码包;内部文件夹保存的是包的代码,外部文件夹保存的是辅助包文件和其他与存储库相关的文件。

因此,初始模块chocobo.py如下所示:

  1. """My chocobo cooking script.""" 
  2. import os 
  3. def chocobo_roast(num_guests, hotness_level): 
  4.  # amazing python code here 

新建存储库文件夹如下所示:

  1. chocobo/ 
  2.  chocobo/ 
  3.  __init__.py 
  4.  chocobo.py 
  5.  .gitignore 

__init__.py 文件应如下所示:

  1. """chocobo is a python package for delicious Chocobo recipes.""" 
  2. from .chocobo import ( 
  3.  chocobo_roast, 

那么在完成封装之后,chocobo包可以有这样的使用方法:

  1. """I'm a script or a different package using chocobo.""" 
  2. import chococbo 
  3. def my_feast(num_guests): 
  4.  snacks = bobbish() 
  5.  main_course = chocobo.chocobo_roast(num_guests, 0) 
  6.  dressing = szechuan_chicken_mcnugget_sauce() 

以上就是一些要点。

步骤三:许可问题

使用共享许可发布代码是较为可取的;如果要将自己的代码公开分享,程序员会想要在保留版权的前提下得到重用代码的许可,或者让那些扩展自己代码的人保证衍生代码可以自由使用。获得许可能轻松解决这些问题。

对于无足轻重的小项目,可以考虑MIT许可(https://choosealicense.com/licenses/mit/)。choosealicense.com(https://choosealicense.com/)提供了很多GitHub和开源社区中的实用建议。

无论选择哪种许可,都比根本不用要好。很多时候,在没有许可的情况下公开代码还不如不公开;如果程序员不明确自己对代码的所有权,大多数公司会因为可能造成的法律纠纷而放弃,从而失去许多潜在用户。

选择许可后,在存储库中创建LICENSE许可文件(不需要文件扩展名),并导入所选许可的确切文本。

步骤四:安装文件

现在创建Python封装工具所需的基本文件(以setuptools为例);setup.py.setup.py 包含了构建和发行时使用的实际指令。

下面是一个初始模板(别担心,稍后会进行详细检查)

  1. """Setup for the chocobo package.""" 
  2. import setuptools 
  3. with open('README.md'as f: 
  4.  README = f.read() 
  5. setuptools.setup( 
  6.  author="Shay Palachy"
  7.  author_email="shay.palachy@gmail.com"
  8.  name='chocobo'
  9.  license="MIT"
  10.  description='chocobo is a python package for delicious chocobo recipes.'
  11.  version='v0.0.3'
  12.  long_description=README, 
  13.  url='https://github.com/shaypal5/chocobo'
  14.  packages=setuptools.find_packages(), 
  15.  python_requires=">=3.5"
  16.  install_requires=['requests'], 
  17.  classifiers=[ 
  18.  # Trove classifiers 
  19.  # (https://pypi.python.org/pypi?%3Aaction=list_classifiers) 
  20.  'Development Status :: 4 - Beta'
  21.  'License :: OSI Approved :: MIT License'
  22.  'Programming Language :: Python'
  23.  'Programming Language :: Python :: 3.5'
  24.  'Programming Language :: Python :: 3.6'
  25.  'Topic :: Software Development :: Libraries'
  26.  'Topic :: Software Development :: Libraries :: Python Modules'
  27.  'Intended Audience :: Developers'
  28.  ], 

首先,导入setuptools。这是一个非常有用代码包,可轻松对Python包进行发行,即使它不包括在标准库中(类似的distutils是比不了的),它仍然是当今Python包发行的标准,应该牢记于心。本文只使用了setuptools包中的两个函数:setup和find_packagges。

在导入setuptools之后,调用setup()函数之前,只需将README.md 文件的内容读入到全局变量 README中即可。

然后只需通过以下变量调用setuptools.setup() 函数即可:

  • author:输入姓名。
  • author_email:输入邮箱。
  • name:代码包的名称,在本例中为“chocobo”。
  • license:在本例中为字符串“MIT”,或选择其他许可证。
  • description:代码包的简短介绍,控制在一行以内。例如:“chocobo代码包是制作美味chocobo的食谱”
  • version:表示封装的当前版本的字符串。笔者在之后的文章中会介绍更简洁的处理方法,但是目前,只需要在想要发布新版本时手动增加一个数字就可以了。通常的做法是将版本号前加入字母V,因此v1是第一个版本的版本字符串,但笔者建议将v0.0.1 视为等效版本字符串并使用此格式。后文将详细介绍这种做法的意义。
  • long_description:表示README的内容。该部分是代码包的详细描述。也就是该页面PyPI的内容(示例:https://pypi.org/project/pdpipe/)。
  • url:可链接到代码包的主页。如果读者没有专用的站点,那么存储库的URL是一个不错的选择。
  • packages: 又一次提到了setuptools!根据命令,这个参数获取要生成和发行/安装的所有代码包的名称数组。从技术上讲,可以直接使用[“chocobo”]这个名字,但是最好是将其通用化,并使用setuptools 函数,它能处理更复杂的包和存储库结构。有两个可选参数可以作为输入数据,where 和exclude,但在这里忽略不计。作为结果,where可链接至安装文件所在的目录,包括所有子目录,一般来说这样已经足够了。
  • python_requires: 如果你的电脑支持Python的所有版本,就不必顾及此参数。如果不能,应该选择一个适当的值。从技术上讲,笔者不赞成使用未经测试的版本,但保险期间目前我们可以进行适当的假设:

(1) 如果读者正在使用Python2,特别是Python2.7版本,可以得出以下两点结论:(a)你独树一帜,十分优秀(b)你的电脑配置只需支持Python2.7即可,所以可以使用“>=2.7”这个字符来编辑这个参数。另外,时代在进步,试试Python3吧。

(2) 如果读者使用的是Python3,那么任何Python版本都大于或等于用来开发代码包的版本。以此类推,如果使用的是Python3.5,那么应该设置成“>=3.5”。

  • install_requires: 此处列出的是所有非标准库代码包的使用前提。例如,如果chocobo 需要requests和 pytz 才能运行的话,那么该参数应设置为:[“ requests”,“pytz”]。
  • classifiers: 连同其他成千上万个代码包一起,你的代码包也会很快PyPI上线。为了进行区分,作者可以向PyPI提供一个列表,列出trove分类器来对每个版本进行分类,描述其用途、支持的系统和开发进度。然后,社区成员可以使用这些标准化的分类器,根据自己的需求来查找项目(尽管不确定谁会进行这项操作)。

这里有所有可能用到的分类器:https://pypi.python.org/pypi?%3Aaction=list_classifiers

建议从以下几个开始:

  • “Development Status :: 3 — Alpha”
  • “License :: OSI Approved :: MIT License”
  • “ Programming Language :: Python”
  • “ Programming Language :: Python :: 3.5”
  • “ Programming Language :: Python :: 3.6”
  • “ Programming Language :: Python :: 3.7”
  • “Topic :: Software Development :: Libraries”
  • “Topic :: Software Development :: Libraries :: Python Modules”
  • “Intended Audience :: Developers”

以上就是这一环节的全部内容。

[[278379]]

图2:选择trove分类器后的艾斯·文图拉

步骤五:建立发行文件

Python包位于发行文件中,这些文件会统一被上传到一个服务器中(通常是PyPI全局服务器),供公众下载。

本文不会详细介绍发行格式。笔者将使用标准方法(https://packaging.python.org/tutorials/packaging-projects/)构建两个文件:源发行文件(基本上包含了代码包)和wheel发行文件(wheel build distribution file)。

首先,确保安装了最新版本的setuptools 以及 wheel:

python3 -m pip install --user --upgrade setuptools wheel

要构建发行文件,只需在setup.py所在的存储库的根目录中运行以下命令:

python setup.py sdist bdist_wheel

在这一步,需要Python运行setup.py这个脚本,并向它发送两个参数,生成源文件(参数sdist),以及wheel工具来构建发行文件(参数bdist_wheel)。

运行此命令时,将在调用目录中创建三个文件夹: build, dist 和 chocobo.egg-info。对于.gitignore 文件来说,这三个可以忽略不计。如果这些目录已经存在(例如,该命令之前已经运行过了,最好用rm -rf build dist将这些目录删除掉,因为dist 下的任何有效代码包文件都将被上传。

要上传的两个文件位于dist 文件夹中:分别为chocobo-0.0.3-py-none.any.whl (构建发行;是一个wheel 文件)和chocobo-0.0.3.tar.gz (源发行;是一个压缩的tar 文件)。创建成功后,我们继续上传的步骤!

步骤六:上传

剩下的步骤就是将代码包上传到PyPI全局服务器!然而,用户必须先在PyPI网站上注册。按照注册的步骤填写用户名和密码。

如果想在上传到PyPI全局服务器之前测试包,程序员也可以在测试PyPI网站上注册一个用户。

现在,用于上传的Python包将在.pypirc文本文件中查找PyPI用户名和密码(通过PyPI服务器进行验证),该文件通常位于主文件夹中。创建后按如下所示进行填写(testpypi 部分视具体情况而定):

  1. [distutils] 
  2. index-servers = 
  3.  pypi 
  4.  testpypi 
  5. [pypi] 
  6. username: teapot48 
  7. password: myPYPIpassword 
  8. [testpypi] 
  9. repository: https://test.pypi.org/legacy/ 
  10. username: teapot48 
  11. password: MYtestPYPIpassword 

本文依照最新的方法将文件上传到PyPI服务器中,并使用twine(上传Python包的实用工具),而不是使用过时的python setup.py upload 。只需运行:

twine upload dist/*

如果想在PyPI服务器上进行测试,只需运行 twine upload — repository testpypi dist/*

不论如何,上传.whl 文件时都应该能看到一个进度条,上传.tar.gz 文档时应该也能看到一个进度条,然后上传就完成了。

现在可以在PyPI官方网站上看到自己的Python包页面了,大家也都能看到!

示例:https://pypi.org/project/birch/

 

图3:PyPI网站上包页面的示例

 

大功告成!

责任编辑:华轩 来源: 今日头条
相关推荐

2011-10-14 10:48:02

2017-10-09 18:54:20

前端Node.js贡献代码

2021-06-22 14:53:35

零信任网络安全网络攻击

2010-09-07 14:42:28

2011-11-18 10:04:46

Citrix私有云

2022-04-06 18:46:35

云战略云计算云服务

2019-02-20 13:25:28

无边界网络网络安全网络攻击

2021-10-21 08:00:00

开发技能技术

2010-08-30 11:28:53

DHCP工作过程

2023-05-22 15:53:06

JavaScrip代码素材

2024-01-16 15:19:29

Python内存

2022-10-17 09:15:37

2019-01-07 07:57:27

物联网运营效率IOT

2023-11-03 15:38:17

2019-07-05 09:00:00

软件开发数据

2022-09-08 09:01:41

CodePenJavaScripCSS

2022-11-25 12:25:27

Python代码编辑器

2017-05-03 10:45:47

Python运行效率窍门

2017-07-20 10:46:57

网页CDN加速缓存

2009-06-04 10:20:34

Hibernate持久化Java
点赞
收藏

51CTO技术栈公众号