Describe the project¶
Create some additional files in the project root directory, alongside the
sample
directory. You should end up with the following structure:
sampleproject-YOUR-USERNAME/
sample/
__init__.py
pyproject.toml
README.md
setup.cfg
setup.py
Creating README.md¶
A README file is essential for people (including yourself in the future) to understand what the project is doing. You can put some text inside this file to describe the project, using the GitHub-flavored Markdown syntax. Put in the following content if you are not sure what to write:
# Example Package
This is a simple example package. You can use
GitHub-flavored Markdown to write your content.
Creating pyproject.toml¶
Add the following content:
This file describes how we want to package the project. We will be using Setuptools, a packaging tool maintained by the Python Packaging Authority (PyPA).
Creating setup.cfg¶
This file tells Setuptools about the project (such as the name and version), as well as which code files to include.
Change the name
value to include your username (for example,
sampleproject-uranusjr
), to make the proejct name unique, and does not
conflict with other people when you upload it. Or you can use any name you like
(as long as it is not already registered—search on the PyPI to find out).
[metadata]
name = sampleproject-YOUR-USERNAME
version = 0.0.1
author = Example Author
author_email = author@example.com
description = A small example package
long_description = file: README.md
long_description_content_type = text/markdown
url = https://github.com/pypa/sampleproject
license = MIT
classifier =
Programming Language :: Python :: 3
License :: OSI Approved :: MIT License
Operating System :: OS Independent
[options]
packages = find:
python_requires = >=3.6
Here is a run-down of the configuration:
name
is the distribution name of your package. This can be any name as long as only contains letters, numbers,_
, and-
. It also must not already be taken on the PyPI. Be sure to update this with your username, as this ensures you won’t try to upload a package with the same name as one which already exists when you upload the package.version
is the package version. See PEP 440 for more details on versions.author
andauthor_email
are used to identify the author of the package.description
is a short, one-sentence summary of the package.long_description
is a detailed description of the package. This is shown on the package detail package on the PyPI. Here, we tell Setuptools to use the content ofREADME.md
, which is a common pattern.long_description_content_type
tells the index what type of markup is used for the long description. In this case, it’s Markdown.url
is the URL for the homepage of the project. For many projects, this will just be a link to GitHub, GitLab, Bitbucket, or similar code hosting service.license
describes what license this project uses—Here we use MIT, but there are many more choices available. Omit this field if you do not intend your code to be open source.classifiers
gives the index and pip some additional metadata about your package. In this case, the package described as- Only compatible with Python 3
- Uses the MIT license
- Does not care about operating systems
A complete list of classifiers can be found at https://pypi.org/classifiers/.
packages
is a list of all Python code that should be included in the distribution package. Instead of listing each package manually, we can use the find derivative to automatically discover all packages and subpackages. This is also a common pattern unless you have an uncommon project layout.python_requires
descibes what versions of Python this project is compatible with. Here, we only allow the project to be installed on Python 3.6 or later.
The keys listed above is a relatively minimal set, and there a a few more you can specify. Visit the documentation on setup.cfg to find a comprehensive list of available configurations.
Creating setup.py¶
setup.py
is a script to call Setuptools. It can be used to include custom
logic to build the project, but we are using all defaults here. Simply put:
import setuptools
setuptools.setup()