Python Packaging: Hosting Code at Github

Github Code Sharing and Development Platform

Github is a great platform for open source software. It grew so much in recent years as the interest in computer programming grew but it’s also such a great platform for sharing, collaborating and contributing.

A lot of people even create repos (or repositories) as archiving their information in an open environment. 

It’s common to see lists of links, books, movies, knowledge sources etc although it’s mainly developed as a platform to share code.

So, our advice is don’t be shy, jump on the wagon if you don’t have a Github account yet, you will soon discover it offers so many amazing synergies and it’s not that complicated either.

Github Logo

So, in a nutshell, you host and share code on Github, no matter how advanced or basic it is. There is no such criteria as your code must be extraordinary so don’t be intimidated. You can start with something like:

msg = "Hello World!"
print(msg)

just to test the waters…

Creating a Github Account

You can sign up for Github from the top right corner.

Creating a Github Account is simple. Just go to Github Signup Page. Just pick s unique username, set your password and game is on!

Github Sign Up Page

Once you sign up, you can start a repo. Think of repositories as individual projects, libraries, software, notebooks or products.

You can have any amount of repository in your Github account.

Just click New Repository and it will take you to repository initialization page.

Github New Repository Menu

Creating a Github Repository

Creating a repository is also easy. Just pick up a unique name. This name only has to be unique in your account. It doesn’t have to be globally unique. It will let you know with a green or red pop up message anyway.

You can also write a short description, why not. Although it’s optional it makes sense to at least jot a couple of words.

Recommended Reading:

Steps for Creating a Github Repository

Some important criteria to consider are:

    • Public vs Private: This option is straightforward. If you’d like to keep your repo as private no one will be able to see it except you and people you assign it to. Public repos are open to public view and contribution. You can also change it later.
    • Adding a README file: Checking this option almost always makes sense. It’s great to have a Readme file, content of which also shows up on the main page of your repository. You can always delete it later if you don’t want it or you can change it as well.
    • Adding a gitignore file: This file tells setup file which files not to include in a setup. So, it’s an ignore template. This is genius because there can be lots of irrelevant files like temp files from your IDE or from Python itself that you actually want to avoid in software development.
    • Adding a licence: Adding license can be more serious than it sometimes seems. If you’re in a rush you can always uncheck this option and add a license you choose later.

Thank you for checking out Github component of the Python packaging series. When you are ready you can also consider uploading your unique Python library to PyPI.

If you need some inspiration check out this post:

I’ve been learning coding. What’s next? (Python Edition)

How to Use Watermarkd: A Batch Watermarking Library with GUI

What is watermarking?

Watermarking is a technology of printing less opaque text or symbols on images and items. Believe it or not it’s considered an ancient technology as old as paper since it’s been used on special letters, stamps and printed currency.

As digital imaging has never been such a humongous part of humans’ lives, the usage, creation and demand related to digital images rises as well. Despite the rise of open source and sharing mentality in the digital community, there seems to still be significant room for watermarking applications and so the demand for innovation continues.

Star shaped watermarks among with other patterns on 100 Euro banknote

Why Watermarkd?

Watermarkd is a Python library published by Holypython.com under the open source license Apache-2.0.

In this post we will try to demonstrate what can be accomplished with Watermarkd library.

Watermarkd library allows users to handle watermarking operations in Python directly from the terminal or through use of an optional GUI component.

Since it’s specialized only for watermarking tasks, Watermarkd has a very light graphical user interface. You can probably get an image watermarked (or watermarkd!) during the time it takes to start up a major Image Manipulation software.

It has the most commonly used features when it comes to watermarking and expected to cater to 90% or more of the people looking to watermark an image.

How does Watermarkd work?

Currently, Watermarkd library consists of one sole class named Spread which houses two functions that spread out watermark text on image(s):

  • single function: Spread.single() can be used to apply watermark on a single image (photo).
  • batch function: Spread.batch() can be used to apply watermark to multiple images in a folder.
Here are some images created with Watermarkd on the go.
Medical Field Watermarking
Business confidentiality communicated through watermark

Below you can see various usage types of Watermarkd Library under four titles:

– Single Function Usage

– Batch Function Usage

– Single Function Usage with GUI

– Batch Function Usage with GUI

Single Function Usage

Single function can be used in two main ways:

  • through command line without any interface using its parameters
  • through GUI by enabling gui parameter via True boolean.

as simple as passing True argument to gui as below:

single(gui=True)

Let’s first investigate usage scenarios without gui:

import Watermarkd as wmd

wmd.Spread.single(img_path=r"c:/myimage.png")

This code, once executed, will create a watermarkd image on the user’s Desktop. You don’t have to assign gui parameter to False since it’s the default option. So, basically it’s the same thing as this code:

wmd.Spread.single(gui=False, img_path=r"c:/myimage.png")

Also, please note that, when not using gui, the only parameter you have to pass an argument to is img_path, since all the other parameters have default values and hence, they are optional.

Let’s continue to explore other parameters that can be passed to the single function:

 

  • gui, (bool), default False : enables GUI
  • img_path, (string), mandatory parameter :signifies image path
  • wm_text,  (string), default= “Watermarkd”) : Watermark Text
  • wm_trans, (int [1-255]), default= 85 : Signifies Watermark Transparency 
  • font_size, (int), default= 55) : Watermark Font Size
  • font_name, (string), default= “arial.ttf” : Font Type
  • filename, (string), default=”Watermarkd” : File Name for Saving
  • save_to_path, (string), default=”Desktop/watermarkd_” : Saving Folder Path
  • save_to_suffix, (string), default=”.png” : File Type for Saving 
  • output_filename, (default= r”c:/Users/”+user_path+”/Desktop/watermarkd.png”) : File Name For Saving

Here is another example, in which watermark text is assigned to “Inception”:

from Watermarkd import Spread

f = r"c:/Users/ABC/Desktop/film.png"
Spread.single(img_path=f, wm_text="Inception")
Film Making Industry Watermarking

Batch Function Usage

Batch function is very similar to single function with a few subtle differences. First and foremost, it handles a folder of images rather than a single image. 

So, img_path parameter is exchanged with folder_path parameter.

Otherwise the rest of the differences are mainly internal which you can check out in the source code if you like.

from Watermarkd import Spread

