python三方包与模块

一、包管理项目历史

1. distutlis
   • 标准库的一部分，能处理简单包的安装
   • 通过setup.py进行安装
2. setuptools
   • 包安装标准
   • 自带一个easy_install安装脚本，后来被pip安装脚本代替
   • 引入了.egg格式，后来出现更好的.whl格式代替它

二、常见已发布三方包和模块形式

包管理项目：https://packaging.python.org/en/latest/key_projects/

1. 源码

   • 单文件模块
   • 多文件模块（由包管理工具发布的项目）
     • 基于distutils发布的项目特点：包含setup.py文件
     • setuptool也是基于distutils

2. .egg

   • setuptools引入的一种格式
   • setuptools可以识别安装它
3. .whl
   • 本质是.zip
   • 是为了替代.egg

三、安装方式概念

1. 本地安装：

   • 单文件模块：直接拷贝到相关文件夹

   • 对于带setup.py：通过setup.py脚本进行安装即可

   • .egg文件：使用setuptools的自带的安装脚本easy_install进行安装

   • .whl：使用pip进行安装

2. 远程安装：使用easy_install、pip、pycharm

3. 安装源：

• python官方：https://pypi.org/sample
• 豆瓣：https://pypi.douban.com/simple/
• 阿里：http://mirrors.aliyun.com/pypi/simple/
• 中国科技大学：https://pypi.mirrors.ustc.edu.cn/simple/
• 清华：https://pypi.tuna.tsinghua.edu.cn/simple/

四、本地安装（在本地下载好模块或者压缩包）

1. 单文件模块

   • 直接拷贝到相关文件夹即可
   • 存放位置：sys.path中所包含的路径都可以，一般存放在python的Lib/site-packages下

2. 带setup.py的文件

   • 打开命令行工具

   • 切换到setup.py所在目录下

   • 执行命令

     python setup.py build
     # python 2.x
     python setup.py install
     # python 3.x
     python3 setup.py install

   • 注意：

     • 如果项目是distutils打包的，上述命令直接使用，因为distutils是python自带模块，不需要安装
     • 如果项目是setuptools打包的，上述命令可能报错，因为setuptools属于三方模块，不是标准模块，需要安装再使用
     • 离线安装，可能依赖第三方包，还需要联网

3. .egg(现在pypi官网基本上没有了，了解)

   • 使用setuptools自带的安装脚本easy_install进行安装，需要先安装setuptools

   • 语法

     easy_install  xxx.egg

4. .whl

   • 使用easy_install 安装（过时了，新的setuptools已经没有easy_install.py文件）

   • pip安装

     • 安装pip

       • 远程：

         easy_install  pip

       • 本地：

         # .egg .whl .tar.gz
         # 不建议过时了
         easy_install  xxx
         
         # 使用setuptools方式带有setup.py的pip
         # python 2.x
         python setup.py install
         # python 3.x
         python3 setup.py install

     • pip语法

       pip install xxx.whl

五、远程安装（自动从远程地址检索下载安装）

1. 使用easy_install安装

   easy_install  xxx

2. 使用pip安装

   pip install xxx

3. 从远程地址安装到本地python的Lib/site-packages下

六、pip其他操作

1. pip官方介绍文档：https://pip.pypa.io/en/stable/

2. 切换安装源：

   • 一次性修改：

     # 指定检索，只到指定地址检索
     pip install --index-url https://pypi.douban.com/simple/ 需要安装的包/模块名称
     # 简化
     pip install -i https://pypi.douban.com/simple/ 需要安装的包/模块名称
     
     # 扩展检索，先到https://pypi.org/sample/，没有检索到才会到扩展地址检索
     pip install --extra-index-url https://pypi.douban.com/simple/ 需要安装的包/模块名称

   • 永久修改：

     • 在C:\Users\用户名目录下创建pip文件夹

     • 在pip文件夹创建pip.ini文件，写入一下内容

       [global]
       index-url=https://pypi.douban.com/simple/
       [install]
       trusted-host=pypi.doubna.com

