There are several files that are commonly included in the root folder of a Python project. These are:
Almost all projects benefit from these files from one way or another and it can even be said that they are necessary for packaging a Python library.
Let’s take a closer look at each of these files so you can also construct them for you project:
10 mins
Upper-Intermediate
na
Provided by HolyPython.com
Although each file have a function, setup.py is a file with very high priority in the setup chain.
You can include a number of features in your Python package’s setup.py file. On top it usually includes:
from setuptools import setup
Whenever package is being installed, this is the module that’s used to install your package.
It’s also useful to include this file reading procedure. This allows PyPI website to see inside your readme.md file and include it on the website on your project’s webpage.
Make sure to match the exact file name and extension on your package’s root folder, it’s also case sensitive.
with open("README.md", 'r') as f:
long_description = f.read()
Next is constructing a setup function with all the parameters that can be handy for an installation. Most of the information your provide here will either be used in the installation criteria or they’ll be shown on the project’s page on PyPI.
Check out this example from Watermarkd repository:
It’s important to note that these values are sensitive. They can alter the installation process of your package or the name it is listed under. So be especially careful with:
You can probably fix a mistake about author_email or url but you’d probably still want to avoid mistakes.
url is the link that shows under Homepage link on PyPI while;
download_url is the link to your compressed source distribution file on Github that you get after making a release.
long_description=long_description might seem confusing, this just tells PyPI where to get the long description that will be shown on project’s page from. Remember the previous code where we opened readme.md file and assigned this value to its content. This is a common practice to have package’s long_description to come from the readme.md file so that there is a standard and it also helps avoid repeat work.
It’s also a good idea to include long_description_content_type=”text/markdown”, this way setuptools knows the type of your long_description. If you skip this step you might get errors related to the format of your readme.md file.
Additionally, install_requires and python requires ensures necessary libraries as well as the correct Python version is installed for your package to be installed.
If you’re curious about any other parameter python’s official documentation is pretty neat and satisfactory so, you can also check out all the Python setup.py parameters here.
name='Watermarkd',
version='0.7.1.2',
description='A friendly watermarking tool with optional GUI component.',
license="Apache-2.0",
long_description=long_description,
long_description_content_type="text/markdown",
author='holypython.com',
author_email='watermarkd@holypython.com',
url="https://holypython.com/",
download_url = 'https://github.com/holypython/Watermarkd/archive/0.7.1.2.tar.gz',
packages=['Watermarkd'],
install_requires=[
'pillow',
'pysimplegui',
],
python_requires='>=3.6'
)
Additionally, it’s a good idea to include two lists namely, keywords and classifiers. These will be shown on PyPI and help search engines, contributors and your audience in general to find, identify and understand your project better.
A word of caution must be mentioned here. There is a standard for the classifiers, you can’t just make up new categories. You can check out this index from PyPI to decide on your classifiers.
Here is a sample from Watermarkd:
keywords = ['watermarking', 'image processing', 'watermark', 'photography', 'copyrights', 'holypython', 'batch watermark', 'holypython.com'],
classifiers=[
"Development Status :: 3 - Alpha",
"Intended Audience :: Developers",
"Intended Audience :: Education",
"Intended Audience :: End Users/Desktop",
"Programming Language :: Python :: 3",
"License :: OSI Approved :: Apache Software License",
"Operating System :: OS Independent",
],
There you go, we have a nice and full setup.py file. Check out this full code borrowed from Watermarkd library on Github.
"""Simple Photo Watermarker"""
import setuptools
from setuptools import setup
with open("README.md", 'r') as f:
long_description = f.read()
setup(
name='Watermarkd',
version='0.7.1.2',
description='A friendly watermarking tool with optional GUI component.',
license="Apache-2.0",
long_description=long_description,
long_description_content_type="text/markdown",
author='holypython.com',
author_email='watermarkd@holypython.com',
url="https://holypython.com/",
download_url = 'https://github.com/holypython/Watermarkd/archive/0.7.1.2.tar.gz',
packages=['Watermarkd'],
keywords = ['watermarking', 'image processing', 'watermark', 'photography', 'copyrights', 'holypython', 'batch watermark', 'holypython.com'],
classifiers=[
"Development Status :: 3 - Alpha",
"Intended Audience :: Developers",
"Intended Audience :: Education",
"Intended Audience :: End Users/Desktop",
"Programming Language :: Python :: 3",
"License :: OSI Approved :: Apache Software License",
"Operating System :: OS Independent",
],
install_requires=[
'pillow',
'pysimplegui',
],
python_requires='>=3.6'
)
This is a sometimes overlooked but very important file.
Open source projects can lack the fine showcase proprietary software usually has. But, it’s actually very important to have a decent readme.md file so that:
Finally, .md extension stands for markdown language. It’s a bit different than html or text but it’s very intuitive and easy to pick up. Just check out a few readme.md files on Github and you’ll get the idea.
Some of the common useful subtopics in a readme.md file are:
Requirements file is easy, it is used to manage dependencies. It communicates with the setup interface that your package requires certain other libraries because its working depends on them.
The important point here is that:
etc. You don’t have to include these libraries because they are included in the standard Python library. You can see the complete standard library list in Official Python Documents here.
However, if your packaging is using a third party library such as:
pysimplegui, pil, tensorflow, bs4 etc. those are the ones you’ll want to include in your requirements.txt file with the versions your package depends on. You can find the latest version on library’s PyPI page or Github page.
Here is an example from the Watermarkd library’s requirements.txt file:
pillow==7.2.0
pysimplegui==4.29.0
This file manages the import process when a user is using the library after installation.
So, when we type something like import pandas or import matplotlib or import PIL what happens behind the scene is that __init__.py file manages what to actually import.
There can be many different needs and variations depending on the code but there are usually two types of management that takes place related to __init__.py file:
It can help to check out a couple of examples through Holypython’s Watermarkd library on Github.
Firstly, this library includes source code (Watermarkd.py) inside a folder (Watermarkd) under root folder.
from .Watermarkd import Watermarkd
from .Watermarkd import Spread
So, two __init__.py files are being utilized to ensure intended, optimum user experience.
You can check out the files in the repo for a clearer demonstration.
This file is simple from the file structure perspective. It’s just a text file that includes your license. However, it’s not so simple from the legal or philosophical perspective.
If you’re an entrepreneur, inventor, engineer, developer or coder or anything that’s similar to these innovative and inventive occupations you may want to familiarize yourself with different types of licenses and legal obligations they bring or prevent from happening.
We have a nicely structured and extensive article about different open source licenses, so, you’re welcome to check that one out.
Generally, if you decided to publish your code as open source you will likely decide between two categories of open source licenses: copyleft or permissive type.
This is the essence for people with non-legal backgrounds. Even permissive licences usually have many nuances so it makes sense to take a deeper look especially if your work has intellectual weight and potential. Generally speaking it can be said that, the more important the code, the more important license decisions become.
Some of the most common copyleft open source licenses are:
And some of the popular permissive open source licenses are:
You can check out differences and explanations about each open source license here:
Open source licenses and best practices explained.
Legal disclaimer: This article is not intended to be legal advice. Please seek appropriate professional advice and don’t rely on information here. Holypython.com is not responsible for the correctness of any of the information although utmost effort is spent to ensure sharing valid information.
ContentsIntroductionBokeh vs Seaborn & MatplotlibBokeh vs PlotlySummary Introduction As computer science activity booms, you might…
History of Speech-to-Text Models & Current Infrastructure As speech technology continues to advance, so too…
Python Tips & Tricks (Part III) Advanced Level HolyPython.com Here are more Python tips about…
Python Tips & Tricks (Part II) Intermediate Level HolyPython.com The list continues with slightly more…
Almost 15 years after the release of Python 3 many people are wondering when Python…
Introduction We are going to need smart engineering solutions to solve our planet's problems (and…