setuptools

Setuptools: Python’s distribution tool used to be Distutils, but it was unable to define dependencies between packages. Setuptools is an enhanced version that helps you create and distribute Python packages, especially packages with complex dependencies. It compensates for this by adding a basic dependency system and a lot of associated functionality. He also provides automatic package query program, which is used to automatically obtain the dependencies between packages, and complete the installation of these packages, greatly reduced the difficulty of installing each package, make it more convenient, packaged program can install to their own virtual environment, can also be uploaded to PyPI, this project is very convenient

Use setuptools

PIP installation:

$ pip install setuptools
Copy the code

For the first installation file, create a new setup file setup.py under learn_setup and create the package myapp to simulate the source package to be packaged:

├── ├─ ├─ ├─ ├.pyCopy the code

The setup.py file contains the following contents:

from setuptools import setup

setup(
    name='firstApp001'.# application name
    version='0.0.1'.# version number
    packages=['myapp'].The Python package included in the installation package
)
Copy the code

With the setup.py file above, we can type various installation packages, which fall into two main categories: Sdist and Bdist. Source Distribution can be packaged as Source Distribution using Sdist. The supported compression formats are:

Use mode:

$ python setup.py sdist --formats=gztar,zip
Copy the code

Dist and *. Egg-info directories are added to the dist directory, and dist holds the packages we’ve typed. The command above uses –formats to specify.tar.gz and.zip packages. The package name is the name defined in setup.py, version, and the package format specified, for example, firstApp01-0.0.1.tar.gz.

Built Distribution Using bdist allows you to type Built distribution, which is faster to install than the source bundle because it’s pre-built:

In use, as with Sdist, you can specify the package format with –formats. Such as:

$ python setup.py bdist --formats=rpm
Copy the code

To simplify operations, setupTools provides the following commands:

So the above RPM package can be used:

$ python setup.py bdist_rpm
Copy the code

Wheel A “Wheel” is also a built bag and an official recommended way to pack it. You may have encountered or used egg packs at one time or another, but wheel is now the official recommended way to pack eggs.

$ pip install wheel
Copy the code

Then use bdist_wheel to pack:

$ python setup.py bdist_wheel
Copy the code

After successful execution, in addition to dist and *.egg-info, there is also a build directory for storing the packaged intermediate data. The wheel package name is firstApp01-0.0.1-py3-none-any. WHL, where py3 indicates that only Python3 is supported. The wheel package supports both Python2 and Python3. Using universal is also a universal wheel package. The reverse is called a pure wheel package.

Installing the sample application in the previous section on Wheel has nothing. Add the module greet and repackage.

# greet.py
def hello():
    print('Hello, welcome to setuptools! ')
Copy the code

Once packaged again with bdist_wheel, we can install to the local Python site-packages directory using PIP.

$PIP install dist/fisrtApp001-0.0.1 - py3 - none - any. WHLCopy the code

Now used like any other tripartite library installed using PIP:

from myapp.greet import hello
hello()
Copy the code

Changes are frequent during application development, and it is cumbersome to uninstall the old version with each installation. When installed in Develop mode, the actual code is not copied to site-packages, but removed with a link to the current application (*.egg-link). This allows source changes to the current location to be immediately reflected in site-packages. Use the following

$ pip install -e .  Or python setup.py develop
Copy the code

The PyPI Wheel package can be used by itself and transmitted to others, but it is not convenient to maintain and update. PyPI is the Python software repository, so that everyone can easily upload and download, as well as manage the third-party library.

Register a PyPI account. Log in to pypi.python.org/pypi and Register an account.

While setupTools supports uploading package files to PyPI using setup.py upload, it only supports HTTP and is replaced by the new Twine. Again, you need to install Twine first:

$ pip install twine
Copy the code

Upload a file using twine