Spread.batch(folder_path=r"c:/User/ABC/New_Photos")

This code will read all the images from the given folder New_Photos, and create an output folder named Watermarkd_ in user’s Desktop and save all the watermarked files there with the default values for optional parameters. Check out a list of parameters below for adjusting different values such as: watermark text, font size, font type, file name, path name, transparency etc.

If you check out the source code, most of the variable names are also conveniently borrowed from the single function.

Regarding the inner workings of the batch function, the main thing is: it doesn’t apply the watermarking algorithm to a single image, instead watermarking algorithm and positioning etc are placed inside a for loop which iterates through the images in the given folder.

So, in simpler words, folder is iterated with a for loop, image file name is taken which becomes the img_path similar to single function, then watermarking is applied and then files is saved and next iteration starts with the next file.

Here is another example:

from Watermarkd import Spread

f=r"c:/User/ABC/New_Photos"
Spread.batch(folder_path=f, wm_text="Photographer A. C. Jonah, #927-654-92**")
  • gui, (bool), default False : enables GUI
  • folder_path, (string), mandatory parameter  :signifies folder path
  • wm_text,  (string), default= “Watermarkd”) : Watermark Text
  • wm_trans, (int [1-255]), default= 85 : Signifies Watermark Transparency 
  • font_size, (int), default= 55) : Watermark Font Size
  • font_name, (string), default= “arial.ttf” : Font Type
  • filename, (string), default=”Watermarkd” : File Name for Saving
  • save_to_path, (string), default=”Desktop/watermarkd_” : Saving Folder Path
  • save_to_suffix, (string), default=”.png” : File Type for Saving 
  • output_filename, (default= r”c:/Users/”+user_path+”/Desktop/watermarkd.png”) : File Name For Saving
More Photo Examples:
Model Promoting Holypython.com Watermarked with Watermarkd
Young Model Posing For Photography Agency with Watermarkd
Univeristy of Utah Campus Watermarked with Watermarkd
New Release Poster for Software

Watermarkd Usage: Single Function with GUI

Usage with GUI is pretty straightforward.

  1. Pick an image file
  2. Type your watermark text
  3. Choose a watermark text size. Options are:
    • Normal (by default)
    • Small
    • Large
    • Value: Let’s a custom font value to be entered. Possibly something like ~150 for high rez images where something like 30 might suffice for a low resolution image.
  4. Transparency: This value defines the transparency (or opacity) of your watermark text. 85 is the default value but you can go all the way down to 0 for a completely transparent text (Watermark would be invisible then). 255, the maximum value will create a solid white watermark text (which is more just a white text than watermark since it’s not transparent at all. It can sometimes be useful nevertheless.)
  5. Save as: Different options to save watermarked image as different image types such as:
    1. png (default)
    2. jpg
    3. gif
    4. bmp
  6. Save to: Path or folder that you’d like to save your watermarked image to. You can either type it or choose it with the help of the Path button.
  7. Filename: Filename you’d like to save your watermarked image under.

Once submit is pressed all the inputs from the user get registered and watermarking process starts.

It can last anywhere between miliseconds to a couple of seconds depending on the resolution of the image. (For the very high resolutions you might need to allow 2-3 seconds which also depends on the availability of computation resources.)

Just as GUI is a new dimension for the Python coder, Packaging also is a new dimension that opens up a whole new world of opportunities and skillset.

To activate GUI component all you have to do is:

Spread.single(gui=True)

You don’t have to pass any other arguments to setting parameters since they’ll be overridden after the GUI is executed.

from Watermarkd import Spread

Spread.single(gui=True)
Single Function's GUI Component in Watermarkd

Watermarkd Usage: Batch Function with GUI

Usage with GUI in batch function is also simple and straightforward. It’s mostly overlapping with single function’s steps. Here are the main differences:

  • Pick a folder instead of a single image through the Browse button.
  • At the bottom file name will be used as a seed to generate multiple images with watermark. For instance, if you choose Work as file name, files will be saved as Work1.jpg, Work2.jpg, Work3.jpg etc.

Once submit is pressed all the inputs from the user get registered and watermarking process will start.

It can last anywhere between miliseconds to a couple of seconds per image depending on the resolution of the image. (For the very high resolutions you might need to allow 2-3 seconds per image which also depends on the availability of computation resources.)  After that time watermarked images will be created in the specified folder or default folder if none is specified.

Activate graphical user interface for bath watermarking a folder of images similar to the code in single() function’s case:

from Watermarkd import Spread

Spread.batch(gui=True)
Watermarkd batch function's GUI window

Further Steps with Watermarkd

As much as I’d love to see Watermarkd getting used by people with different backgrounds such as:

  • Photographers 
  • Bloggers
  • Entrepreneurs and Business Owners
  • Students
  • Teachers
  • Media Agencies
  • Artists, Illustrators

I’d also love to see it being checked out as a learning tool for Python packaging and Python coding in general. It has all the ingredients necessary to comprehend packaging in Python.

Besides packaging topics such as: Pypi repository publishing, Github hosting, licensing etc. It also has fundamental coding topics, but nothing too complicated to discourage an intermediate or even beginner coder, such as:

Additionally, it’s pretty simple to understand and demonstrates all the ingredients needed to publish a library on PyPI (Python Package Index), such as:

    • setup.py
    • requirements.txt
    • License
    • Readme.md
    • __init__.py
Every great coder was a beginner at some point. So, don’t be too shy. One step at a time you too can become great, and create great programs,  there is no doubt about it. Some helpful topics to discover can be:

Such topics open up whole new worlds for a programmer to progress towards, you can see them as paths you can take in your journey(Oftentimes you can combine these paths for a great product as well).

Final Thoughts

If you’re a beginner or intermediate programmer go ahead and create a Github account. Maybe create a trivial repository where you take some notes and save some files if you like, just to start getting familiar with the environment.

If you like Watermarkd or Holypython’s work in general, you’re welcome to visit our Github repos as well. You can read the Watermarkd.py source code along with other necessary files there (setup.py, requirements.txt, __init__.py etc.). 

As simple as it is, I hope Watermarkd library serves as a practical solution for people who might need watermarking and I’d love to see it serve educational purposes for coders and developers who never had a chance to explore packaging and publishing topics related to Python.

