https://ift.tt/3ZA4pyd This is an end-to-end demo aiming to facilitate the process of sharing an open-source software both privately and pu...
This is an end-to-end demo aiming to facilitate the process of sharing an open-source software both privately and publicly
This is an end-to-end demo of sharing your code. The project aims to help you understand how to properly publish your python modules/packages on PyPI externally and share your work with your colleagues internally.
Step 1
Go to the following two websites to register your own account, respectively.
- PyPI test: https://test.pypi.org/
- PyPI: https://pypi.org/
Note: You may skip this part if you do not want to publish your package publicly. Also, I highly recommend trying your package on the test site first to avoid mistakes in the uploading process. Since any change, you make to your package on PyPI is not revertable, uploading errors may lead to a malfunctioning patch for your package. You want to avoid that!!
Step 2
Option 1: Fork this repository to your own GitHub account and make it available in your local. You can make the most changes on GitHub, but you will need to publish your package via cmd with those files available in local.
Option 2: Create the necessary files manually. And here is the list of the core files you will need:
I know that’s a lot. But bear with me. You only need to make necessary changes to some of them, and the rest will stay as default.
OPTIONAL — Multiple Modules
Suppose you have multiple classes with functions created in separate files. You want to make the folders (or subfolders) following this convention:
Inside each folder, update the “__init__.py” by doing this:
In the main folder, update the “__init__.py” by doing this:
Then the users will be able to import your library properly like this:
If You want to import something from the main (previous) folder, here is what you should do:
Consider adding a list in your “__init__.py” for each sub-lib, so that the users can check what functions are available:
Step 3
Install the following python package in your cmd:
Step 4
Do the following changes in ANY order you want:
- Replace your_main_code.py in the src folder with your own python package and leave “__init__.py” as it is if you are only publishing a module.
- Make changes to setup.py, and instructions are included in that file.
- Pick your own license. Open the LICENSE file, click on Edit, click “Choose a license template”, and select the license that fulfills your needs. If you have no idea which license works for you, you can use the MIT license, which is one of the most common choices. Or, you can use this link to pick one: https://choosealicense.com/
- Update CHANGELOG.md to reflect version information
- Optional: create a “test.py” and put the file in the tests folder. Or you can remove the whole folder if you are confident that everything works great in your module.
- Delete everything in this “README.md” file, and update the file with the long description of your package.
Step 5
You have multiple choices for step 5 to perform the rest of the steps. Here are two examples:
- Do it in cmd - Command Prompt
- In your local, open the cmd, navigate to the directory where your package is and type the following:
2. Do it in the Jupyter Notebook terminal:
Step 6
In this step, we will use the following code in cmd/terminal to build your package:
Once you run the code, you will see the following two folders in the current directory:
- build
- dist
Under the dist folder, you will see a ‘tar’ file called “TheNameofYourPackage-TheVersionofYourPackage.tar.gz”. Up to this point, if you do not need to publish your code in public; instead, if you just want to share your code with your friends or colleagues, you may just share this file with them. All they need to do is to do “pip install” to use your code:
OPTIONAL — Test Your Package on PyPI
Now, you are about to publish your package to PyPI. Before you make it public, one more thing you may want to do is to test if your package will work as expected once people download them. What you can do is to create a folder called “test”, and create a test.py, which includes some sample implementations of your package. Then, type “pytest” in your cmd/terminal. If everything works fine, it will run your test.py automatically and pass. Otherwise, it will raise errors, and you should fix the bugs accordingly before moving to the next step.
And here is one more thing you might want to try to test if the architecture of your package is good to go. In the cmd/terminal, type the following code:
You should see something like this:
Checking distribution dist/TheNameofYourPackage-TheVersionofYourPackage-1.0.0-py3-none-any.whl: Passed
Checking distribution dist/TheNameofYourPackage-TheVersionofYourPackage.tar.gz: Passed
Step 7
Upload your package to TestPyPI:
Then you will see a link leading to the testing version of your package on TestPyPI. Check it out! If there are any typos or incompatible bugs, fix them before uploading your package to the real PyPI.
And, now, it is the most exciting moment, upload your package to PyPI to help hundreds of thousands of people in our community:
By this point, your package should be officially online and can be “pip install” by anyone at any time from anywhere. Big moment! I still remember how I felt at the moment when I saw my first package is out there. I told myself, that’s why I code!
CONGRATULATIONS!!!
A few tips
- Whenever you want to update your package, you should remove the ‘build’ and ‘dist’ folders, make changes to your code, edit the “CHANGLOG.txt” file, and revise the version number in the “setup.py”. And repeat steps 5–7.
- You may upgrade your package after the updates by doing this: pip install YOURPACKAGENAME — upgrade
- You can always find your package on PyPi here: http://pypi.org/project/YOURPACKAGENAME/
- Do not publish packages arbitrarily. Even though there are no hard restrictions on what you can or cannot publish, make sure you are uploading something that is actually meaningful and someone will benefit from your work.
An End-to-End Guide to Publish Your Python Package was originally published in Towards Data Science on Medium, where people are continuing the conversation by highlighting and responding to this story.
from Towards Data Science - Medium https://ift.tt/lUyOhMr
via RiYo Analytics
No comments