3. 安装在不同的python环境

   # 方式一：
   python -m pip install 包或模块名
   python3 -m pip install 包或模块名
   # 方式二：
   py -2 -m pip install 包或模块名
   py -3 -m pip install 包或模块名
   
   # 理论依据是：
   python安装包实际在系统中安装了一个启动器py.exe   C:\Windows\py.exe
   启动器调用不同版本的python解释器去执行某些脚本

4. 查看包

   • 所有已经安装的：

     pip list
     pip -v config list #查看配置文件位置

   • 不被依赖的包：

     pip list --not-required

   • 过期的包：

     pip list --outdated

   • 查看某个包的具体信息：

     pip show xxx

   • http警告（永久修改安装源的修改为http，而不是https）：

     #每个pip命令最后加上trusted-host=组织域名，不建议使用，直接https
     # 例如：
     pip list --outdated --trusted-host=pypi.doubna.com

5. 搜索包（官方已经停用，了解）

   pip search xxx
   # 默认是https://pypi.org/，-i修改检索地址
   pip search -i 检索地址 xxx

1. 安装其他版本包

   # pip install "库名（包的名称） 限定符 版本号" 
   # 限定符 为 == > < >= <= ，多个限定符与版本用，分隔
   # 注意双引号的书写，例如
   pip install "requests >= 2.28.0, <= 2.28.1"

2. 升级包

   # pip install xxx  只有在本地库没有的时候才能下载最新不然不会下载更新，所以更新需要使用上式
   python -m pip install --upgrade pip

3. 删除包

   pip uninstall xxx
   # 删除对应的包

4. 生成冻结需求的文本

   • 可以将当前安装的三方包记录，存储到指定的文件中

   • 以后可以根据该文件安装三方包

   • 用法：用来将当前环境的下安装的第三方包输出到指定文件中，输出的文件中，方便别人使用pip安装，过滤掉了pip，setuptools，通过—all参数查看所有包

     pip freeze > requirements.txt

   • 根据冻结文本安装

     pip install -r requirements.txt

5. 三方包版本

   三方包版本有n1+n2+n3组成，n1.n2.n3

   • 版本bug修复：n3+1
   • 新增某一个功能：n2+1
   • 修改一个功能，或者修改原来api增加一个新的大功能：n1+1

七、发布自己的三方包或模块

1. 文档：https://python-packaging.readthedocs.io/en/latest/minimal.html

2. pypi官网进行账号注册

3. 环境准备

   • setuptools安装
   • pip安装
   • wheel安装：使用pip命令安装 pip install wheel
   • twine安装：帮助我们把包上传到pypi，使用pip命令安装 pip install twine
   • 注意python版本环境问题

4. 发布前准备

   • 创建一个项目
   • 编译生成发布包

5. 发布过程

6. 发布成功后使用

   • 手动下载

   • pip安装

     pip install xxx

八、创建一个项目的项目结构

1. 项目名称

2. 包

   • 模块(必须有)

   • init.py(必须有)

   • setup.py(必须有)：

     • 作用：项目信息的配置文件，这个里面重要的是执行setup函数，通过这个函数指明信息，

       from distutils.core import setup
       setup(形参1=实参1, 形参2=实参2, ...)
       # 一般推荐使用
       from setuptools import setup
       setup(形参1=实参1, 形参2=实参2, ...)

     • 名称：name

     • 版本：version
     • 描述信息：description
     • 需要处理的包列表：packages
     • 需要处理的单文件模块列表：py_modules
     • 作者：author
     • 作者邮箱：author_email
     • 长描述：long_description，可以从README.rst读取出来
     • 依赖的其他包：install_requires
     • python版本控制：python_requires
     • 项目主页地址：url
     • 协议：license
     • …
     • 具有setup.py的脚本文档1：https://docs.python.org/zh-cn/3.9/distutils/setupscript.html
     • 具有setup.py的脚本文档2：https://packaging.python.org/en/latest/tutorials/packaging-projects/

