1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
|
==========================
``setuptools`` Quickstart
==========================
Installation
============
.. _Installing Packages: https://packaging.python.org/tutorials/installing-packages/
To install the latest version of setuptools, use::
pip install --upgrade setuptools
Refer to `Installing Packages`_ guide for more information.
Basic Use
=========
For basic use of setuptools, just import things from setuptools. Here's a
minimal setup script using setuptools::
from setuptools import setup, find_packages
setup(
name="HelloWorld",
version="0.1",
packages=find_packages(),
)
As you can see, it doesn't take much to use setuptools in a project.
Run that script in your project folder, alongside the Python packages
you have developed.
Invoke that script to produce distributions and automatically include all
packages in the directory where the setup.py lives. See the `Command
Reference`_ section below to see what commands you can give to this setup
script. For example, to produce a source distribution, simply invoke::
setup.py sdist
Of course, before you release your project to PyPI, you'll want to add a bit
more information to your setup script to help people find or learn about your
project. And maybe your project will have grown by then to include a few
dependencies, and perhaps some data files and scripts::
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=["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="me@example.com",
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.
)
Automatic package discovery
===========================
For simple projects, it's usually easy enough to manually add packages to
the ``packages`` argument of ``setup()``. However, for very large projects
, it can be a big burden to keep the package list updated. setuptools therefore
provides tools to ease the burden.
``find_packages()`` takes a source directory and two lists of package name
patterns to exclude and include. It then walks the target directory, filtering
by inclusion patterns, and return a list of Python packages (any directory).
Finally, exclusion patterns are applied to remove matching packages.
For example::
#...
from setuptools import find_packages()
setup(
#...,
packages = find_packages()
)
For more details and advanced use, go to :ref:`package_discovery`
Entry points and automatic script creation
===========================================
Setuptools support automatic creation of scripts upon installation, that runs
code within your package if you specify them with the ``entry_point`` keyword.
This is what allows you to run commands like ``pip install`` instead of having
to type ``python -m pip install``. To accomplish this, consider the following
example::
setup(
#....
entry_points={
"console_scripts": [
"foo = my_package.some_module:main_func",
],
}
)
When this project is installed, a ``foo`` script will be installed and will
invoke the ``main_func`` when called by the user. For detailed usage, including
managing the additional or optional dependencies, go to :ref:`entry_point`.
Dependency management
=====================
``setuptools`` supports automatically installing dependencies when a package is
installed. The simplest way to include requirement specifiers is to use the
``install_requires`` argument to ``setup()``. It takes a string or list of
strings containing requirement specifiers::
setup(
#...
install_requires = "docutils >= 0.3"
)
When your project is installed, either by using pip, ``setup.py install``,
or ``setup.py develop``, all of the dependencies not already installed will
be located (via PyPI), downloaded, built (if necessary), and installed.
For more advanced use, see :ref:`dependency_management`
Including Data Files
====================
The distutils have traditionally allowed installation of "data files", which
are placed in a platform-specific location. Setuptools offers three ways to
specify data files to be included in your packages. For the simpliest use, you
can simply use the ``include_package_data`` keyword e.g.::
setup(
...
include_package_data=True
)
This tells setuptools to install any data files it finds in your packages.
The data files must be specified via the distutils' ``MANIFEST.in`` file.
For more details, see :ref:`datafiles`
Development mode
================
Setuptools allows you to deploy your projects for use in a common directory or
staging area, but without copying any files. Thus, you can edit each project's
code in its checkout directory, and only need to run build commands when you
change a project's C extensions or similarly compiled files.
To do this, use the ``setup.py develop`` command. It works very similarly to
``setup.py install``, except that it doesn't actually install anything.
Instead, it creates a special ``.egg-link`` file in the deployment directory,
that links to your project's source code. And, if your deployment directory is
Python's ``site-packages`` directory, it will also update the
``easy-install.pth`` file to include your project's source code, thereby making
it available on ``sys.path`` for all programs using that Python installation.
for more information, go to :ref:`development_mode`
Distributing a ``setuptools``-based project
===========================================
Before you begin, make sure you have the latest versions of setuptools and wheel::
pip install --upgrade setuptools wheel
To build a setuptools project, run this command from the same directory where
setup.py is located::
setup.py sdist bdist_wheel
This will generate distribution archives in the `dist` directory.
Before you upload the generated archives make sure you're registered on
https://test.pypi.org/account/register/. You will also need to verify your email
to be able to upload any packages.
You should install twine to be able to upload packages::
pip install --upgrade twine
Now, to upload these archives, run::
twine upload --repository-url https://test.pypi.org/legacy/ dist/*
To install your newly uploaded package ``example_pkg``, you can use pip::
pip install --index-url https://test.pypi.org/simple/ example_pkg
The next following sections will walk you through all of the available functions
``setuptools`` offers in excrutiating details (including those already mentioned)
for more advanced use.
|
