Post pypi

_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
+```