notebooks/examples/Extra - Python Software Development Practices.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Software development practices\n",
    "\n",
    "This exercise and demo are hands-on and done in your own system.\n",
    "\n",
    "However as all other exercises are notebooks, the instructions are distributed as a notebook as well."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Set-up\n",
    "\n",
    "In an appropriate directory, run the following commands to clone the example git repository.\n",
    "\n",
    "```\n",
    "$ git clone https://github.com/csc-training/python-quality-exercise.git\n",
    "$ cd python-quality-exercise\n",
    "```\n",
    "\n",
    "Now you are in the repository. You can view the README file for an explanation.\n",
    "\n",
    "Create a virtual environment (with Python3 with the following\n",
    "\n",
    "```\n",
    "$ virtualenv -p python3 python-quality\n",
    "  [...]\n",
    "$ source python-quality/bin/activate\n",
    "(python-quality) $\n",
    "```\n",
    "\n",
    "Install the required package versions with\n",
    "\n",
    "```\n",
    "(python-quality) $ pip install -r requirements.txt\n",
    "```\n",
    "\n",
    "Now, whenever you want to activate the virtual environment you run:\n",
    "\n",
    "```\n",
    "$ source python-quality/bin/activate\n",
    "(python-quality) $\n",
    "``````\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Tests\n",
    "\n",
    "You can now run tests using pytest with\n",
    "\n",
    "```\n",
    "(python-quality) $ pytest\n",
    "```\n",
    "\n",
    "Go ahead and find out the functions you can test and write unit tests for some of them.\n",
    "\n",
    "You might want to use mock for some tests, for instance to avoid the initialization of DemoClass, but at least the find_median function should be simple to test with a few examples."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Test coverage\n",
    "\n",
    "You can check the coverage of your tests with pytest-cov, a coverage plugin for pytest by running.\n",
    "\n",
    "```\n",
    "pytest --cov demolib\n",
    "```\n",
    "\n",
    "Observe that initially ``demomodule.py`` isn't even imported so it's not in the report."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Style\n",
    "\n",
    "You can test style with pep8 by running\n",
    "```\n",
    "(python-quality) $ pep8 .\n",
    "```\n",
    "\n",
    "Or with pylint by running\n",
    "\n",
    "```\n",
    "(python-quality) $ pylint demolib\n",
    "```\n",
    "\n",
    "Go ahead and fix coverage mistakes."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Setup script\n",
    "\n",
    "To make the package installable, you should put a setup.py at the top level.\n",
    "\n",
    "A minimal one like [in the Python documentation](https://docs.python.org/3.6/distutils/setupscript.html) will suffice. The name of the package you wish to expose is, of course demolib.\n",
    "\n",
    "Go ahead and make a setup script. You can test that the package is installable with\n",
    "\n",
    "```\n",
    "(python-quality) $ pip install .\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Tox\n",
    "\n",
    "To facilitate running test for more than one version of python, use tox.\n",
    "\n",
    "Create a file called tox.ini, with the following contents\n",
    "```\n",
    "[tox]\n",
    "envlist = py27,py35\n",
    "[testenv]\n",
    "deps= -rrequirements.txt\n",
    "commands=py.test --cov demolib  # run pytest\n",
    "            pep8  # run pep8\n",
    "\n",
    "```\n",
    "\n",
    "If you still have any errors go ahead and fix them.\n",
    "\n",
    "You should now be able to run tox with\n",
    "```\n",
    "(python-quality) $ tox\n",
    "```\n",
    "\n",
    "That's it. If you had an open source project you could e.g. enable Travis to automatically run your tests and style checks against every branch your team makes."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.5.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}