Thank you so much for visiting.

ps: I’d like to thank creators and contributors of Pillow the Friendly PIL Fork and PySimpleGUI libraries for creating such fantastic libraries and influencing further developments. Also, a huge thank you to Stack Overflow community for sharing so much expert level knowledge and being so kind.

Python Packaging: Quick Tutorial & Checklist

Packaging is a very exciting process for the coder. Packaging allows you to share your work with the world and step into a structured, real developer position rather than dealing with bits and pieces of code here and there. And I don’t mean position in a corporate sense here, after all you know your position better than everyone else.

So, this tutorial is about packaging and it can help you navigate the pretty standardized steps of Python packaging and all the intricacies that come with it.

Estimated Time

10 mins

Skill Level

Upper-Intermediate

Exercises

na

Posts from the Series

Course Provider

Provided by HolyPython.com

This page is a practical summary version of all the steps involved in Python library packaging. You can also find links for longer versions of each step with more detailed explanations, comments and remedies for potential pitfalls at the bottom of this page along with a Python packaging checklist.

If you’re reading this tutorial you might already have a cool invention or an improved version of some other program. In that case congratulations! You’re one step closer to creating wealth for yourself and also for the world.

If you don’t have something tangible yet don’t worry, it’s something that comes with sustained practice. I don’t mean to be corny but, just continue coding and exploring and if you stay at it it’s almost guaranteed to happen. When the inspiration is there though, it’s advised not to sleep on it, so when the moment comes, don’t put it off, don’t delay, act and realize!

So, here is a summary of the major Python packaging cornerstones:

  1. Getting the Code Ready for Packaging
  2. Hosting at Github
  3. Open Source Software Licenses
  4. Necessary Files (setup.py, readme.md, license, __init__.py, requirements.txt, setup.cfg)
  5. Local Installation, tests and __init__.py File
  6. Uploading to PyPI with Twine
Long version links at the bottom.
A routine startup portrait, members discussing in front of computers

At some point in your coding journey, eventually you realize the power of publishing. Open source is really cool and it enables sharing technical knowledge and intellectual products at an unprecedented level. But only when you experience first hand:

  • An open source program development on Github
  • Publishing your program on a library like Pypi. Maybe at different stages like:
    • Pre-alpha,
    • Alpha,
    • Beta,
    • Release Candidate,
    • Stable Release)

you really start to feel the incredible power of open source synergies.

It is recommended to every programmer, yet, the knowledge gap seems to prevent many people from getting to that stage.

It’s not that difficult, but there is an open source terminology involved which can be confusing for a lot of people.

This is a huge value loss for everyone, for the programmer, for his environment, eventually for the whole world. Because you never know how far that programmer is going to be able to go if those gaps are bridged and dots are connected.

So, hopefully this Python tutorial empowers coders at the beginning stages of their journey and helps them understand how to package Python code, how to create a library, how to create a module. You might not necessarily be a beginner programmer, but you might not have discovered these topics yet or had the opportunity or occasion for it.

Nevertheless, understanding library structures and entering open source world really expands a coders horizons and we recommend stepping into this knowledge space as soon as possible since the benefits are so high.

You might have just learned how to print “Hello World” or you might actually be producing advanced level programs already and just not have stumbled upon this knowledge yet. In the end, it’s all good. Everyone’s journey is unique and it’s important to embrace and strive to progressively move forward.

 

Let’s check out the general frame of the packaging process and if you’d like to go deeper in any of the steps we have links for that too.

Python Packaging Preparation

After you have a functioning code you will want to do a certain type of cleaning up on it because, code in a library is slightly different than the code in a local .py file that’s used for personal tasks and development. Here are some common practices:

  • Clean up the unnecessary comments
  • Clean up the part or all of print functions not to cloud user’s terminal too much
  • If something can be expressed as a user-defined function, then consider building some functions.
  • Tidy up via Python classes. Try to place everything inside a class or multiple classes. User-defined functions can be run from inside the class when needed. For example:
    • class A:
      • def alpha():
  • A.alpha()

Before we advance, and after certain improvements on your code you also need a few tools for packaging so you might want to get them ready. These are:

  1. A Github account
  2. A PyPI account
  3. Command Prompt that works with Python (or PowerShell), we suggest Anaconda Command Prompt as a practical and complete solution.
  4. twine library installed in Python for uploading to PyPI

Creating a Github Repository

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut elit tellus, luctus nec ullamcorper mattis, pulvinar dapibus leo.

python setup.py sdist

Choosing a license

If you’re sharing your code you need a license so that important aspects of usage, development, price, modification, reselling, responsibility, sublicensing etc. are more clear.

Most common open source licenses are:

Apache-2.0

GNU GPL

GNU LGPL

MIT License

BSD Licenses

More on open source licenses here.

Necessary Files

You need a couple of files that you might not be familiar with in order to package your Python library and turn it into an installable repository. These files are:

setup.py

requirements.txt (optional)

readme.md (optional)

setup.cfg (optional)

__init__.py (optional)

So, before being misleading, although it seems only setup.py is obligatory for Python installation and this is technically true, all of the files above are pretty obligatory in practical sense. You don’t really want to miss any of them.

python setup.py sdist

Creating a Release on Github

Github is a great platform for coding collaboration, version management and open source sharing. It’s free and you simply sign up and create a new repository.

You might want to skip the license selection for your project at the very beginning if you’re not informed on the topic yet.

Local Installation & Testing

First off, you can just navigate to the root folder which hosts your package and import the package after launching Python there. This is as simple as navigating with cd command and then launching Python and trying to import the library as intended.

Eventually though you will want to make a real installation to see if everything is going through smoohtly. 

You can use the code below for a local installation, first create a source distribution, it will create a Python egg and source distribution in the folder where your package exists.

Installing a library locally is very simple and straightforward. Just navigate to the package’s root folder where setup.py can be found and execute the command below:

pip install .

This one will properly install the package inside the site-packages folder under your Python installation folder.

It can be more convenient if you don’t want to have to navigate to the specific directory to import your library and it’s still a local installation and has nothing to do with uploading.

After installation is successful, you can just import your library like any other library:

import [library_I_developed]

At this point, you can make the final checks, see if library is installing and functioning as it’s supposed to, you can also check if __init__.py files are functioning properly and creating the correct importing structure you intend for your users.

