First part of second session

Author: astrojuanlu

sessions/02_layout-unit-tests.ipynb

@@ -0,0 +1,183 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "slideshow": {
+     "slide_type": "slide"
+    }
+   },
+   "source": [
+    "![IE](../img/ie.png)\n",
+    "\n",
+    "# Sessions 2 & 3: Project layout and unit tests\n",
+    "\n",
+    "### Juan Luis Cano Rodríguez <jcano@faculty.ie.edu> - Master in Business Analytics and Big Data (2019-04-03)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Triangular workflows in git\n",
+    "\n",
+    "When collaborating with a project hosted online on GitHub or GitLab, the most common setup is having a central repository, one remote fork per user, and local clones/checkouts:\n",
+    "\n",
+    "![Triangular workflow](https://github.blog/wp-content/uploads/2015/07/5dcdcae4-354a-11e5-9f82-915914fad4f7.png?resize=2000%2C951)\n",
+    "\n",
+    "(Source: https://github.blog/2015-07-29-git-2-5-including-multiple-worktrees-and-triangular-workflows/)\n",
+    "\n",
+    "Following this workflow requires discipline and sticking to a subset of actions and git commands to avoid common mistakes. This website contains all you need to know to setup your triangular workflow and we don't need to reproduce it here:\n",
+    "\n",
+    "https://www.asmeurer.com/git-workflow/\n",
+    "\n",
+    "*Notice* the different naming conventions between this website and the first image:\n",
+    "\n",
+    "1. **Convention 1**: upstream/origin/local\n",
+    "2. **Convention 2**: origin/&#x3C;username&#x3E;/local\n",
+    "\n",
+    "We will be consistent with the Aaron Meurer guide and therefore use Convention 2 all the time.\n",
+    "\n",
+    "### ⚠ After creating a pull request ⚠\n",
+    "\n",
+    "After your pull request has been merged to `master`, your local `master` and `<username>/master` will be outdated with respect to `origin/master`. On the other hand, **you should avoid working on this branch anymore in the future**: remember branches should be ephemeral and short-lived.\n",
+    "\n",
+    "To put yourself in a clean state again, you have to:\n",
+    "\n",
+    "1. Click \"remove branch\" in the pull request (don't click \"remove fork\"!)\n",
+    "2. `git checkout master` to go back to `master`\n",
+    "3. `git fetch origin` (**never, ever use `git pull` unless you know exactly what you're doing**)\n",
+    "4. `git merge --ff-only origin master` (this will update your local `master` with `origin/master`, and fail if you accidentally made any commit in `master`)\n",
+    "5. `git fetch -p <username>` :star2: this will acknowledge the removal of the branch :star2:\n",
+    "6. `git push <username> master` (this will update your fork with respect to `origin`)\n",
+    "7. `git checkout -b new-branch` to start working in the new feature!\n",
+    "\n",
+    "This process **has to be repeated after every pull request**.\n",
+    "\n",
+    "🌈 "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Project layout\n",
+    "\n",
+    "Most data science projects will start with a bunch of notebooks. However, at some point we will want to reuse code between them, and eventually put our models in production without the need to use the notebooks themselves ([unless you are Netflix](https://medium.com/netflix-techblog/notebook-innovation-591ee3221233)). Choosing a good project layout is extremely important to organize the code, avoid common pitfalls and be predictable (i.e. imitate the rest of the ecosystem to minimize surprise). On the other hand, there is lots (**lots**) of outdated, bad or wrong advice on the Internet about this topic, so here we will present The Truth™.\n",
+    "\n",
+    "### References\n",
+    "\n",
+    "* Packaging a Python library https://blog.ionelmc.ro/2014/05/25/python-packaging/\n",
+    "* Less known packaging features and tricks https://blog.ionelmc.ro/presentations/packaging/\n",
+    "* setuptools documentation https://setuptools.readthedocs.io/en/stable/setuptools.html"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### The `src` layout\n",
+    "\n",
+    "```\n",
+    "├─ src\n",
+    "│  └─ packagename\n",
+    "│     ├─ __init__.py\n",
+    "│     └─ ...\n",
+    "├─ tests\n",
+    "│  └─ ...\n",
+    "├─ README.txt\n",
+    "├─ setup.py\n",
+    "└─ setup.cfg\n",
+    "```\n",
+    "\n",
+    "* The `src/packagename` contains the source code of the library.\n",
+    "  - The `packagename` is what users type after `import` in a Python script, and therefore should not contain special characters.\n",
+    "  - It should contain a `__init__.py` that can be empty (more on that below).\n",
+    "  - The `src` segment prevents you from *shooting yourself in the foot*, because it's common to do `import packagename` when you are developing, and this will import the code from the directory, not from your `sys.path`. Always include it.\n",
+    "\n",
+    "* The `tests` directory contains the tests. It **must not** contain any `__init__.py` because it's not meant to be imported as a package. In very specific cases it's included inside `src/packagename`.\n",
+    "\n",
+    "* Every project contains a `README.txt` that at least explains what the project is.\n",
+    "\n",
+    "* `setup.py` can be an extremely simple file containing only this:\n",
+    "\n",
+    "```\n",
+    "from setuptools import setup\n",
+    "\n",
+    "setup()\n",
+    "```\n",
+    "\n",
+    "(This requires `setuptools > 30.3.0`, released 8 Dec 2016)\n",
+    "\n",
+    "* `setup.cfg` contains the metadata of the project. The absolutely required fields are `name`, `version`, and `packages`, therefore you will need something like this:\n",
+    "\n",
+    "```\n",
+    "[metadata]\n",
+    "name = my_package\n",
+    "version = 0.1.0\n",
+    "\n",
+    "# Magic! Don't touch below this line\n",
+    "[options]\n",
+    "package_dir=\n",
+    "    =src\n",
+    "packages=find:\n",
+    "\n",
+    "[options.packages.find]\n",
+    "where=src\n",
+    "```\n",
+    "\n",
+    "The `name` is what users will have to type after `pip install` and therefore can contain hyphens. **Do not confuse this** with what users have to type on `import` (see above).\n",
+    "\n",
+    "With this layout, **you can `pip install` your code** in your Python environment:\n",
+    "\n",
+    "```\n",
+    "$ pip install --editable .\n",
+    "$ python\n",
+    ">>> import packagename\n",
+    ">>>\n",
+    "```\n",
+    "\n",
+    "This is an alternative to modifying the `PYTHONPATH` environment variable (see first session)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Exercise\n",
+    "\n",
+    "1. Create a directory called `test-package`\n",
+    "2. `git init` inside it\n",
+    "3. Create a basic `src` layout in it, with `name = test-package` and the source in `src/test_package`\n",
+    "4. Create a `src/test_package/__init__.py` with a `print(\"Hello, world!\")`\n",
+    "5. Install it in editable mode using `pip` and test that `>>> import test_package` prints `Hello, world!`\n",
+    "6. Include a `README.txt` and an appropriate `.gitignore` from http://gitignore.io/\n",
+    "7. Commit the changes\n",
+    "8. Create a new GitHub project and push the repository there\n",
+    "\n",
+    "🎉"
+   ]
+  }
+ ],
+ "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.7.1"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}