diff --git a/_posts/2014-10-23-publishing-in-pypi.markdown b/_posts/2014-10-23-publishing-in-pypi.markdown new file mode 100644 index 0000000..633eee1 --- /dev/null +++ b/_posts/2014-10-23-publishing-in-pypi.markdown @@ -0,0 +1,106 @@ +--- +layout: post +title: "Publishing in PyPi" +date: 2014-10-27 10:00:00 +tags: github python pypi +--- + +Developing a python module and publishing it on Github is cool, but most of the times you want others to download and use it easily. +That is the role of PyPi, the python package repository. +In this post I show you how to publish your package in less than 10 minutes. + +## Choose a fancy name + +If you haven't done so yet, take a minute or two to think about this. +To publish on PyPi you need a name for your package that isn't taken. +What's more, a catchy and unique name will help people remember your module and feel more inclined to at least try it. + +The package name should hint what your module does, but that's not always the case. +That's your call. +I personally put uniqueness and memorability over describing the functionality. + +## Create a .pypirc configuration file +{% highlight cfg %} +[distutils] # this tells distutils what package indexes you can push to +index-servers = + pypi # the live PyPI + pypitest # test PyPI + +[pypi] # authentication details for live PyPI +repository = https://pypi.python.org/pypi +username = { your_username } +password = { your_password } # not necessary + +[pypitest] # authentication details for test PyPI +repository = https://testpypi.python.org/pypi +username = { your_username } +{% endhighlight %} + +As you can see, you need to register both in the [main pypi repository](https://pypi.python.org/pypi?%3Aaction=register_form) and the [testing server](https://testpypi.python.org/pypi?%3Aaction=register_form). +The usernames and passwords might be different, that is up to you! + +## Prepare your package + +{% highlight raw %} +root-dir/ # Any name you want + setup.py + setup.cfg + LICENSE.txt + README.md + mypackage/ + __init__.py + foo.py + bar.py + baz.py +{% endhighlight %} + +### setup.cfg + +{% highlight cfg %} +[metadata] +description-file = README.md +{% endhighlight %} + +The markdown README is the _de facto_ standard in Github, but you can also use rST (reStructuredText), the standard in the python community. + +### setup.py + +{% highlight python %} +from distutils.core import setup +setup( + name = 'mypackage', + packages = ['mypackage'], # this must be the same as the name above + version = '{ version }', + description = '{ description }', + author = '{ name }', + author_email = '{ email }', + url = 'https://github.com/{user}/{package}', # URL to the github repo + download_url = 'https://github.com/{user}/{repo}/tarball/{version}', + keywords = ['websockets', 'display', 'd3'], # list of keywords that represent your package + classifiers = [], + ) +{% endhighlight %} + +You might notice that the download_url points to a Github URL. +We could host our package anywhere, but Github is a convenient option. +To create the tarball and the zip packages, you only need to tag a tag in your repository and push it to github: + +``` +git tag {version} -m "{ Description of this tag/version}" +git push --tags origin master +``` + +## Push to the testing/main pypi server + +It is advisable that you try your package on the test repository and fix any problems first. +The process is simple: +``` +python setup.py register -r {pypitest/pypi} +python setup.py sdist upload -r {pypitest/pypi} +``` + +If everything went as expected, you can now install your package through pip and browse your package's page. +For instance, check my senpy package: [https://pypi.python.org/pypi/senpy](https://pypi.python.org/pypi/senpy) +``` +pip install senpy +```