LICENSE是表示该项目所遵循的开源协议必威:,第

亲自动手写一个python库(二),动手写python库

引言

经过上一节中所述,我们搭建好了一个Python环境用于库开发,我们在这一节真正开始搭建一个库,并将其发布。

项目文档结构

首先我们先构建出自己项目的文档结构,首先是LICENSE和README.md,这两个文件并不是必要的,但是最好将其加上,方便别人了解你的项目。README.md是关于本项目的介绍,LICENSE是表示该项目所遵循的开源协议,一般MIT用的比较多,其他协议你可以百度谷歌了解一下。

接下来是打包库需要的一些文件,主要有MANIFEST.in和setup.py两个文件。MANIFEST.in表示打包时不会被自动包含进去的附加文件清单。setup.py是打包程序配置文件,需要设置一些选项。此外,setup.cfg是包含setup.py额外配置信息的文件,我没有用到这其中的设置,所以本项目中其是空的。

caafinder文件夹就是我们要写的Python程序,我们要注意这个文件夹里必须有__init__.py这个文件。

下面是一下setup.py的一些简单配置选项,详细请参考官方文档。

可以参考一下:

  • PyPA sample project这是一个官方示例库结构。

  • Python Packaging User Guide这是Python打包的官方英文文档。

关于模块

模块也就是库,我们自己写程序时,通常通过import XX来导入一个需要的模块,在Python中,一个py文件就是一个模块,如一个abc.py的文件就是一个名字叫abc的模块。

你也许还想到,如果不同的人编写的模块名相同怎么办?为了避免模块名冲突,Python又引入了按目录来组织模块的方法,称为包(Package),包是一个带有__init__.py的文件夹,如图中文档所示,我们有一个包caafinder,因为它的子级有一个__init__.py,包caafinder拥有database和workspace两个模块。__init__.py可以是空文件,也可以有Python代码,因为__init__.py本身就是一个模块,而它的模块名就是caafinder。

程序打包

通过执行下列语句来进行打包:

其中xxx可以是下列几种方式中其中一个:

举个例子:

此时在根目录出现了dist文件夹,里面有name-version.tar.gz这个文件,这就是我们要发布到PyPI的压缩包了。

-

发布到PyPI

首先我们需要在PyPI上注册一个帐号,并在本地用户根目录下创建文件~/.pypirc,这样以后就不需要输入帐号密码了。

接下来,需要在PyPI网站上注册一个项目,网站提供三种方式注册,选择一种即可,最简单的是通过上传打包时生成的PKG-INFO文件,生成项目信息。此步骤只需在第一次发布时操作。

接下来就是最后一步,上传打包好的库。我们这里是用twine,如果环境中没有安装,需要先采用pip install twine安装即可。

此时在网页上就可以看到自己的源代码包啦,并且可以通过使用pip install packagename,就可以使用我们自己写的Python库了。

祝大家玩的开心,希望大家能到Github上帮忙点个赞。

作者:Gutierrez

来源:


————广告时间————

马哥教育2018年Python自动化运维开发实战面授班2018年3月5号开班,马哥联合BAT、豆瓣等一线互联网Python开发达人,根据目前企业需求的Python开发人才进行了深度定制,加入了大量一线互联网公司:大众点评、饿了么、腾讯等生产环境真是项目,课程由浅入深,从Python基础到Python高级,让你融汇贯通Python基础理论,手把手教学让你具备Python自动化开发需要的前端界面开发、Web框架、大监控系统、CMDB系统、认证堡垒机、自动化流程平台六大实战能力,让你从0开始蜕变成Hold住年薪20万的Python自动化开发人才

扫描二维码领取学习资料**

更多Python好文请点击【阅读原文】哦

↓↓↓

打包发布Python模块的方法详解,python详解

前言

昨天把自己的VASP文件处理库进行了打包并上传到PyPI,现在可以直接通过pip和easy_install来安装VASPy啦(同时欢迎使用VASP做计算化学的童鞋们加星和参与进来),