Uploading to PyPI

If everything is looking absolutely fine it’s time to step into the wild. Wild in this case is Python Package Index or PyPI.

Egg and source distribution terminology can be confusing. Source distribution is just your library packaged in a .zip or .tar.gz compressed archive formats. Installation occurs through these source distributions.

Egg is pretty much the same thing and it’s a zip file, it’s just a bit specialized and distinct so it’s extension is .egg instead of .zip. You can still open it as a zip file and check out the content if you’re curious.

So, let’s create the source distribution:

python setup.py sdist

This will create a source distribution which is basically a tar.gz or zip file as mentioned above.

Now you have a source distribution ready to be shipped to PyPI however, it’s beneficial to add one more step. It takes a couple of seconds but it can save you lots of headache.

Using twine check all the distributions inside the package. If there is an error with the setup.py file or readme.md file or any of the other ones, it will tell you what the error is so you can fix it and ship again.

import twine

twine check dist/*

Once everything clears 100%, it’s time to upload. Just execute the command below:
Don’t forget to import twine if you haven’t before.

twine upload dist/*

You’ll be asked your PyPI username and then password, just type those in order and press enter and your package will be uploaded.

If update to PyPI is successful, that means that now your library can be installed on any computer with Python and internet connection all around the world. All that’s needed is the execution of this simple pip command:

pip install [Library_Name]

Just get rid of the brackets around your library name when you’re actually installing it.

Updating the package in PyPI

You will likely have new versions every now and then just create a new source distribution and repeat the check and upload steps and your package will be updated automatically.

python setup.py sdist
import twine

twine check dist/*
twine upload dist/*

After that you might want to update your library in your computer from PyPI. Just run this code for that:

pip install [Library_Name] --upgrade 

If you still have question, each step included here has its own long version below and maybe the answers you’re looking for are there. It can still be a good idea to check them out even if you don’t have any questions since there are some cool knowledge included regarding each step of Python packaging.

Python Packaging: Necessary Files (setup.py, requirements.txt, readme.md, __init__.py)

List of Necessary Files for Packaging

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:

Estimated Time

10 mins

Skill Level

Upper-Intermediate

Exercises

na

Posts from the Series

Course Provider

Provided by HolyPython.com

setup.py

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:

  • name, unique name of your package to be distributed under
  • version: Package version, important to match with the release version on Github and download_url.
  • license: The license content based on the license you decided to choose.
  • download_url: Compressed file link under releases on Github.
  • packages: List of all Python import packages that should be included.

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'
)

readme.md

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:

  • users know what the library is capable of
  • users don’t have to struggle to get started with your library
  • known issues are shared honestly with the audience
  • development plans are shared, so users can know what to expect and you can also build rapport with your audience.
  • don’t forget the people who helped you, supported you and inspired you. As the saying goes, nothing’s new under the sun, we’re all learning from each other.
  • examples can make understanding your library 100x easier.
  • you can also include images and appropriate links, but remember, images have to be in the hosted in the repository for PyPI to pick them up. Otherwise they’ll show in Github readme but they’ll be broken on PyPI.

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:

  • Installation
  • How to Use
  • Examles
  • Classes and Functions Explained
  • Known Issues
  • Versions
  • References
  • Acknowledgements
  • Future Plans
  • Dependencies
  • Contact Information
  • Instructions for Contributing

Requirements.txt

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:

  1. You don’t have to list default Python libraries. They are already included in Python. So, if your library is using something like:
    1. random
    2. datetime
    3. getpass
    4. turtle
    5. calendar
    6. collections
    7. math
    8. sqlite3
    9. json
    10. socket
    11. unittest
    12. tkinter
    13. re
    14. zipfile
    15. gzip

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

__init__.py

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:

  • which libraries to actually import when import command is executed.
  • which classes from those libraries to import when a library is imported.

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.

  1. First one, under the root folder imports the source code from the folder it’s in when import is executed.
    • from .Watermarkd import Watermarkd
  2. Second one, under the Watermarkd folder where source code can be found. This __init__.py ensures necessary classes are imported when Watermarkd library source code is imported.
    • 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.

License

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.

  1. Copyleft is more restrictive regarding the continuation of the same license and sharing everything (even related work) as open source regarding derivative work. It also comes with a subcategory; weak copyleft. Weak copyleft licenses usually have less restrictions than a copyleft license. Depending on perspective copyleft can be favorable or unfavorable. But in general it can be said that it’s much less business friendly (or commercial friendly) in the traditional sense.
  2. Permissive on the other hand comes with less restrictions. There are many varieties that cater to different needs but at their core they usually share this message: Here is my code, it’s free, it’s as is, it’s open source. You can do whatever you want with it. You can’t sue me though, I’m not responsible for any damage or commercial failure or anything like that.

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:

  • GNU GPL (strong copyleft)
  • Eclipse Public License 2.0 (weak copyleft)
  • LGPL (weak copyleft)
  • Common Development and Distribution License, CDDL, (weak copyleft)

And some of the popular permissive open source licenses are:

  • Apache-2.0
  • MIT License
  • Berkeley Software Distribution, BSD

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.

Python Packaging: Local Installation & Tests Before Uploading

Locally installing and testing a Python library is such a good idea especially before uploading it to PyPI.

You might have tested the software itself during and after the development processes but there are so many new components after packaging. It’s particularly useful to build and install a library and you have multiple options that will help you understand packaging better and ensure a smooth operation when you’re finally uploading your library to PyPI.

Don’t worry we’ve tried hard to explain all these steps and options clearly below.

Estimated Time

10 mins

Skill Level

Upper-Intermediate

Exercises

na

Posts from the Series

Course Provider

Provided by HolyPython.com

Install Library where it exists

install the library using the code below:

python setup.py install

Building VS. Installing

python setup.py install already takes care of two steps. It builds and then installs. But you just normally don’t see that build step take place as it happens.

python setup.py install

If you want to build separately without installing though it’s also possible. You just need to use this code:

python setup.py build

Install Library with pip Locally

This is the closest you get to a pip installation your audience will experience via pip command.

This way, your library will be added to site-packages folder in your Python installation folder. Python installation folder can differ based on the setup you’re using. For example, it’s normally under:

c:/Anaconda3/Lib/site-packages if you’re using Anaconda.

To proceed with installation this way, just ensure you are running command prompt (or Anaconda Shell) in the folder where your setup.py is residing. Then run the command below (Yes! There is a dot.):

pip install .

Uninstalling and Reinstalling with pip during the tests

As you proceed with your tests you may wanna make little changes and then test again. This might require uninstalling and re-installing your library to check if changes are taking place.

Please note that sometimes you might also need to close the Command Prompt, Anaconda Prompt, or Python IDE you’re working with, and then restart so that library loads up freshly without the old remains in the memory.

To uninstall a library simply run this command:

pip uninstall [LIBRARYNAME]

Testing __init__.py file

Another big aspect of local tests is testing the __init__.py files.

__init__.py file is responsible of loading up necessary modules and classes at appropriate stages. For examples if your source code is in a folder you don’t want to force user to do repetitive import tasks. And also, you don’t want to oblige user to import each class every time they import a library or module.

In that case we would have to do something like this every time we import a library:

  • import folder
  • import library
  • import class a
  • import class b

So, developers usually strive to eliminate unnecessary steps from the importing process and achieve something like this:

  • import folder
  • import library
  • import class a
  • import class b

and hopefully everything relevant gets loaded automatically. This depends on a proper structuring of __init__.py file. Don’t worry in practice it’s a couple of lines of code and not so difficult but it’s just important to get it right and sometimes it can be a bit complicated to do so. Explanations and examples below should help you get it right.

It makes perfect sense to test __init__.py file and see if its functioning as it should via a local installation. Other files such as Readme.md or setup.py will cause errors during installation or have visible flaws when something’s wrong but it’s possible to have a malfunctioning program due to __init__.py file despite a successfully executed installation. That’s why it’s wise to test the program locally in this sense as well.

Since this file’s behavior can be observed during and after the import it’s quite useful to take advantage of local tests to see if __init__.py is doing what it’s intended to be doing.

__init__.py file is used to load up modules, libraries and classes when a library is imported.

For instance when your library exists inside a folder, if you don’t include a proper __init__.py file, when your library is imported it will only import the folder name. Then the users will have to follow a repetitive calling structure such as

library.library.class.function

First library in this example is only the folder while the second library is the actual Python module.

You can also include multiple __init__.py files. It’s common practice to include a __init__.py file in the root folder to ensure proper importing of the main library and then several __init__.py files as needed to where modules exist. In the same folder with modules you will want to make sure classes of these modules are initialized inside the __init__.py files.

So, while __init__.py file in the root directory looks like this:

from .ABCDEF import ABCDEF

__init__.py file in the module’s folder may look something like this:

from .ABCDEF import MyClassName

This example is just to give an idea and your program might have specific needs regarding importing modules and classes. You will know it best as the developer and it can also help you find out to locally test the code and installation in that sense.

Also please note that after recent updates, including a dot before the importing source became a necessary step as in the code examples and forgetting that dot can cause problems.

So, while the first code is importing the actual library from the folder where it stays, in the second code certain Class is being imported from the actual library itself.

You can check out Watermarkd library in Holypython’s Github Repository to see __init__.py files in action both in the root folder and also in the Watermarkd folder where source code can be found.

Thanks for reading this turorial. Once you have everything down with the local tests and __init__.py files, next and final step for having a library on PyPI is Uploading a package to The Python Package Index PyPI.

Congratulations on your efforts and coming thus far!

Please share this article if you found it helpful.

Python Packaging: Software Licenses (Open Source Licensing and More)

If you don’t know anything about open source licenses, you will probably never look at software the same way again. Licenses imply many meanings about the project and its eco-system and its a decision many developers have to make at some point in their development process.

This tutorial tries to decipher different types of open source licenses and you will find some detailed information about different licenses and their types as well.

If you are in a hurry consider checking out Github’s website about choosing a license.

Estimated Time

20 mins

Skill Level

Upper-Intermediate

Exercises

na

Posts from the Series

Course Provider

Provided by HolyPython.com

If you’re sharing your code you’ll also need a license. A license is an agreement that defines some major criteria about your program such as, but not limited to:

  • who can use your code
  • to what extend can they use your code
  • what kind of attributions are required
  • how can they use your code
  • who is responsible if something goes wrong
  • who can modify your code
  • sublicensing
  • who can resell your code or something created with it, etc. etc.

Luckily, if your code is open source there are a number of convenient and ready-to-use open source software license options that you can choose from. We take these licenses for granted but they save open-source coders and developers so much headache and legal costs.

When you decide to share your code as open source, which is an amazing thing to do, the license mostly becomes about protecting you, the developer, from the situations where something goes wrong related to your code or program.

Lawyer lady working on legal document on her laptop with Lady Justice figure on her desk

One of the most important and significant criteria regarding choosing an appropriate open source license for your software, or also when you are working with open source software, is license being permissive or copyleft.

Permissive licenses are more relaxed in their terms and they basically allow whatever users please to do with the source code of a library, package, program or software.

Copyleft, on the other hand comes with some obligations, hence its more restrictive in this sense. It usually requires that users continue using the same license and continue sharing source code of their modified work (and also everything related to that work). But, copyleft also comes in weak copyleft form which can be a little more permissive and flexible than copyleft, yet still not fully permissive.

Copyleft Vs. Permissive

In general open source licenses fall under two categories: permissive and copyleft.

Permissive makes less demands on the user’s of the program. It doesn’t enforce derivative work or modifications, rebrandings, redistributions etc to stay under a specific license. It doesn’t require that in case of commercial adaptation the code must be shared as open source.

For these reasons permissive open source licenses are known to be more commercial friendly and less strict in general.

Copyleft on the other hand is a bit stubborn or demanding in that sense. It usually requires that code remains under the same or similar open source licenses. It can also apply restrictions in commercial use cases. While remaining open source can be a good thing, restrictions also can hurt business in long term especially if the license enforces to remain under the exact same license. 

There can be cases where VC or other investors avoid work done with copyleft licenses simply because it might imply further restrictions in the future. Copyleft can also make it impossible to adopt a custom license.

Nevertheless, there are definitely room for copyleft applications in the open source world and famous license options from both sides continue to remain and co-exist. 

Strong Copyleft vs Weak Copyleft

Weak copyleft is a lighter version of regular copyleft licenses. It usually has less restrictive conditions and allows some of the code the remain proprietary or undisclosed depending on the relations with modified source code.

Here is a nice a nice and detailed explanation of copyleft (or strong copyleft) vs weak copyleft from: WhiteSourceSoftware.com:

Weak copyleft licenses requires you to disclose your source on source code, but not on binaries and therefore you can compile covered sources with others and distribute the resulting (merged) binaries under the licence of your choice. With ‘strong’ copyleft license, the GPL family, you are obligated to reuse the same licence in case of re-distribution of copies or derivatives on both source and binaries.

Most Common Open Source Licenses

MIT License Logo
GNU GPL3 License Logo
Apache License Logo

Let’s take a deeper look at most common open source licenses.

Some of the most common copyleft open source licenses are:

  • GNU GPL (strong copyleft)
  • Eclipse Public License 2.0 (weak copyleft)
  • LGPL (weak copyleft)
  • Common Development and Distribution License, CDDL, (weak copyleft)

And, some of the most common permissive open source licenses are:

  • Apache-2.0
  • MIT License
  • Berkeley Software Distribution, BSD

As it’s often the case in legal practice there are some nuances between the fine prints of these licenses. Let’s look at the main characteristics of each of these licenses.

GPL and AGPL

GPL is a slightly tricky license because if you share something under GPL license this means your package can be used freely but if someone wants to modify or repackage and redistribute your package they will also have to use the same GPL license.

So, you might want to consider that your audience will be forced to use the same license in that case. Also, if you are working on a package which is published under GPL license and planning to distribute a different or improved version of it you don’t want to breach the license agreement so, you have to use the same license.

In this sense it can be a bit restrictive as a license but it’s also supporting and promoting the continuation of open source distribution which is really nice.

Basically, if you share your work under GPL it’s likely to stay under the same open source licensing.

Another important point with GPL is that it has 3 variations so far: GPL1, GPL2 and GPL3. But each of these variations also have “only” and “or later” versions. So, if you decided to adapt GPL2 only license back in the day, you couldn’t even switch to GPL3 license when it came out while if you choose GPL3 or later license that means you can also use any license that comes after GPL3 if it does (such as GPL4) 

AGPL (Affero GPL) is pretty much GPL for network applications such as a website or online service. It’s not weak copyleft like LGPL and it’s copyleft like GPL. The only difference is user is redefined as the visitor of website or user of online application where in GPL case user is user of the program.

You can check out this interesting article on Wikipedia regarding the acquisition of MySQL and how involved open source licenses were affected. You can see the interesting license dynamics and the event that leads to MariaDB database management system after Monty Widenius’ effort to fork MySQL and release it under GPL only license with the name MariaDB.

LGPL

LGPL or Lesser GPL is a weak copyleft version of GPL. Although they are similar in many ways, LGPL allows many important things that GPL don’t.

With LGPL:

You can link to a library dynamically in your software and you wouldn’t have to publish your software under the same license because of that as long as you don’t modify the library with LGPL.

This allows proprietary applications as well as open source applications under different licenses.

If you link to the LGPL library statically though the situation changes and you are required to publish derivative work under LGPL.

There is a very interesting discussion here about how GPL or LGPL applies to interpreted languages such as Python: How does GPL/LGPL static-dynamic linking rules apply to interpreted languages?

Also, if you’d like to learn more about static linking Vs. dynamic linking.

Eclipse Public License 2.0

Eclipse Software License Logo

Eclipse is a weak copyleft license and it’s more similar to CDDL than GPL. EPL allows EPL and non-EPL licensed code to be combined under the same software given that they are separate modules. EPL also allows sub-licensing.

Another feature of Eclipse Public License 2.0 is that it requires commercial distributors to compensate contributors for any damage or lawsuit scenario that might happen.

Eclipse Foundation has a very nice FAQ page you can find here if you are interested.

CDDL

Common Development and Distribution License is a weak copyleft license with a restriction level between GPL and permissive licenses like Apache 2.0.

Instead of everything related or working with the code to be published under the same license as in the case of GPL, it only requires source code under CDDL to remain under CDDL.

This provides more flexibility regarding mixing codes with different licenses and also provides less restriction regarding re-licensing permissions.

Although it might seem subtle this difference has massive implications. A good example is if a closed source product like Adobe Photoshop or Microsoft Windows was to use GPL licensed code somewhere in their massive eco-system, they’d have to publish everything as open source under GPL license. Probably a nightmare scenario for such proprietary software companies or products.

But, if a closed source product used CDDL, they would only have to publish CDDL licensed code and compiled software could be packaged under a different license.

That’s basically how a weak copyleft license such as CDDL exists in a sweet spot between copyleft and permissive licenses.

Unlike strong copyleft licenses like the GPL, mixing of CDDL licensed source code files with source code files under other licenses is permitted without relicensing. The resulting compiled software product (“binary”) can be licensed and sold under a different license, as long as the source code is still available under CDDL, which should enable more commercial business cases, according to Sun.[5][6][7]

Apache-2.0

Apache 2.0 license is permissive and it’s also very similar to other permissive open source licenses such as MIT. However, it has a special trick. Apache 2.0 comes with patent protection for the user and software owner.

If any patent is involved, Apache 2.0 grants rights to freely use the software and waives all the license or patent fees. This grant is in effect until the user decides to sue the contributor/owner in which case license is immediately revoked.

Otherwise, Apache 2.0 gives rights to do pretty much whatever user legally wants to do. It also protects the owners from responsibility and legal issues by disclaiming warranty regarding the code or program.

Another edge Apache 2.0 license has over others is the appropriate legal language and explicitness which makes it an attorney-favorite.

You can check out Apache Licenses here.

MIT

MIT is the most popular open source license. Approximately 50% of all open source projects are under MIT license on Github which is probably a good representative sample of all open source projects in the world.

MIT license is known to be very short and straightforward basically suggesting

  • software is free and source code is openly shared
  • user can do whatever they want with it
  • contributor(s)/owner(s) aren’t responsible and do not guarantee anything
Although attorneys might frown upon such simplicity, most tech people absolutely love it exactly for that reason.
MIT License from mit-license.org

BSD

BSD comes under many varieties. Some main ones are:

0-clause BSD: Originally named Free Public License 1.0.0, zero clause BSD is not derived from BSD license family.

2-clause BSDVery similar to MIT license with the exception of not explicitly mentioning granting of; merging, publishing, sub-licensing, selling rights.

Although, these rights are likely to be granted under the right to use. There can be restrictions to some of the items since they are not explicitly mentioned such as sub-licensing.

3-clause BSDBans using contributor or organization names in promoting products derived from original source code.

4-clause BSDRequires mentioning the organization’s names in all advertisements related to derivative work. Here is the text obliged to be included:

This product includes software developed by the [organization].

There are also other interesting BSD License varieties such as:

2-clause BSD + Patent, which is somewhat familiar patent reciprocity offered by Apache 2.0 license.

3-clause BSD + no nuclear, which clearly states that code is not licensed or intended for any use in any nuclear facility.

BSD 2-clause License example.org

Caution for freestyle licensing

Given there are so many varieties of different licenses, you might be tempted to create your own cool as a cucumber license and maybe name it something like Snow Frost ATL 5.0. Well, hold your horses because this might not be a very wise thing to do for a number of reasons.

Although there seems to be quite some amount of open source licenses these are all approved by Open Source Initiative OSI.

  1. When you try to operate on your own homemade license, this might mean that you are excluded from using other open source material only allowed to be used by open source projects under OSI approved licenses.
  2. A bigger problem is however uncharted waters. Regarding any common open source license you can go on an online forum or ask an intellectual property lawyer and you will easily get decent information and likely outcomes about a case. Since, precedent is a major principle in legal matters, having previously established rulings or consortium creates a massive convenience regarding your the visibility of your situation. A custom, homemade license means a whole estimation from ground up which will be a very costly scenario in case you have to go that route.
  3. It’s very likely that you will mess up something. Open source licenses are created by decent amount of legal power that big organizations employ. It’s usually a team work and takes lots of time effort and time even though they might seem simple. In law, one word or its lack of can turn the tables and your probably don’t want to go through that kind of a stressful situation.

For these reasons, we don’t usually recommend adaptation of a homemade amateur license. However, you never know, your project or startup might actually require something more custom, in which case working with some experienced people and law experts will probably make most sense although even then, unless if you really must, it’s probably something that should be avoided.

Luckily there are numerous options that cater to different needs and philosophies.

The Software Package Data Exchange® (SPDX®) also has a very nice and extensive list of open source licenses here. And also you can find open source licenses under different categories in this list.

Disclaimer: Please understand that, knowledge and comments shared in this article are not legal advice. Although utmost care is taken for integrity and correctness of the information gathered here holypython.com or its authors or its owners do not guarantee accuracy of this information. If you are concerned about choosing a license we encourage you to read the individual license and draw your own conclusion before making your decision. Or, you can also consider seeking professional legal advice. Holypython.com or its authors or its owners will not take any responsibility for decisions made or conclusions drawn based on this article.

Please share if you found this article helpful.

Python Packaging: Getting Ready

Before publishing a library one needs to consider the circumstances that arise from the project going public.

These considerations change from cleaning up the code and comments to establishing the right structure for people to read, learn, use and contribute.

This Python packaging tutorial provides a list of some of these points to think about before and during packaging a Python library or software.

Estimated Time

15 mins

Skill Level

Upper-Intermediate

Exercises

na

Posts from the Series

Course Provider

Provided by HolyPython.com

We will focus on some of these points:

  • Getting the Code Ready
    • Cleaning up print functions, unpresentable comments, function calls.
    • Dealing with errors in a user friendly way
      • implementing try / except statements
      • implementing continue / break statements
    • Constructing Python Classes to compartmentalize the code
    • Creating multiple .py files when necessary (i.e.: if multiple modules are involved).
  • Signing Up for Necessary Accounts
  • Drafting Documentation
    • Readme.md file (markdown format is very common for readme files)
    • Versioning
    • Future Plans
    • Intended Use
    • Getting familiar with licensing

Getting the Code Ready

Coding style during development and coding style for publishing a library can differ quite a bit. There are some points you will want to pay attention to ensure a successful experience for your users and other contributors.

Here are some of the adjustments that are generally made before publishing a software after the development period.

Random coding window on development laptop
  1. You want to be more thoughtful about code structure. When the curtains open the whole world might, read, use, modify and improve your code. You might further your development process in future with new versions.
    • Use user-defined functions more often
    • Use classes as often as needed
    • Use meaningful variable names
    • Check out advanced coding tutorials about writing better code
  2. You’ll likely want to clean up comments a bit, at the packaging stage comments are not only for you but also for the whole world to see and interpret.
  3. You’ll want to clean up print statements and function calls. Now your audience can call the functions as they need. But it’d be weird if functions automatically called by themselves as users or contributors import your library.
  4. Try to put everything in a class or classes. Again, the point is, we want the user to import the classes they wish to import and avoid unnecessary automatic assignments and function calls. Classes are also a fantastic way to offer reusable blueprint schemes and refined structure.
  5. Check the code for different scenarios. Add try except and break continue statements where it makes sense. At this point you want a smooth user experience rather than a development experience. Although the seriousness of this statement may vary depending on your audience being end-users or other developers, you still want it to be as refined as possible in most cases.

Once your source code seems ready it might be time to upload it to or update it on Github. You can read about Creating a Github Repository here.

Or you can skip that stage and read about Local Installation and Tests tutorial here.

Github Logo

Getting the Accounts Ready

Further on, we’re going to need a couple of accounts, so, if you haven’t yet, it makes sense to sign up to these and get your ducks in a row. Most needed accounts will be:

  1. Github: If you don’t have a Github account yet, you can sign up now. It’s the most widely-used platform for managing open source software development. It’s pretty straightforward to use and incredibly useful.
  2. PyPI: PyPI, stands for Python Package Index, will be the global host for your package. You will need a username and password and you can just get that done now if you like.
  3. Stack Overflow: This is more about getting help during the development but also probably during the life time of the developer / contributor. While you’re at it it wouldn’t hurt to get a Stack Overflow account as well. Stack overflow is a forum platform where coders help each other with usually technical questions or issues.

Thinking About Versioning, Development Stage & Future Plans

Startup Team Discussing in Meeting

Versions:

It also makes sense to think about the version of your program if you haven’t already.

Usually the deeper the number tree gets the more detailed and specific the differences between versions get. Higher up the tree numbers start to imply major changes.

For example:

You can pick a version number such as: 5.0.0

Maybe 5.0.1 can be about a tiny change or improvement or bug fix, while you want to introduce a new feature as 5.1.0 and so on. Eventually when you make a major redesign or overturn it might be wise to continue with 6.0.0. Kind of like mobile phone software!

Development Stage: 

There are different stage in the life of a software. Most commonly used nomenclature goes like this:

Alpha: First stage of officially testing software.

Beta: Beta usually means less bugs than alpha but bugs likely still exist and feature-set is expected to be complete and fully functioning at this level.

Release Candidate (RC): Release Candidate is a version that has a strong potential to be a stable release. Bugs are minimized and last checks and controls are expected to be made during this stage.

Stable Release or Release: Finally Stable Release is expected to have 100% functionality and minimal or no bugs.

Future Plans: You may also want to think a little bit about future of your software.

  • Where do you want to take it?
  • How many versions do you roughly anticipate?
  • Do you see a big potential of growth or will it always exist in a small niche spot?
  • Do you think there might be synergies with other libraries? 
  • Do you have a timeline for fixing the known bugs?
  • Do you have an intended use case for your audience?
  • Do you not intend your work to be used by a specific group or industry? (such as disallowing fossil fuel facilities or nuclear facilities from using your program/library/software.)
As coders and programmers we focus and go deep but it can help to disengage and try to address some general questions from a higher level. This can also help improve your vision specific to your project and in general.
Pen and Paper for taking notes along with goggles and gadgets

Drafting a Readme FIle

Drafting a readme file on a piece of paper or any digital document can be helpful at this stage to avoid overwhelming work later on.

Some of the topics you can consider are:

Installation

Usage Examples:

Class and Function Explanations

Known Issues

Future Plans

Versions

Acknowledgment and Thank You

Contact Information

Links

References

Disclaimers

You’re not limited with these topics and you can include anything that seems relevant for your audience however, especially if you’re not working with markdown format you probably don’t wanna go crazy with styling details as markdown has its own little syntax.

Speaking of which you might also want to familiarize yourself a bit with markdown format, if you’re not familiar with it already, as this is the most common extension that’s used for the official readme.md file that will have to prepared later on.

Don’t worry though, it’s just text editing and it’s pretty easy to pick up.

Next Steps

Thanks for reading this article. Next step will be about open source licenses. It’s important to understand open source licenses and take an appropriate pick for your library as you will need to make decision when you’re hosting your project on Github later on.

Open Source Licenses Explained for Python Projects.

If you already know about open source licenses and you’d like to skip to one step ahead you can check out:

How to host your Project on Github.

Python Packaging: Uploading a Python Library to PyPi

Once you cover the necessary ground for packaging whether it be coding, licensing, testing or documentation, it’s finally the moment of truth: Uploading to PyPI!

From this point on, you should be executing commands inside the root folder of your library. This is where installation files such as: setup.py, requirements.txt and readme.md exist.

There are two ways to ensure you’re running Python in a specific directory that comes to mind:

  1. Before starting Python: Navigate to the folder from Command Prompt (Anaconda Command Prompt or Anaconda Shell), then launch Python there.
    • To do this, use cd command. For example:
    • if you’re in C:/ and you want to navigate to C:/New_Folder, all you have to do is execute cd New_Folder
    • Then, if you execute cd .. this will take you to the directory one level up, if you are in C:/New_Folder and execute cd .. it will take you back to C:/
  2. From inside Python:
    • import os
    • os.chdir(r’c:/Users/ABC/Desktop’)

You can check your current working directory from inside Python with this code:

import os

dirpath=os.getcwd()
print(dirpath)

Estimated Time

10 mins

Skill Level

Upper-Intermediate

Exercises

na

Posts from the Series

Course Provider

Provided by HolyPython.com

Creating Source Distribution

If you’ve prepared all the packaging files, did some local testing and installation you are ready for the real deal: uploading your package to PyPi Python Repository.

After your package is successfully up, your package will be available for installation globally.

python setup.py sdist

Checking your distribution

It’s always a good idea to check the source distribution before uploading it to a repository.

This way if there is an error you will catch it before hand and avoid potential failures.

twine already has a fantastic command that takes care of this:

twine check dist/*

twine check is usually pretty good at pointing out the exact error when there is one. So, if there is an error, it will be raised to your attention, otherwise it will say something like check successfully completed 100%. Then, you’re good to go.

It’s the moment of truth, your precious package is ready to be uploaded and take its place in the wild. All  you have to do is execute the command below:

twine upload dist/*

Then, you will be asked for your pypi username and password. Just enter them in order. While entering password it will seem like you’re not typing, if you’re not familiar with this it might feel weird, just type as usual and it will actually be registering key presses. Then press enter and ta-da!. 

Your package is up congratulations.

If something goes wrong don’t be discouraged. First times are always a bit messy. Just refer to the tutorials about each step and once you address the problem everything should work fine.

We tried to include all the pitfalls and common errors in each step in this tutorial series. So, you should be covered if you still get a really unexpected error then chances are high that it also happened to someone else and there is a thread about it on Stack Overflow. If there isn’t it’s a good idea to just start it which will help the next guy encountering the same problem after you.

If you’re certain that you’ll upload your project but you just need a little more time, you might want to register your project name with PyPI in the meanwhile.

you need an extra file to do this:

Once you create a .pypirc file with the following content you can execute the code to register your project.
servers = pypi

username:[Enter your PyPI username here]
password:[Enter your PyPI password here]
python setup.py register

Now, you can take your time without worrying about the project name getting taken.

Don’t drag it forever though, some things are meant to be fixed and improved during the different development stages of the code when the program is in alpha version.

Congratulations, now you don’t only know Python and programming but you’re also figuring out how to create software and upload it to a repository, in this case PyPI which is a fantastic step for coding work in Python.

Wishing everyone a productive, creative, innovative and meaningful coding journey.

If you need some inspiration check out some of the topics we have on our blog.

Please share this Python packaging tutorial if you found it helpful.