modules_and_packages.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Modules and Packages"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Table of contents\n",
    "\n",
    "- [References](#References)\n",
    "- [Why?](#Why?)\n",
    "- [Script](#Script)\n",
    "- [Module](#Module)\n",
    "  - [Exercise on module creation](#Exercise-on-module-creation)\n",
    "  - [Module side-effects](#Module-side-effects)\n",
    "- [Package](#Package)\n",
    "  - [Exercise on package creation](#Exercise-on-package-creation)\n",
    "  - [Exercise on package refactoring](#Exercise-on-package-refactoring)\n",
    "  - [Different ways of importing things](#Different-ways-of-importing-things)\n",
    "  - [Application Programming Interface (API)](#Application-Programming-Interface-(API))\n",
    "  - [Exercise on defining the public API](#Exercise-on-defining-the-public-API)\n",
    "  - [Import `as`](#Import-as)\n",
    "  - [Stability of the API](#Stability-of-the-API)\n",
    "  - [Imports with `.`](#Imports-with-.)\n",
    "  - [Imports with `..`](#Imports-with-..)\n",
    "- [Install package](#Install-package)\n",
    "  - [Exercise: try to import the package from a different place](#Exercise:-try-to-import-the-package-from-a-different-place)\n",
    "  - [Make the package installable.](#Make-the-package-installable.)\n",
    "  - [Exercise on installing the package](#Exercise-on-installing-the-package)\n",
    "- [Outreach: share your package with the world](#Outreach:-share-your-package-with-the-world)\n",
    "  - [Git & GitHub](#Git-&-GitHub)\n",
    "    - [Exercise on creating a GitHub account.](#Exercise-on-creating-a-GitHub-account.)\n",
    "    - [Exercise on initializing a Git repository](#Exercise-on-initializing-a-Git-repository)\n",
    "    - [Exercise on creating a new repository on GitHub](#Exercise-on-creating-a-new-repository-on-GitHub)\n",
    "    - [Exercise on connecting the local Git repository to the remote GitHub repository](#Exercise-on-connecting-the-local-Git-repository-to-the-remote-GitHub-repository)\n",
    "    - [Exercise on making changes to the package and pushing them to GitHub](#Exercise-on-making-changes-to-the-package-and-pushing-them-to-GitHub)\n",
    "    - [Exercise: install a friend's package](#Exercise:-install-a-friend's-package)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# References\n",
    "\n",
    "* [Introduction to modules and packages](https://docs.python.org/3/tutorial/modules.html) from the official Python tutorial.\n",
    "* [Python Modules and Packages](https://realpython.com/python-modules-packages/) tutorial from Real Python.\n",
    "* [Python Packages](https://www.geeksforgeeks.org/python-packages/) tutorial from GeeksforGeeks.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Why?\n",
    "\n",
    "\"Why?\" is perhaps the most important question one should ask himself before doing something.\n",
    "We use modules and packages (in contrast to just writing all our code in one file) because it makes our code more organized and easier to maintain.\n",
    "This approach is known as [\"modular programming\"](https://en.wikipedia.org/wiki/Modular_programming) and is a fundamental concept in computer science.\n",
    "\n",
    "In this part of the tutorial, we will learn how to create modules and packages and how to use them in our code.\n",
    "We will also learn how to distribute our code as an installable package.\n",
    "We will start with a single file script and gradually convert it into a package."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Script\n",
    "Up to now, we mostly saw scripts, which are a sequence of statements in a single file or Jupyter cell.\n",
    "Scripts are great for quick and dirty work, but they are not very good for long-term projects because:\n",
    "\n",
    "* They are not well organized as they contain all the code in one place.\n",
    "* They are not easy to maintain.\n",
    "* They are not easy to reuse in other projects (unless you copy-paste the code).\n",
    "* They are not easy to distribute (unless you consider sending the file to your colleagues as an easy way of distributing).\n",
    "\n",
    "With these problems in mind, let's start with a simple example.\n",
    "Suppose we want to write a script that deals with points in 2D space.\n",
    "\n",
    "Here is a simple script that defines a class `Point` and a function `distance`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "class Point:\n",
    "    def __init__(self, x: float, y: float) -> None:\n",
    "        self.x = x\n",
    "        self.y = y\n",
    "\n",
    "def distance(p1: \"Point\", p2: \"Point\") -> float:\n",
    "    return ((p1.x - p2.x) ** 2 + (p1.y - p2.y) ** 2) ** 0.5\n",
    "\n",
    "p1 = Point(0, 0)\n",
    "p2 = Point(3, 4)\n",
    "print(f\"The distance between `p1` and `p2` is {distance(p1, p2)}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Module\n",
    "\n",
    "The [**module**](https://docs.python.org/3/tutorial/modules.html#modules) is a file containing Python definitions and statements.\n",
    "The file name is the module name with the suffix `.py` appended."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "\n",
    "## Creating your first module\n",
    "So our first task would be to create the module `point.py` and put the code from the previous section in it."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercise on module creation\n",
    "\n",
    "Move the `Point` class and the `distance` function to a new file called `point.py`:\n",
    "\n",
    "1. Create a new file called `point.py` in the same directory as this notebook.\n",
    "2. Copy **only** the `Point` class and the `distance` function to the new file.\n",
    "3. Save the file."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, since the module is in the same directory as this notebook, we can import things from it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from point import Point, distance\n",
    "\n",
    "p1 = Point(0, 0)\n",
    "p2 = Point(3, 4)\n",
    "print(f\"The distance between `p1` and `p2` is {distance(p1, p2)}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Very nice!\n",
    "We managed to create our first module and import it in our script."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Module side-effects\n",
    "\n",
    "To prevent issues for users importing your package, it's best to avoid running time-consuming computations or causing side effects at the top-level of a module. Keep in mind that all top-level code in a module is executed upon import.\n",
    "\n",
    "You can try this yourself:\n",
    "\n",
    "1. Create a new file called import_side_effect.py\n",
    "2. Copy these lines in your file:\n",
    "\n",
    "\n",
    "    ```python\n",
    "    import time\n",
    "\n",
    "    print(\"I will now sleep\")\n",
    "    time.sleep(5)\n",
    "    print(\"I am now awake\")\n",
    "\n",
    "    def some_function() -> int:\n",
    "        print(\"I don't do much\")\n",
    "    ```\n",
    "\n",
    "1. Save the file\n",
    "1. Now try this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from import_side_effect import some_function\n",
    "some_function()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you see, importing the module printed a first message on the terminal, then waited some time and then finally printed a message on the terminal again.\n",
    "Only after this process finished you were able to execute `some_function`.\n",
    "\n",
    "To avoid these problems, you should put these statements in a function that the user can call when they need it."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Package\n",
    "\n",
    "A **package** is a collection of related modules.\n",
    "\n",
    "For example, the `numpy` package contains the modules `numpy.core`, `numpy.linalg`, `numpy.random`, etc.\n",
    "\n",
    "A package is a directory that contains a file called `__init__.py`.\n",
    "This file can be empty.\n",
    "The presence of the file indicates that the parent directory is a Python package and can be imported the same way as a module."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercise on package creation\n",
    "\n",
    "Let's create a package named `mypackage` that contains our `point` module:\n",
    "\n",
    "1. Create a new directory called `mypackage` in the same directory as this notebook.\n",
    "2. Create a new empty file called `__init__.py` in the `mypackage` directory.\n",
    "3. Move the `point.py` file to the `mypackage` directory.\n",
    "\n",
    "Once this is done, let's see if we can import the `Point` class and the `distance` function from the `mypackage` package:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from mypackage.point import Point, distance\n",
    "\n",
    "p1 = Point(0, 0)\n",
    "p2 = Point(3, 4)\n",
    "print(f\"The distance between `p1` and `p2` is {distance(p1, p2)}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Congratulations, we managed to create a package and import it here!\n",
    "\n",
    "Suppose our package grows and we need to do some refactoring.\n",
    "We can take the `distance` function to a new modules called `utils.py`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercise on package refactoring\n",
    "\n",
    "Let's move the `distance` function to a new module called `utils.py`:\n",
    "\n",
    "1.  In the `mypackage` folder, create a new file called `utils.py`.\n",
    "2.  Copy the `distance` function to the new file and save it.\n",
    "3.  Remove the `distance` function from the `point.py` file, and save it.\n",
    "\n",
    "If everything went well, we should be able to execute the following code:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from mypackage.point import Point\n",
    "from mypackage.utils import distance\n",
    "\n",
    "p1 = Point(0, 0)\n",
    "p2 = Point(3, 4)\n",
    "print(f\"The distance between `p1` and `p2` is {distance(p1, p2)}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Nice!\n",
    "The `distance` function is now in the `utils` module under the `mypackage` package."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Different ways of importing things\n",
    "\n",
    "There are several ways to import things from a module or package.\n",
    "Let's see some examples:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Same as above:**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from mypackage.point import Point\n",
    "from mypackage.utils import distance\n",
    "\n",
    "p1 = Point(0, 0)\n",
    "p2 = Point(3, 4)\n",
    "print(f\"The distance between `p1` and `p2` is {distance(p1, p2)}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Import only the `mypackage` package:**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "import mypackage\n",
    "\n",
    "p1 = mypackage.point.Point(0, 0)\n",
    "p2 = mypackage.point.Point(3, 4)\n",
    "\n",
    "print(f\"The distance between `p1` and `p2` is {mypackage.utils.distance(p1, p2)}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "**Import `point` and `utils` modules from `mypackage`:**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from mypackage import point, utils\n",
    "\n",
    "p1 = point.Point(0, 0)\n",
    "p2 = point.Point(3, 4)\n",
    "\n",
    "print(f\"The distance between `p1` and `p2` is {utils.distance(p1, p2)}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can improve things a bit more, but before we do that, let's first introduce the concept of Application Programming Interface (API)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Application Programming Interface (API)\n",
    "\n",
    "An [**Application Programming Interface** (API)](https://en.wikipedia.org/wiki/API) stands for a set of publicly available classes, functions, and variables that a software program can use to interact with other software components.\n",
    "\n",
    "When developing a package, we often import things from its modules into the `__init__.py` file.\n",
    "This way we can access the things using `mypackage.Point` and `mypackage.distance`.\n",
    "Everything imported into the topmost `__init__.py` file is considered to be part of the package's public API.\n",
    "\n",
    "For example, in the `mypackage` we can import the `Point` class and the `distance` function into the `__init__.py` file.\n",
    "Let's do it as the next exercise."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-block alert-warning\">\n",
    "<b>Attention:</b> Things imported in the topmost <code>__init__.py</code> are the public API of your package.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercise on defining the public API\n",
    "\n",
    "Please import the `Point` class and the `distance` function into the `__init__.py` file.\n",
    "\n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "<b>Hint:</b> often, when importing things from local modules, we use the following syntax: <br>    \n",
    "<code>from .module import thing</code>\n",
    "\n",
    "</div>\n",
    "\n",
    "\n",
    "In our case, the `.` stands for the current directory, so the `.` in the above code means the `mypackage` directory.\n",
    "We will see more examples of this syntax later.\n",
    "\n",
    "If everything went well, we should be able to execute the following code:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-block alert-warning\">\n",
    "    <b> Warning: </b> Sometimes for the code below to work you need to restart the Python kernel. Find the <b>Kernel</b> menu at the top and then choose <b>Restart Kernel</b>.\n",
    "The reason for this is that Python has imported the package before, and it is too lazy to import it again.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from mypackage import Point, distance\n",
    "\n",
    "p1 = Point(0, 0)\n",
    "p2 = Point(3, 4)\n",
    "print(f\"The distance between `p1` and `p2` is {distance(p1, p2)}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Import `as`\n",
    "\n",
    "It is possible to import a package and access its content throughout the code via its namespace (in this case, `mypackage`):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "import mypackage\n",
    "\n",
    "p1 = mypackage.Point(0, 0)\n",
    "p2 = mypackage.Point(3, 4)\n",
    "print(f\"The distance between `p1` and `p2` is {mypackage.distance(p1, p2)}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "But if the package name is rather long, it is possible to import it under a shorter name.\n",
    "For example, we can import the `mypackage` package as `mp`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "import mypackage as mp\n",
    "\n",
    "p1 = mp.Point(0, 0)\n",
    "p2 = mp.Point(3, 4)\n",
    "print(f\"The distance between `p1` and `p2` is {mypackage.distance(p1, p2)}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The last two examples are probably the best way to use packages.\n",
    "If the package name is short, we can import it under its original name.\n",
    "If the package name is long, we can import it under a shorter alias.\n",
    "\n",
    "For some packages (like `numpy` and `pandas`), it has become a convention to import them under their aliases.\n",
    "For example, we often use `np` for `numpy` and `pd` for `pandas`:\n",
    "\n",
    "```python\n",
    "import numpy as np\n",
    "import pandas as pd\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Stability of the API\n",
    "\n",
    "When you're developing a package, it's important to remember that the public API forms a crucial part of the package's agreement with its users.\n",
    "As developers, we should strive to keep the API stable and not change it too often.\n",
    "It is OK to add new features to the package, but it is not OK to suddenly change the API of the existing features.\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "<b>Info:</b>  The API of a package is considered to be stable when the changes to it are rare and well-documented. If the API changes too often, users might look for another, more reliable alternative.\n",
    "</div>\n",
    "\n",
    "Suppose we would like to introduce a new class called `Line` to our package.\n",
    "Here is the code:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "class Line:\n",
    "    def __init__(self, p1: \"Point\", p2: \"Point\") -> None:\n",
    "        self.p1 = p1\n",
    "        self.p2 = p2\n",
    "\n",
    "    def length(self) -> float:\n",
    "        return ((self.p1.x - self.p2.x) ** 2 + (self.p1.y - self.p2.y) ** 2) ** 0.5"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We want to place it with the `Point` class, but the module name is `point.py`, which doesn't make sense anymore.\n",
    "We should rename the module to something like `geometry.py`.\n",
    "\n",
    "## Exercise on adding new class to the package\n",
    "\n",
    "1.  Rename the `point.py` file to `geometry.py`.\n",
    "2.  Copy the `Line` class to the `geometry.py` file.\n",
    "3.  Update the import statements in the `__init__.py` file to import the `Point` and `Line` classes from the `geometry` module.\n",
    "\n",
    "```python\n",
    "from .geometry import Point, Line\n",
    "```\n",
    "\n",
    "<div class=\"alert alert-block alert-warning\">\n",
    "    <b> Warning: </b> Before trying the cell below you might need to restart Python kernel again (Kernel -> Restart Kernel).\n",
    "</div>\n",
    "\n",
    "\n",
    "If everything went well, we should be able to execute the following code:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "import mypackage as mp\n",
    "\n",
    "p1 = mp.Point(0, 0)\n",
    "p2 = mp.Point(3, 4)\n",
    "\n",
    "line = mp.Line(p1, p2)\n",
    "\n",
    "print(f\"The length of the line is {line.length()}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We did a good job maintaining the public API of our package 👍.\n",
    "We added a new class to the package and changed the module name, but nothing changed for the users.\n",
    "The old-good `Point` class is still available under the `mypackage.Point` name."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Imports with `.`\n",
    "\n",
    "To import things from the neighbouring modules, we can use the `.` symbol.\n",
    "We did it a few times already when we were editing `__init__.py`\n",
    "Now, let's have a look at our `Line` class again.\n",
    "You might notice that the body of the `length` method is essentially the same as the `distance` function we had in the `utils.py` module.\n",
    "Let's import it from there.\n",
    "\n",
    "## Exercise on importing from neighboring modules.\n",
    "\n",
    "1. Import the `distance` function from the `utils` module in the `geometry` module.\n",
    "```python\n",
    "    from .utils import distance\n",
    "```\n",
    "2. Update the `length` method of the `Line` class to use the `distance` function.\n",
    "3. Store both files and run the following code:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "import mypackage as mp\n",
    "\n",
    "p1 = mp.Point(0, 0)\n",
    "p2 = mp.Point(3, 4)\n",
    "\n",
    "line = mp.Line(p1, p2)\n",
    "\n",
    "print(f\"The length of the line is {line.length()}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Imports with `..`\n",
    "\n",
    "Sometimes we need to import things from the modules that are located in the parent directory.\n",
    "For that we can use the `..` symbol.\n",
    "The `..` symbol means the parent directory, so `..` in the following code means the `mypackage` directory.\n",
    "\n",
    "```python\n",
    "from ..utils import distance\n",
    "```\n",
    "\n",
    "Let's reorganise our package a bit to see how it works.\n",
    "\n",
    "\n",
    "## Exercise on importing from parent modules\n",
    "\n",
    "1. Create a new directory called `geometry` in the `mypackage` directory.\n",
    "2. Move the `geometry.py` file to the geometry directory.\n",
    "3. Create an empty file called `__init__.py` in the geometry directory.\n",
    "4. Add the following import statement to the `__init__.py` file:\n",
    "```python\n",
    "from .geometry import Point, Line\n",
    "```\n",
    "5. Update the import statement in the `geometry.py` file to import the `distance` function from the `utils` module to take into account the relative location of the `utils` module:\n",
    "```python\n",
    "from ..utils import distance\n",
    "```\n",
    "6. Store everything and restart the Python kernel (Kernel -> Restart Kernel).\n",
    "7. Run the code below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "import mypackage as mp\n",
    "\n",
    "p1 = mp.Point(0, 0)\n",
    "p2 = mp.Point(3, 4)\n",
    "\n",
    "line = mp.Line(p1, p2)\n",
    "\n",
    "print(f\"The length of the line is {line.length()}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Hopefully, everything went well, and you were able to execute the code above.\n",
    "\n",
    "We learned how to import things from the neighbouring and the parent modules.\n",
    "We also learned that it is possible to create sub-packages and import things from them."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Install package\n",
    "\n",
    "Now that we have a package, we should be able to install it with a little bit of work.\n",
    "\n",
    "Why do we want to install it?\n",
    "Well, if we want to use our package in another project, we need to install it.\n",
    "Right now it can only be imported from the directory where it is located.\n",
    "\n",
    "See that for yourself."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercise: try to import the package from a different place\n",
    "\n",
    "1. Create a new directory called `tmp_dir` (or similar).\n",
    "2. Create a new notebook by right click of the mouse and selecting `New Notebook` from the context menu.\n",
    "3. In the new notebook, try to import the `mypackage` package.\n",
    "\n",
    "This should fail, because the `mypackage` package is not installed in your system:\n",
    "\n",
    "```python\n",
    "\n",
    "import mypackage\n",
    "\n",
    "\n",
    "---------------------------------------------------------------------------\n",
    "ModuleNotFoundError                       Traceback (most recent call last)\n",
    "Cell In[1], line 1\n",
    "----> 1 import mypackage\n",
    "\n",
    "ModuleNotFoundError: No module named 'mypackage'\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Make the package installable.\n",
    "\n",
    "To make the package installable, we need to do a few more things.\n",
    "Typically, this is done by creating the `pyproject.toml` file.\n",
    "`pyproject.toml` is a configuration file that contains the build system requirements and the package metadata.\n",
    "It is used by the build tools like `flit` or `poetry` to build and install the package.\n",
    "It is also used by other tools like `black` and `mypy` to configure their behaviour.\n",
    "\n",
    "The [`toml` format](https://toml.io/) is a configuration file format that is easy to read and write for humans (unlike `json`).\n",
    "It is quite flexible but not as complex as the `yaml` format.\n",
    "Another advangtage of the `toml` format is that it is pre-installed in Python, so you don't need to install any additional packages to use it.\n",
    "\n",
    "\n",
    "Here is a minimal example of the `pyproject.toml`: \n",
    "\n",
    "```toml\n",
    "[build-system]\n",
    "requires = [\"flit_core >=3.2,<4\"]\n",
    "build-backend = \"flit_core.buildapi\"\n",
    "\n",
    "[project]\n",
    "name = \"mypackage\"\n",
    "version = \"0.1.0\"\n",
    "description = \"My first package\"\n",
    "```\n",
    "\n",
    "The package directory should look like this:\n",
    "\n",
    "```bash\n",
    "mypackage/\n",
    "├── mypackage\n",
    "│   ├── __init__.py\n",
    "│   ├── geometry\n",
    "│   │   ├── __init__.py\n",
    "│   │   └── geometry.py\n",
    "│   └── utils.py\n",
    "└── pyproject.toml\n",
    "```\n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "    <b> Notice: </b> we moved our original <code>mypackage</code> directory to <code>mypackage/mypackage</code>. This is common practice for Python packages.\n",
    "</div>\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercise on installing the package\n",
    "\n",
    "1. Inside the `mypackage` directory, we need to create another directory called `mypackage`.\n",
    "2. Move the `geometry` directory together with `__init__.py` and `utils.py` files to the freshly-created `mypackage` sub-directory.\n",
    "3. Create a new file called `pyproject.toml` in the top-level `mypackage` directory with the content from the cell above.\n",
    "4. Open the terminal (`File` -> `New Launcher`, then select `Terminal`), and run the following command to install `mypackage`:\n",
    "```bash\n",
    "    $ pip install mypackage/\n",
    "```\n",
    "5. Return to the new notebook we created in the previous exercise and try to import the `mypackage` package again.\n",
    "\n",
    "\n",
    "Congratulations, now your package is installed and you can import it from anywhere!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Outreach: share your package with the world\n",
    "\n",
    "Now that we have a package, we can share it with people around the world.\n",
    "There are many ways to do that, but in this turorial we will focus on [GitHub](https://github.com/)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Git & GitHub\n",
    "\n",
    "[Git](https://git-scm.com/) is a version control system.\n",
    "It allows you to track changes in your code and collaborate with other people.\n",
    "GitHub is a website that hosts Git repositories.\n",
    "It adds even more features to Git, like issue tracking, pull requests, and code review.\n",
    "It is almost impossible to imagine a modern software development without Git.\n",
    "\n",
    "If you want to share your package with the world, [GitHub](https://github.com/) is a great place to start.\n",
    "But there are a few things you need to do before you can share your package."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Exercise on creating a GitHub account.\n",
    "\n",
    "1. [Create a new account](https://github.com/signup?source=login) on GitHub. Skip this exercise if you have one already.\n",
    "\n",
    "<div class=\"alert alert-block alert-warning\"><b>Warning:</b> Please choose a meaningful username.</div>\n",
    "\n",
    "You can still change it later, but it is better not to do it at all due to [unwanted consequences](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/changing-your-github-username).\n",
    "For example, John Doe can use `johndoe`, `john.doe`, `johnd`, `jdoe`, etc.\n",
    "\n",
    "2. [Create an access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-personal-access-token-classic) for your account that will be used instead of your password."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once the account is created we can start working on the package.\n",
    "The first thing we need to do is to initialize a Git repository in the package directory."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "### Exercise on initializing a Git repository\n",
    "\n",
    "1. Open the terminal and navigate to the `mypackage` directory.\n",
    "2. Run the following command to initialize a Git repository:\n",
    "```bash\n",
    "    $ git init\n",
    "```\n",
    "3. Create a new file named `.gitignore` (do **not** forget the leading `.`) in the package directory with the following content to exclude some temporary files from the repository:\n",
    "```\n",
    "    .ipynb_checkpoints\n",
    "    __pycache__\n",
    "```\n",
    "4. Run the following command to add all files to the staging area:\n",
    "```bash\n",
    "    $ git add .\n",
    "```\n",
    "<div class=\"alert alert-block alert-warning\">\n",
    "<b>Warning:</b> the dot (<code>.</code>) means <b>all files</b> in the current directory **except** those listed in the <code>.gitignore</code> file.\n",
    "Git does not track files that are listed in the <code>.gitignore</code> file.\n",
    "The <code>.gitignore</code> file, however, should be committed to the repository.\n",
    "</div>\n",
    "\n",
    "5. Review the changes that will be committed:\n",
    "```bash\n",
    "    $ git status\n",
    "```\n",
    "\n",
    "6. Run the following command to commit the changes:\n",
    "```bash\n",
    "    $ git commit -m \"Initial commit\"\n",
    "```\n",
    "\n",
    "Now, we have a Git repository with the initial commit.\n",
    "We can push it to GitHub.\n",
    "But first, we need to create a new repository on GitHub."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "### Exercise on creating a new repository on GitHub\n",
    "\n",
    "\n",
    "1. Go to [the following link](https://github.com/new) to create a new repository.\n",
    "2. Enter the repository name as `mypackage`, add a descprition if you want to, and leave the rest of the options as they are.\n",
    "3. Click on the `Create repository` button.\n",
    "\n",
    "\n",
    "Ok, the repository is created.\n",
    "Now we need to connect it to the local Git repository."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Exercise on connecting the local Git repository to the remote GitHub repository\n",
    "\n",
    "1. Have a look at your new repository on GitHub. You should see a message like this:\n",
    "\n",
    "    > …or push an existing repository from the command line\n",
    "\n",
    "2. Copy the command that starts with `git remote add origin...` (all three of them) and paste it into the terminal. Enter your GitHub username and token generated earlier instead of the password.\n",
    "3. Reload the page on GitHub. You should see the files from the local Git repository.\n",
    "\n",
    "Congratulations, your package is now on GitHub!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "### Exercise on making changes to the package and pushing them to GitHub\n",
    "\n",
    "1. Open the `mypackage/__init__.py` file and add the following lines to the end of the file:\n",
    "```python\n",
    "def personal_message():\n",
    "    print(\"Hello from <your name>!\")  # Replace <your name> with your actual name\n",
    "```\n",
    "2. Create a new file called `README.md` in the top-level `mypackage` directory with the following content:\n",
    "```markdown\n",
    "# My first package\n",
    "\n",
    "This is my first package.\n",
    "\n",
    "# Installation\n",
    "$ pip install git+<specify the URL of your package here>\n",
    "\n",
    "```\n",
    "\n",
    "3. Run the following commands to add the changes to the staging area and commit them:\n",
    "```bash\n",
    "    $ git add .\n",
    "    $ git commit -m \"Add personal message and README\"\n",
    "```\n",
    "\n",
    "4. Run the following command to push the changes to GitHub:\n",
    "```bash\n",
    "    $ git push\n",
    "```\n",
    "\n",
    "5. Reload the page on GitHub. You should see the changes you made."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Exercise: install a friend's package\n",
    "\n",
    "1. Uninstall the `mypackage` package:\n",
    "```bash\n",
    "    $ pip uninstall mypackage\n",
    "```\n",
    "2. Ask another tutorial's participant to share the URL of their package with you.\n",
    "3. Open the URL and study the README file.\n",
    "4. Install the package using the instructions from the README file.\n",
    "5. Import the package and run the `personal_message` function.\n",
    "```python\n",
    "import mypackage\n",
    "mypackage.personal_message()\n",
    "```\n",
    "\n",
    "Hooray, you have just installed your first package from GitHub made by your friend!"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.9.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}