VASPy的GotHub地址:
VASPy的PyPI地址:

由于自己的记性真是不咋地,怕时间久了就忘了,于是在这里趁热打铁以自己的VASPy程序为例对python的打包和上传进行下总结。

VASPy包文件结构

首先写贴上来VASPy包的整个文件结构, 后面的内容都是以此为例进行说明:

VASPy/
├── LICENSE
├── MANIFEST
├── MANIFEST.in
├── README.rst
├── requirements.txt
├── scripts
│  ├── change_incar_parameters.py
│  ├── create_inputs.py
│  └── ...
├── setup.cfg
├── setup.py
├── tests
│  ├── incar_test.py
│  ├── __init__.py
│  ├── oszicar_test.py
│  ├── outcar_test.py
│  ├── testdata
│  │  ├── CONTCAR
│  │  ├── DOS_SUM
│  │  ├── ELFCAR
│  │  └── ...
│  └── ...
└── vaspy
  ├── __init__.py
  ├── iter.py
  ├── matstudio.py
  └── ...

4 directories, 54 files

打包和安装第三方包的工具

这里我们需要借助setuptools和pip等工具进行自己包的打包和发布以及安装,如果需要构建成wheel还需要安装wheel模块。如果python版本>=2.7.9或者>=3.4,setuptools和pip是已经安装好的,可能需要进行更新到最新版本

pip install -U pip setuptools

可以使用包管理工具,例如

yum install pip
sudo apt-get install pip

通过get-pip.py脚本安装,如果检测到没有安装wheel和setuptools也会自动安装

python get-pip.py

具体的工具安装和介绍就不多讲了,可以请参考requirements for installing packages

包中不同文件的作用

setup.py

这个文件是打包整个项目最重要的文件,它里面提供了两个主要的功能:

setup()函数,此函数的参数指定了如何配置自己的项目。
命令行工具,包括打包,测试,发布等。可以通过下面的命令查看;

python setup.py --help-commands

setup.cfg

此文件包含了构建时候的一些默认参数例如构建bdist_wheel的时候的--universal参数

[bdist_wheel]
universal=1

这样每次打包的时候就会默认使用--universal参数了,效果类似:

python setup.py bdist_wheel --universal

README.rst

这个最初我是用markdown写的,打包发布到PyPI之后发现PyPI不支持markdown的渲染,页面上真是一片混乱,于是就用reStrutruedText的语法重新写了一遍。毕竟标记语言语法基本上可以秒上手,实在不行找个模板比葫芦画瓢就行。
reStructureText的语法规则可参考官方文档:Quick reStructuredText

其实还有一种方法就是使用pandoc将markdown转换成rst格式,一种省事的方式就是使用pyandoc模块在发布的时候自动转换。
具体方法可以参考:Use Markdown README's in Python modules

MANIFEST.in

此文件在打包的时候告诉setuptools还需要额外打包那些文件,例如我VASPy中的单元测试的测试数据文件我就使用这个文件将其包含进来。当然README,LICENSE这些也可以通过它来一起打包进来。
下面是我自己的MANIFEST.in的内容:

include README.rst
include requirements.txt
include LICENSE
recursive-include scripts *
recursive-include tests *

具体的语法规则可以参考:The MANIFEST.in template

vaspy/

此文件夹就是vaspy源代码所在的包。

tests/

此文件夹也是一个子包,包含了单元测试脚本,为了能使用python setup.py test进行单元测试,特地添加了__init__.pys使其成为一个包。

setup()的参数

这里只介绍我使用的几个参数,其他参数的具体使用可以参考:

name

versions = "vaspy"

是整个项目的名字,打包后会使用此名字和版本号。

version

from vaspy import __version__
version = __version__

description

是一个简短的对项目的描述,一般一句话就好,会显示在pypi上名字下端。

long_description

是一个长的描述,相当于对项目的一个简洁,如果此字符串是rst格式的,PyPI会自动渲染成HTML显示。这里可以直接读取README.rst中的内容。