$ twine upload dist/*
Copy the code

Enter username and password to upload to PyPI. If you don’t want to enter your password every time, you can create a.pypirc file in your home directory.

[distutils]
index-servers =
    pypi
    pypitest

[pypi]
username: 
password: 

[pypitest]
repository: https://test.pypi.org/legacy/
username: 
password:
Copy the code

You can fill in your own account password. The official pypi and Pypitest are configured here. If you want to configure other warehouses, add them according to the format. Return to the PyPI home page to see the uploaded firstApp001

The setup () parameters

In the setup.py installation file above, we have used setup() parameters: name, version, packages. Version Indicates the project version number, which consists of MAJOR, MINOR, and MAINTENANCE.

  • MAJOR version when they make incompatible API changes,
  • MINOR version when they add functionality in a backwards-compatible manner, and
  • MAINTENANCE version when they make backwards-compatible bug fixes. Choose to see the version number: packaging.python.org/tutorials/d… Packages: Lists all packages that need to be packaged within the project. Setuptools.find_packages () is used for automatic discovery.
packages=find_packages(exclude=['contrib'.'docs'.'tests*'])
# exclude exclude packages that are not packaged
Copy the code

Description: A short description of the project, usually a single sentence, displayed on the PyPI next to the name.

description='My first Python project'
Copy the code

For a complete description of the project, use long_description. If the string is in RST format, PyPI will automatically render it to HTML display. Markdown can also be specified.

long_description=long_description,
long_description_content_type='text/x-rst'
Copy the code

Url: usually a link on GitHub or readthedocs link.

url='https://github.com/pypa/sampleproject'
Copy the code

Author: Indicates the author information

author='example',
author_email='[email protected]'
Copy the code

License: project license

license='MIT'
Copy the code

For an introduction and selection of various licenses, see: choosealicense.com/ ClassiFIERS

classifiers=[
    # How mature is this project? Common values are
    # 3 - Alpha
    # 4 - Beta
    # 5 - Production/Stable
    'Development Status :: 3 - Alpha'.# Indicate who your project is intended for
    'Intended Audience :: Developers'.'Topic :: Software Development :: Build Tools'.# Pick your license as you wish (should match "license" above)
     'License :: OSI Approved :: MIT License'.# Specify the Python versions you support here. In particular, ensure
    # that you indicate whether you support Python 2, Python 3 or both.
    'Programming Language :: Python :: 2'.'Programming Language: Python :: 2.6'.'Programming Language: Python :: 2.7'.'Programming Language :: Python :: 3'.'Programming Language :: Python :: 3.2'.'Programming Language: Python :: 3.3'.'Programming Language: Python :: 3.4',].Copy the code

Keywords: list of project keywords

keywords='sample setuptools development'
Copy the code

Project_urls: additional project-related links, such as code repositories, document addresses, and so on.

project_urls={
    'Documentation': 'https://packaging.python.org/tutorials/distributing-packages/'.'Funding': 'https://donate.pypi.org'.'Say Thanks! ': 'http://saythanks.io/to/example'.'Source': 'https://github.com/pypa/sampleproject/'.'Tracker': 'https://github.com/pypa/sampleproject/issues',}Copy the code

Install_requires: The Python library for project dependencies, which will be automatically checked and installed when this project is installed using PIP.

install_requires=['pyyaml']
Copy the code

Dependent on the installation of the reference: packaging.python.org/discussions… Python_requires: Specifies the Version of Python that the project depends on

python_requires='> = 3'
Copy the code

Package_data: The project depends on data files, which must be placed in the project directory and use relative paths

package_data={
    'myapp': ['data/*.yml'],}Copy the code

If the directory key is not specified as an empty string, it means that all modules will be operated on (the following example will include all yamL files in the data directory within the package) :

package_data={
    ' ': ['data/*.yml'],}Copy the code

Data_files: If the data file exists outside the project, it can be managed using either the data_Files parameter or the manifest.in file. Manifest.in is used if used for source packages; If used for wheel, use data_files.

Data_files = [(' mydata ', [' data/conf. Yml '])]Copy the code

The above Settings will add the data/conf.yml file to the myData directory when packaging the wheel. (data_files cannot use wildcards path) in addition, scripts, py_modeles, entry_points, console_scripts reference parameters, such as: packaging.python.org/tutorials/d… Other initialization Files When you read the Python library on Github, you’ll see other files besides the basic core setup.py file and the main program. This section describes their functions and usage.

Setup.cfg contains some build-time default parameters, such as:

[bdist_wheel]
universal=1
Copy the code

The universal parameter is used as the default when using bdist_wheel.

Readme. RST/readme. md: Project documentation. ReStrutruedText renders well on PyPI, but Markdown support is not good enough.

Manifest.in: This file tells SetupTools what additional files need to be packaged when you package the source code.

# Include the README
include *.md

# Include the license file
include LICENSE.txt

# Include the data files
recursive-include data *
Copy the code

TXT: project LICENSE file SetupTools packages the following files by default: readme. RST/readme. md, setup. CFG, and manifest.in Other files, such as license. TXT, You need to manually add include to manifest.in for source packages and setup.cfg for wheel packages:

[metadata]
license_file = LICENSE.txt

Copy the code

PyPI Upload Recommended configuration

setup.py name version author author_email url packages description package_data/data_files setup.cfg MANIFEST.in Readme.rst license. TXT < project >Copy the code

Official website example reference:

from setuptools import setup, find_packages
setup(
    name="HelloWorld",
    version="0.1",
    packages=find_packages(),
    scripts=['say_hello.py'].# Project uses reStructuredText, so ensure that the docutils get
    # installed or upgraded on the target machine
    install_requires=['the docutils > = 0.3'],

    package_data={
        # If any package contains *.txt or *.rst files, include them:
        ' ': ['*.txt'.'*.rst'].# And include any *.msg files found in the 'hello' package, too:
        'hello': ['*.msg'],},# metadata to display on PyPI
    author="Me",
    author_email="[email protected]",
    description="This is an Example Package",
    keywords="hello world example examples",
    url="http://example.com/HelloWorld/".# project home page, if any
    project_urls={
        "Bug Tracker": "https://bugs.example.com/HelloWorld/"."Documentation": "https://docs.example.com/HelloWorld/"."Source Code": "https://code.example.com/HelloWorld/",
    },
    classifiers=[
        'License :: OSI Approved :: Python Software Foundation License'
    ]

    # could also include long_description, download_url, etc.
)
Copy the code

Reference: setuptools. Readthedocs. IO/en/latest/s…