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
- Github
- PyPI
- Stack Overflow (indirectly related to packaging)
- 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.
- 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
- 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.
- 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.
- 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.
- 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.
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:
- 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.
- 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.
- 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
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.)
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.