url

包的连接,通常为GitHub上的链接或者readthedocs的链接。

packages

需要包含的子包列表,setuptools提供了find_packages()帮助我们在根路径下寻找包,这个函数distutil是没有的。

setup_requires

这个参数定义了VASPy安装和顺利运行所需要的其他依赖项(最基本的),使用pip安装的时候会对这些依赖项进行安装。
关于这个参数与requirements.txt的区别可以参考:install_requires vs Requirements files

classifier

这个参数提供了一系列的分类,在PyPI上会将其放入不同的目录中讲项目进行归类。
具体的categories的名称和规则参考:

test_suite

这个参数可以帮助我们使用

python setup.py test

来跑单元测试,再也不需要单独再写一个脚本例如run_tests.py这样来跑单元测试了。
此参数的官方解释:

A string naming a unittest.TestCase subclass (or a package or module containing one or more of them, or a method of such a subclass), or naming a function that can be called with no arguments and returns a unittest.TestSuite. If the named suite is a module, and the module has an additional_tests() function, it is called and the results are added to the tests to be run. If the named suite is a package, any submodules and subpackages are recursively added to the overall test suite.

也就是说这个参数可以接受多种类型的参数:

接收unittest.TestCase子类,我们可以讲所有单元测试写入一个测试用例中,然后import进来,再传你给test_suite
接收函数对象,此函数对象没有任何参数,且返回一个unittest.TestSuite.这样我们就可以单独写一个函数,将多个测试用例合并成一个suite然后返回,然后再将函数import进来传给test_suite。

模块和包名称,我就是使用这种方式,之前自己的测试都是分开的多个脚本,这样我添加一个__init__.py就可以将其变成一个包,将包名传给test_suite,setuptools就会神奇的将此包下的所有测试全部跑一边,这样我以后再加测试脚本的时候直接就添加新的脚本就好了,其他的都不需要改动了。

运行效果:

[email protected]:/mnt/d/Dropbox/Code/CentOS_code/VASPy$ python setup.py test
running test
running egg_info
creating vaspy.egg-info
writing vaspy.egg-info/PKG-INFO
writing top-level names to vaspy.egg-info/top_level.txt
writing dependency_links to vaspy.egg-info/dependency_links.txt
writing manifest file 'vaspy.egg-info/SOURCES.txt'
reading manifest file 'vaspy.egg-info/SOURCES.txt'
reading manifest template 'MANIFEST.in'
writing manifest file 'vaspy.egg-info/SOURCES.txt'
running build_ext
test_compare (tests.incar_test.InCarTest)
Make sure we can compare two InCar objects correctly. ... ok
test_eq (tests.incar_test.InCarTest)
Test __eq__() function. ... ok
...
此处省略若干输出

----------------------------------------------------------------------
Ran 22 tests in 3.574s

OK

发布自己的python包

  1. 首先先去PyPI注册帐号

  2. 配置~/.pypirc如下:

    [distutils] index-servers = pypi pypitest

    [pypi] username:ShaoZhengjiang password:mypassword

    [pypitest] username:ShaoZhengjiang password:mypassword

  3. 然后注册并上传自己的包到测试服务器

pypi提供了一个测试服务器,我们可以在这个测试服务器上做测试。

python setup.py register -r pypitest

然后

python setup.py sdist upload -r pypitest

若没有问题我们应该不会得到任何错误。

  1. 上传至PyPI

若上面的测试成功,我们就可以按照相同的步骤将包注册并上传。

python setup.py register -r pypi
python setup.py sdist upload -r pypi

