How to submit a PyPI

How to submit a PyPI

The other month a coworker of mine wanted to distribute a small wrapper he ' d written for the Locu API. Instead of forcing developers to clones his repository, he wanted them to being able install with a single command: pip install locu . He wasn ' t sure how to go on this so I wrote up a quick guide, which I ' M publishing below because I haven ' t found any OT Her guides-particular use case (Python library hosted on GitHub).

What is PyPI?

From the official website:

PyPI -the Python Package Index

The Python package, Index is a repository of software for the Python programming language.

Written something cool? Want others to is able to install it with easy_install or pip ? Put your code on PyPI. It's a big list of Python packages that's absolutely must submit your package to for it to be easily one-line I Nstallable.

The good news is this submitting to PyPI are simple in theory:just sign up and upload your code, all for free. The bad news is this in practice it's a little bit more complicated than that. The other good news was that I ' ve written this guide, and so if you ' re stuck, you can always refer to the Offici Al documentation.

I ' ve written this guide with the following assumptions:

• The module/library/package that you ' re submitting are called mypackage .
• mypackageis hosted on GitHub.

Create your Accounts

On PyPI Live and also on PyPI Test. You must create a account in order to being able to upload your code. I recommend using the same email/password for both accounts, just to make your life easier when it comes time to push.

Create A .pypircConfiguration file

This file holds your information for authenticating with PyPI, both the live and the test versions.

 [distutils]index-servers =  Pypi Pypitest[pypi]repository= https://pypi.python.org/pypiusername=your_ Usernamepassword=your_password[pypitest]repository=https://testpypi.python.org/pypi Username=your_usernamepassword= your_password              

This is just to make your life easier, so if it comes time to upload you don't have to type/remember your username and password. Make sure to put the this file in your home folder–its path should is ~/.pypirc .

Notes on Passwords/usernames

Michiel Sikma has reported so in Python 3 if your password includes a raw % , it needs to being escaped by doubling–th E. PYPIRC config parser interpolates strings. For example, if your password is hello%world :

[PyPI] repository=Https://pypi.python.org/pypiusername=myusernamepassword=  Hello%%world        

I ' ve never run into this issue and if you ' re have trouble this might help.

Andrew Farrell points out this if your password includes spaces, make sure don't to quote it. For example, if your password is correct horse battery staple :

[PyPI] repository=Https://pypi.python.org/pypiusername=myusernamepassword=  Correct horse battery staple        

Thanks to Michiel, Andrew, and Charlie Hack for their help with the This section.

Prepare your Package

Every package on PyPI needs to has a file called  setup.py  at The root of the directory. If your ' e using a markdown-formatted read Me file you ' ll also need a  setup.cfg  file. Also, you'll want a  LICENSE.txt  file describing what can is done with your code. So if I ' ve been working on a library called  mypackage , my directory structure would look like this:

 root-dir/# arbitrary working directory name  Setup. PY setup. CFG license. TXT readme. MD mypackage/__init__. PY foo. PY bar. PY baz. PY                  

Here's a breakdown of what goes in which file:

setup.py

This was metadata about your library.

FromDistutils.coreImportSetupSetup(Name=' MyPackage ',Packages=[' MyPackage '],# This must is the same as the name aboveVersion=' 0.1 ',Description=' A random test lib ',Author=' Peter Downs 'author_email =  [email protected] ' url =  Https://github.com/peterldowns/mypackage ' # use the URL to the GitHub repo download_url =  ' https://github.com/peterldowns/mypackage/tarball/0.1 ' # I ' ll explain This in a second keywords = [ ' testing '  ' logging '  ' example ' , # arbitrary keywords classifiers = [], )               /span>              

The is download_url a link to a hosted file with your repository ' s code. Github would host this for you, and if you create a git tag . In your repository, type: git tag 0.1 -m "Adds a tag so that we can put this on PyPI." . Then, type to git tag show a list of tags-you should see in the 0.1 list. Type to git push --tags origin master Update your code on Github with the latest tag information. Github creates tarballs for download at https://github.com/{username}/{module_name}/tarball/{tag} .

Setup.cfg

This tells PyPI where your the README file is.

[Metadata]   readme.md

This is the necessary if you ' re using a markdown Readme file. At upload time, your may still get some errors about the lack of a readme-don ' t worry about it. If you do have a markdown README file, I would recommend Usingrestructuredtext (REST) instead.

LICENSE.txt

This file would contain Whichver license you want your code to. I tend to use the MIT license.

Upload your package to PyPI Test

Run:

Setup.  -pypitest  

This would attempt to register your package against PyPI's test server, just to make sure you ' ve set up everything Correctl Y.

Then, run:

Setup.  -pypitest  

You should get no errors, and should also now is able to see your library in the test PyPI repository.

Upload to PyPI Live

Once you ' ve successfully uploaded to PyPI Test, perform the same steps and point to the live PyPI server instead. To register, run:

Setup.  -pypi  

Then, run:

Setup.  -pypi  

And you ' re done! Congratulations on successfully publishing your first package!

How to submit a PyPI