{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Project structure"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Python script\n",
    "Python is a great language for building small helper tools for various different kinds of tasks. Such small tools can be often expressed as a single file Python script.\n",
    "\n",
    "Here is an example structure for a Python script (aka executable Python module)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# the content of my_script.py\n",
    "\n",
    "# imports\n",
    "import logging\n",
    "\n",
    "# constants\n",
    "LOGGER = logging.getLogger()\n",
    "\n",
    "\n",
    "def magical_function():\n",
    "    LOGGER.warning('We are about to do some magical stuff')\n",
    "\n",
    "\n",
    "def main():\n",
    "    # The actual logic of the script\n",
    "    magical_function()\n",
    "\n",
    "\n",
    "if __name__ == '__main__':\n",
    "    main()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Python package\n",
    "An example structure for a python project:\n",
    "\n",
    "```\n",
    "my_project/\n",
    "    README.md\n",
    "    requirements.txt\n",
    "    setup.py\n",
    "    \n",
    "    src/\n",
    "        my_project/\n",
    "            __init__.py\n",
    "            my_module.py\n",
    "            other_module.py\n",
    "            \n",
    "            my_pkg1/\n",
    "                __init__.py\n",
    "                my_third_module.py\n",
    "                \n",
    "    tests/\n",
    "        conftest.py\n",
    "        test_module.py\n",
    "        test_other_module.py\n",
    "        \n",
    "        my_pkg1/\n",
    "            test_my_third_module.py\n",
    "\n",
    "```\n",
    "\n",
    "* [requirements.txt](https://pip.pypa.io/en/latest/user_guide/#requirements-files) lists the Python packages from which my_project depends on.\n",
    "    * these can be installed by running `pip install -r requirements`\n",
    "* [setup.py](https://packaging.python.org/tutorials/distributing-packages/#setup-py) is a file in which you include relevant information about your project and the file is also used for packaging your project. Here's a minimal example of a setup.py:\n",
    "\n",
    "```python\n",
    "'''Minimal setup.py file'''\n",
    "\n",
    "from setuptools import setup, find_packages\n",
    "\n",
    "setup(\n",
    "    name='my_project',\n",
    "    version='0.1',\n",
    "    packages=find_packages(where=\"src\"),\n",
    "    package_dir={\"\": \"src\"})\n",
    "```\n",
    "* Once you have the setup.py file in place, you can install your project in editable mode by running `pip install -e .` in the root directory of your project. In editable mode the installed version is updated when you make changes to the source code files."
   ]
  }
 ],
 "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.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}