Ok,之后我们就可以在PyPI(

前言 昨天把自己的VASP文件处理库进行了打包并上传到PyPI,现在可以直接通过pip和easy_install来安装...

Publishing your app¶

2.10.7 如何在virtualenv中安装python的包

前面,我们安装polls应用作为一个用户库,它有一些缺点:

  • 修改用户库会影响到你系统上的其它Python软件
  • 你无法同时运行此包的多个版本

解决这个问题最好的办法就是使用virtualenv。详见

Installing some prerequisites¶

2.12 编写你的第一个Django补丁

**待翻译!**

已经同步到gitbook,想阅读的请转到gitbook: Django 1.10 中文文档

2.10.4 打包你的app

打包的意思是让你的app具有一种特殊的格式,使得它更容易被安装和使用。

  1. 首先,在Django项目外面,为你的polls应用,准备一个父目录,取名django-polls;

    为你的app选择一个合适的名字:
    在取名前,去PYPI搜索一下是否有重名或冲突的包已经存在。建议给包名加上“django-”的前缀。名字中最后一个圆点的后面部分在INSTALLED_APPS中一定要独一无二,不能和任何Django的contrib packages中的重名,例如auth、admin、messages等等你。

  2. 拷贝polls目录到该目录内;

  3. 创建一个文件django-polls/README.rst,写入下面的内容:

Polls

Polls is a simple Django app to conduct Web-based polls. For each
question, visitors can choose between a fixed number of answers.
Detailed documentation is in the "docs" directory.
Quick start
-----------
64 Chapter 2. Getting started
Django Documentation, Release 1.10.2a1
1. Add "polls" to your INSTALLED_APPS setting like this::
INSTALLED_APPS = [
...
'polls',
]
2. Include the polls URLconf in your project urls.py like this::
url(r'^polls/', include('polls.urls')),
3. Run `python manage.py migrate` to create the polls models.
4. Start the development server and visit http://127.0.0.1:8000/admin/
to create a poll (you'll need the Admin app enabled).
5. Visit http://127.0.0.1:8000/polls/ to participate in the poll.
  1. 创建一个django-polls/LICENSE版权申明文件。大多数Django相关的app都基于BSD版权。
  2. 接下来创建一个setup.py文件,用于编译和安装app。如何创建这个,请前往setuptools的官方文档获取详细的教程,本文不涉及。具体内容如下:

django-polls/setup.py

import os
from setuptools import find_packages, setup

with open(os.path.join(os.path.dirname(__file__), 'README.rst')) as readme:
    README = readme.read()

# allow setup.py to be run from any path
os.chdir(os.path.normpath(os.path.join(os.path.abspath(__file__), os.pardir)))

setup(
    name='django-polls',
    version='0.1',
    packages=find_packages(),
    include_package_data=True,
    license='BSD License', # example license
    description='A simple Django app to conduct Web-based polls.',
    long_description=README,
    url='https://www.example.com/',
    author='Your Name',
    author_email='yourname@example.com',
    classifiers=[
        'Environment :: Web Environment',
        'Framework :: Django',
        'Framework :: Django :: X.Y', # replace "X.Y" as appropriate
        'Intended Audience :: Developers',
        'License :: OSI Approved :: BSD License', # example license
        'Operating System :: OS Independent',
        'Programming Language :: Python',
        # Replace these appropriately if you are stuck on Python 2.
        'Programming Language :: Python :: 3',
        'Programming Language :: Python :: 3.4',
        'Programming Language :: Python :: 3.5',
        'Topic :: Internet :: WWW/HTTP',
        'Topic :: Internet :: WWW/HTTP :: Dynamic Content',
    ],
)
  1. 默认只有python的模块和包会被打包进我们的app内。为了包含一些附加的文件,需要创建一个MANIFEST.in文件。为了将静态文件,模板等等非python语言编写的文件打包入内,我们需要在django-polls/MANIFEST.in文件内写入:
    include LICENSE
    include README.rst
    recursive-include polls/static *
    recursive-include polls/templates *
  1. 该步骤可选,但是强烈推荐,将详细的说明文档一起打包。创建一个空的目录django-polls/docs,用于放置你的app相关文档。同时不要忘了,在django-polls/MANIFEST.in文件内写入一行recursive-include docs *。需要注意的是,如果docs目录是空的,那么它不会被打包进去。当然,许多apps通过在线的网站提供文档阅读。
  2. 在你的django-polls目录内,运行python setup.py sdist命令。这将会创建一个dist目录,并编译成功你的新包,django-polls-0.1.tar.gz。

可重用很重要¶

It’s a lot of work to design, build, test and maintain a web application. Many Python and Django projects share common problems. Wouldn’t it be great if we could save some of this repeated work?

设计、构建、测试和维护一个网页应用需要做许多工作。许多Python 和 Django 项目都会遇到一些共性问题。如果我们能不重复的造轮子,岂不是很棒。

Reusability is the way of life in Python. The Python Package Index (PyPI) has a vast range of packages you can use in your own Python programs. Check out Django Packages for existing reusable apps you could incorporate in your project. Django itself is also just a Python package. This means that you can take existing Python packages or Django apps and compose them into your own web project. You only need to write the parts that make your project unique.

可重用性在Python 中是一种常见的方式。
Python包索引 (PyPI)网站 具有大量的包,你可以在你自己的Python程序中使用。
查阅一下Django Packages中已经存在的可重用的应用,你可以把它们放到你的项目中。
Django 自身也只是一个Python 包。
这意味着你可以获取已经存在的Python包和Django应用并将它们融合到你自己的网页项目。你只需要编写你项目的独有的部分代码。

Let’s say you were starting a new project that needed a polls app like the one we’ve been working on. How do you make this app reusable? Luckily, you’re well on the way already. In Tutorial 3, we saw how we could decouple polls from the project-level URLconf using an include. In this tutorial, we’ll take further steps to make the app easy to use in new projects and ready to publish for others to install and use.

假如说你正在开始一个新的项目,需要一个像我们正在编写的投票应用。你如何让该应用可重用?幸运的是,其实你已经在这条道路上了。在教程 3中,我们看到我们可以如何使用include将投票应用从项目级别的URLconf 解耦。在本教程中,我们将进一步让你的应用更容易复用到新的项目中,而且可以发布给其它人安装和使用。

2.10.6 发布你的app

你可以:

  • 通过邮件的形式发送给朋友
  • 上传包到你的网站
  • 推送到一个公开的仓库,例如PyPI,github等

https://packaging.python.org/distributing/#uploading-your-project-to-pypi是如何上传到PyPI的教程。

Package? App?

A Python package provides a way of grouping related Python code for easy reuse. A package contains one or more files of Python code (also known as “modules”).

Python package提供了可让一组相关性代码复用的方式,一个包包含一个或许多python文件(也就是我们常说的模块)

A package can be imported with import foo.bar or from foo import bar. For a directory (like polls) to form a package, it must contain a special file init.py, even if this file is empty.

一个包可以通过import foo.bar or from foo import bar方法导入。如果是一个目录(如polls)要做成一个包,必需要包含一个特殊文件init.py,即使这个文件是空。

A Django application is just a Python package that is specifically intended for use in a Django project. An application may use common Django conventions, such as having models, tests, urls, and views submodules.

一个Django应用就是仅仅用于Django项目中Python包。一个应用可以遵循常见的Django 约定,例如具有models、tests、urls和views 子模块。

Later on we use the term packaging to describe the process of making a Python package easy for others to install. It can be a little confusing, we know.

将python包变的让其他人更易于安装的过程,我们称之为打包。目前对于你来说可能有点困惑。

2.10.5 使用你自己的包

在安装包的时候,最好是以个人身份安装,而不是全系统范围的身份。这样可以有效减少给别的用户带去的影响或被别的用户影响。当然,最好的方式是在virtualenv环境下,类似隔离的沙盒环境。

  1. 使用pip安装:pip install --user django-polls/dist/django-polls-0.1.tar.gz
  2. 现在你可以在项目中使用这个包了
  3. 卸载:pip uninstall django-polls

本文由必威发布于必威-运维,转载请注明出处:LICENSE是表示该项目所遵循的开源协议必威:,第

相关阅读