• README.rst

  • 文档语法:https://zh-sphinx-doc.readthedocs.io/en/latest/contents.html
  • 与markdown语法非常相似，基本一样
  • 语法检测
    • 在pypi无法正确显示原因：pypi对rst的解析问题，并不是sphinx，导致部分语法差异
    • 解决：从本地对long_description进行验证，通过后再上传
    • 步骤：
      • 安装库 pip install readme_renderer
      • 执行 python3 setup.py check -r -s，running check检测成功
      • 也可以使用pycharm验证，右键rst文件运行
  • 注意：使用setuptools打包，自动包含这些文件，不需要在MANIFEST.in声明，使用distutils打包，不包含文件，需要声明

• LICENSE.txt

  • 声明库的使用责任等等
  • 内容文档：https://choosealicense.com/
  • 注意：使用setuptools打包，自动包含这些文件，不需要在MANIFEST.in声明，使用distutils打包，不包含文件，需要声明

• MANIFEST.in

  • 当我们打包项目时，并不是所有的文件都会被打包到目标包中，打包工具会所有已经打包的文件生成一个MANIFEST的列表清单，我们可以通过MANIFEST.in告诉打包工具新增一下指定文件
  • 例如include LICENSE.txt、include README.rst
  • 官方文档：https://docs.python.org/zh-cn/3.9/distutils/sourcedist.html#specifying-the-files-to-distribute
  • 包含：include *.txt
  • 递归包含：recursive-include examples .txt .py
  • 修剪：prune examples/sample/build

1. 注意：

   • 命名全部小写
   • 多个单词使用中划线-进行分割，不要使用下划线，pip对下划线支持不是很好
   • 不能与Pypi上的命名重复

九、编译生成发布包

1. 进入setup.py同级目录（cd 目命令）

2. 执行

   • python3 setup.py sdist

     • 生成源码压缩包
     • 包含setup.py，源码文件，数据文件等等
     • 可以用在任何平台上重新编译使所有内容

     • 官方文档：https://docs.python.org/zh-cn/3.9/distutils/sourcedist.html#manifest-related-options

       python setup.py sdist --formats=gztar,zip

       

   • python3 setup.py bdist

     • 生成二进制发行包
     • 不包含setup.py
     • 是某个特定平台和python版本的一个存档
   • python3 setup.py bdist_egg
     • 生成egg包
     • 需要安装setuptools
   • python3 setup.py wheel
     • 生成wheel包
     • 需要安装wheel
   • python3 setup.py bdist_wininst（官方文件有，但是我没有这个命令）
     • 生成whindows下的安装文件
   • 更多命令：python3 setup.py —help-commands

3. 注意：

   • 以上生成的包可以在本地安装
   • 二进制发行包：可以解压直接拷贝到指定目录
   • 包含setup.py的源码压缩包，解压进入同级目录，执行python3 setup.py install
   • windows下的安装包，双击按步骤进行
   • 包含setup.py的源码压缩包、.egg、.whl,使用pip install xxx
   • 卸载 pip uninstall xxx

十、发布

1. 在命令行执行

   twine upload 需要发布的目标包
   # 需要输入用户名和密码

1. 成功后，pypi官网可以查看

2. 不需要上传到镜像服务器，镜像服务器每隔一段时间自动同步，可能不会立即更新

十一、区分模块的测试和发布状态

1. 我们在发布前写的测试代码，上传到pypi时，别人下载使用，导入模块时，会执行测试代码

2. 解决

   • 方式一：发布前删除测试代码，弊端是下次更新迭代需要把测试代码重新写

   • 方式二：借助name来区分py文件是被执行模式（name前后有双下划线）

     • 自己模块内执行name为main(main、name前后均拥有双下划线)

     • 被其他模块导入执行，name为模块名称

       if __name__ == "__main__":
          #测试代码才执行，到时候发布后别人就不会执行

十二、项目打包生成可执行文件

1. 安装三方库PyInstaller

   pip install -i https://pypi.douban.com/simple PyInstaller

1. 将模块打包

   pyinstaller -F 模块名称
   # example：
   pyinstaller -F F:\code\python\python3Project\student-system\stusystem.py

1. 找到提示路径下的exe执行

   我的是C:\Users\16691\dist\stusystem.exe