migrated all content to markdown

1 files changed, 176 insertions, 0 deletions

diff --git a/content/weblog/2019-01-31_python-package-to-pypi/index.md b/content/weblog/2019-01-31_python-package-to-pypi/index.md
new file mode 100644
index 0000000..f0b14e0
--- /dev/null
+++ b/content/weblog/2019-01-31_python-package-to-pypi/index.md
@@ -0,0 +1,176 @@
++++
+title = "Packaging and distributing python apps and modules"
+date = 2019-01-31T08:10:00Z
++++
+
+There may come a time after some hacking and playing around with python that
+you feel like the piece of code you just created needs to be shared with the
+world, and so you might be thinking "Man, wouldn't it be sweet if anyone could
+install my app/module just by typing `pip install stuffimade'`. Well, it is
+actually easier than you might think (it certainly was in my case).
+
+<!-- more -->
+
+It basically boils down to these five things:
+
+1. Make an account on pypi.org
+1. Come up with an original name, that hasn't been taken on pypi (arguably the
+   hardest part of these instructions).
+1. Prepare a setup py file to package your app/module, choose a license, maybe
+   (preferably) write a readme.
+1. Package it.
+1. Upload it.
+
+The first step is really simple, just go the website (pypi.org) and click on
+the link that says "Register" on the top right corner. Be sure to not forget
+your password, especially after uploading your package, since you will need
+everything that you want to upload a new version of your package.
+
+The second step is all up to you, just use the search function in the website
+to make sure that your package name hasn't been taken.
+
+After having created your account on pypi.org, and decided on a name for your
+app/package, you'll proceed to create the necessary package files. Your package
+should consist of a folder with your actual module or app, inside which should
+also be a `__init__.py` file (it can be empty if you don't need to set any
+variables or anything), a `LICENSE` file with your license of choice (e.g. MIT,
+BSD, GPL, etc.), and a `README.rst` or `README.md` file containing a detailed
+description of your app/module.
+
+Your directory structure should look something like this
+
+```
+/my-app-package
+  /my-app
+    __init__.py
+    (other files and directories)
+  setup.py
+  LICENSE
+  README.md
+```
+
+Now, if your app is going to have files other than python files, and the
+aforementioned files, you might to add a `MANIFEST.in` in the root of you
+package directory specifying the files to include. This is true, for example,
+for Django apps, since they might contain template and static files (html, css,
+js, etc.) that the packaging tool we are going to use might not pick up. As an
+example I'll show you the `MANIFEST.in` file of my w3blog package
+
+```
+include LICENSE
+include README.md
+recursive-include weblog/static *
+recursive-include weblog/templates *
+recursive-include weblog/locale *
+```
+
+There I specified to, just in case, include the `LICENSE` and `README.md`
+files, and also include static files, templates, and the message files for
+localization, by recursively searching the directories of said files.
+
+Now on to the setup.py file. For this I am also going to use my project's file
+as an example
+
+```py
+#!/usr/bin/env python3
+import os
+from setuptools import find_packages, setup
+
+with open(os.path.join(os.path.dirname(__file__), 'README.md')) as readme:
+    README = readme.read()
+
+# allow setup.py to be run from any path
+os.chdir(os.path.normpath(os.path.join(os.path.abspath(__file__), os.pardir)))
+
+setup(
+    name='w3blog',
+    version='0.5.2',
+    packages=find_packages(),
+    include_package_data=True,
+    license='BSD License',
+    description='A simple blog engine for Django with multilingual capabilities.',
+    long_description=README,
+    url='https://www.yaroslavps.com/',
+    author='Yaroslav de la Peña Smirnov',
+    author_email='contact@yaroslavps.com',
+    classifiers=[
+        'Environment :: Web Environment',
+        'Framework :: Django',
+        'Framework :: Django :: 1.11',
+        'Framework :: Django :: 2.0',
+        'Framework :: Django :: 2.1',
+        'Intended Audience :: Developers',
+        'License :: OSI Approved :: BSD License',
+        'Operating System :: OS Independent',
+        'Programming Language :: Python',
+        'Programming Language :: Python :: 3',
+        'Programming Language :: Python :: 3.4',
+        'Programming Language :: Python :: 3.5',
+        'Programming Language :: Python :: 3.6',
+        'Programming Language :: Python :: 3.7',
+        'Topic :: Internet :: WWW/HTTP',
+        'Topic :: Internet :: WWW/HTTP :: Dynamic Content',
+    ],
+)
+```
+
+Of course, you should customize this file according to your app's details, for
+example, your classifiers list might look shorter, like this
+
+```py
+    classifiers=[
+        'License :: OSI Approved :: BSD License',
+        'Operating System :: OS Independent',
+        'Programming Language :: Python :: 3',
+        'Programming Language :: Python :: 3.4',
+        'Programming Language :: Python :: 3.5',
+        'Programming Language :: Python :: 3.6',
+        'Programming Language :: Python :: 3.7',
+    ],
+```
+
+It will depend on which version of python you want to support, your license,
+some other required packages, etc. The rest of the setup function parameters
+should be self explanatory.
+
+Once you have you package files ready (don't forget about your readme and
+license), you'll need to proceed to package them, i.e. generate the
+distribution files. For that, we'll need to install a couple of packages, we
+cant install them inside a virtual environment, or you could install them
+system wide
+
+```sh
+$ sudo pip3 install --upgrade setuptools wheel twine
+```
+
+Now just run the following command from the same directory where setup.py is
+located
+
+```sh
+$ python3 setup.py sdist bdist_wheel
+```
+
+After running that command, you should now have a dist subdirectory with a
+.tar.gz archive and a .whl file. Those are the files that you'll need to
+upload. The twine package that we just installed is going to take care of that
+for us. Remember that you already should have an account on pypi.org to upload
+your package.
+
+So for example, when I just uploaded the first version of w3blog, and each time
+that I upload a new version I run a command (from the same directory as
+setup.py) that looks like this
+
+```sh
+$ python3 twine upload dist/w3blog-0.5.2*
+```
+
+Just replace "w3blog-0.5.2*" with your appropriate package name-version. After
+running that command, twine is going to ask you for your username and password,
+thence it is going to upload it to pypi. Once it is successfully uploaded, it
+should be a matter of seconds or minutes before you, and everybody else in the
+world with an internet connection (and capable of running python, of course),
+can install your package!
+
+If you need more detailed information about this process, check out the
+official documentation at
+[https://packaging.python.org/tutorials/packaging-projects/](https://packaging.python.org/tutorials/packaging-projects/)