intro.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introduction to the tutorial"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "## Table of Contents\n",
    "\n",
    "- [Timetable](#Timetable)\n",
    "- [How to interact](#How-to-interact)\n",
    "- [How to run the tutorial](#How-to-run-the-tutorial)\n",
    "    - [With GitHub Codespaces](#With-GitHub-Codespaces)\n",
    "    - [With Binder](#With-Binder)\n",
    "    - [On your laptop](#On-your-laptop)\n",
    "- [How to use Jupyter Lab and the notebooks](#How-to-use-Jupyter-Lab-and-the-notebooks)\n",
    "    - [Cells](#Cells)\n",
    "    - [Store your progress](#Store-your-progress)\n",
    "    - [Simple view](#Simple-view)\n",
    "    - [File browser](#File-browser)\n",
    "    - [Terminal](#Terminal)\n",
    "- [Exercises 🌶️](#Exercises-🌶️)\n",
    "    - [Exercise example](#Exercise-example)\n",
    "    - [Exercise variables](#Exercise-variables)\n",
    "    - [Exercise difficulty](#Exercise-difficulty)\n",
    "- [Hands-on sessions](#Hands-on-sessions)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Welcome! 🐍\n",
    "\n",
    "Hello and welcome, everyone! We’re excited that you chose to embark in this Python journey.\n",
    "\n",
    "Over **three** days, we'll see a lot of Python. **Two** topics each day:\n",
    "\n",
    "### Day 1\n",
    "1. Basic syntax and data types\n",
    "2. Control flow, loops, and exceptions\n",
    "\n",
    "### Day 2\n",
    "1. Functions\n",
    "2. Working with files\n",
    "\n",
    "### Day 3\n",
    "1. Object-oriented programming\n",
    "2. Modules and packages\n",
    "\n",
    "Although this is an introductory course, we will go in-depth to cover as much ground as possible.\n",
    "We aim to equip you with a strong foundation in Python programming that you can build on in the future.\n",
    "So, let's get started!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Timetable\n",
    "\n",
    "Here is the schedule we'll be following each day:\n",
    "\n",
    "- 9:30-10:00 — Welcome coffee\n",
    "- 10:00-12:00 — Topic 1 (theory, hands-on, Q&A)\n",
    "- *12:00-13:00 — Lunch Break*\n",
    "- 13:00-15:00 — Topic 2 (theory, hands-on, Q&A)\n",
    "- 15:00-16:00 — Practice, discussions and additional Q&A"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# How to interact\n",
    "\n",
    "Each block will contain both theory and hands-on.\n",
    "Remember that interaction between us is **essential**.\n",
    "We encourage you to actively participate and ask questions.\n",
    "\n",
    "## On GitHub\n",
    "- For any other question you might have about the workshop, feel free to post a message in the [discussions](https://github.com/empa-scientific-it/python-tutorial/discussions).\n",
    "- If you come across any bug or have suggestions on how we could improve the content and exercises, feel free to open a new [issue](https://github.com/empa-scientific-it/python-tutorial/issues).\n",
    "\n",
    "GitHub is much better suited to hold continued Q&A and other discussions, even after the tutorial ends.\n",
    "Please, use it."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# How to run the tutorial\n",
    "\n",
    "We designed the tutorial as a hands-on workshop. You should try to write as much code as possible to practice the foundational concepts."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## With GitHub Codespaces\n",
    "\n",
    "GitHub Codespaces is a cloud-based development environment that allows developers to code directly within their web browser, through Visual Studio Code, or Jupyter Lab.\n",
    "It provides a fully configured development environment, including the necessary tools, libraries, and dependencies, tailored to the specific needs of your project.\n",
    "\n",
    "We are going to show you in practice how to create a codespace and run the tutorial inside it, but here a step-by-step guide.\n",
    "From the repository on GitHub:\n",
    "\n",
    "**(1) Sign in to GitHub:**\n",
    "\n",
    "- Ensure you are logged into your GitHub account.\n",
    "\n",
    "**(2) Open the Codespaces Tab:**\n",
    "\n",
    "- Once you are on the repository's main page, look for the \"Code\" button (usually green) near the top right of the page.\n",
    "- Click on the \"Code\" button to reveal a dropdown menu.\n",
    "- In the dropdown menu, you will see a \"Codespaces\" tab. Click on it.\n",
    "\n",
    "**(3) Create a New Codespace:**\n",
    "\n",
    "- In the \"Codespaces\" tab, you will see an option to create a new Codespace. Click on the \"New codespace\" button.\n",
    "- GitHub will start setting up your Codespace. This process involves provisioning a virtual machine, cloning the repository, and setting up the development environment based on the repository's configuration files.\n",
    "\n",
    "**(4) Access Your Codespace:**\n",
    "\n",
    "- Once the setup is complete, you will be automatically redirected to your new Codespace. This environment will be accessible either through your web browser or through Visual Studio Code if you prefer a desktop application.\n",
    "- You can now start coding, running, and debugging your application directly within this environment\n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "    <h4><b>Note</b></h4>\n",
    "    We <b>strongly</b> suggest you to work with the tutorial material via Jupyter Lab because Visual Studio Code is not 100% compatible with all the notebooks' features.\n",
    "    You can start Jupyter Lab in your Codespace from the \"Code\" button as shown in the following screenshot.\n",
    "</div>\n",
    "\n",
    "<img src=\"images/codespaces-jupyterlab.png\" alt=\"Jupyter Lab in Codespaces\" width=\"600\"/>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## With Binder\n",
    "\n",
    "[Binder](https://mybinder.org/) is a service that allows you to run Jupyter Notebooks in the cloud.\n",
    "It's free and requires no installation.\n",
    "You can use it by clicking the `launch|binder` button on the main page of the [official repository on GitHub](https://github.com/empa-scientific-it/python-tutorial) of the tutorial.\n",
    "\n",
    "Once you click on the link, you will be redirected to the startup page of Binder, which looks like this:\n",
    "\n",
    "<img src=\"images/binder.png\" alt=\"Binder\" width=\"800\"/>\n",
    "\n",
    "Once the startup is completed (it may take a few minutes), you will be redirected to a Jupyter Lab instance running in the cloud.\n",
    "The starting page contains the links to the notebooks of the tutorial.\n",
    "\n",
    "\n",
    "<div class=\"alert alert-block alert-warning\">\n",
    "    <h4><b>Warning</b></h4>\n",
    "    Binder is free, so it provides limited resources.\n",
    "After 10 minutes of inactivity, your Binder instance will be shut down.\n",
    "You will lose all your work.\n",
    "To avoid this, please save your work regularly.\n",
    "See more about saving later in this notebook.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## On your laptop\n",
    "\n",
    "You can also run the tutorial locally, on your laptop.\n",
    "We warmly suggest you to choose this route as a last resort since it might take some time to properly install/configure all the prerequisites.\n",
    "Please, refer to the [README](https://github.com/empa-scientific-it/python-tutorial/blob/main/README.md#run-the-tutorial-on-your-computer) for detailed instructions.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# How to use Jupyter Lab and the notebooks\n",
    "\n",
    "Jupyter Lab is a web-based interactive development environment for Jupyter notebooks, code, and data.\n",
    "We have prepared a set of notebooks for you to follow along during the tutorial.\n",
    "Each notebook covers a specific topic and contains both theory and hands-on."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Cells\n",
    "\n",
    "The content of the notebooks is organized in cells.\n",
    "We will work with two types of cells: **Markdown** and **Code**.\n",
    "Markdown cells contain text, while Code cells contain Python code.\n",
    "We put all the theory in Markdown cells and all the hands-on in Code cells.\n",
    "To execute a Code cell, you can either click on the `Run` button in the toolbar or press `Shift+Enter` on your keyboard.\n",
    "Once the cell is executed, the output will be displayed below the cell.\n",
    "The next cell will be automatically selected, so you can press `Shift+Enter` again to execute it.\n",
    "\n",
    "Try to execute the cell below to see how it works in practice:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# Run this cell by clicking on it and pressing Shift+Enter.\n",
    "\n",
    "print(\"Hello, world!\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# And this one too.\n",
    "\n",
    "print(\"Goodbye!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Congratulations!\n",
    "You have just executed your first Python code!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Store your progress\n",
    "\n",
    "While working on the notebooks, you will probably want to save your progress.\n",
    "How to do it depends on where you are running the tutorial.\n",
    "\n",
    "### In GitHub Codespaces\n",
    "\n",
    "With either Jupyter Lab or Visual Studio Code, saving your work in your Codespace works the same as if you were working on your laptop.\n",
    "\n",
    "In Jupyter Lab, you can use the \"File\" menu (`File > Save Notebook`) or simply use the shortcuts `Ctrl+S` (Windows/Linux) or `Cmd+S` (macOS).\n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "    <h4><b>Note</b></h4>\n",
    "    <h5>Codespace resources</h5>\n",
    "    Running a GitHub Codespace consume resources (storage and compute). GitHub will provide each Free plan account 120 core hours, or 60 hours of run time for a 2 core codespace, plus 15 GB of storage to use <b>each month</b>. If you exceed these quotas, you are going to be <a href=\"https://docs.github.com/en/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces\">billed</a> for the extra resources.\n",
    "</div>\n",
    "\n",
    "<div class=\"alert alert-block alert-warning\">\n",
    "    <h4><b>Warning</b></h4>\n",
    "    <h5>Automatic deletion</h5>\n",
    "    By default, a Codespace that has been stopped for <b>more than 30 days</b> is automatically deleted by GitHub. Make sure you save your work <b>outside</b> your Codespace before stopping it. If you need help, don't hesitate to ask during the tutorial.\n",
    "</div>\n",
    "\n",
    "### In Binder\n",
    "\n",
    "With Binder you cannot just press `Ctrl+S` (or `Cmd+S`) to save your work - the notebook will be stored on the server, which is not accessible to you.\n",
    "A better solution is to use those buttons in the toolbar:\n",
    "\n",
    "<img src=\"images/save_binder.png\" alt=\"Save\"/>\n",
    "\n",
    "The arrow down button is for storing the notebook in your browser storage.\n",
    "The arrow up button is for restoring the notebook from your browser storage.\n",
    "\n",
    "To try that out, please do the following:\n",
    "\n",
    "1. Add some text to the cell below.\n",
    "2. Press the arrow down button to save the notebook.\n",
    "3. Close the browser tab with the notebook.\n",
    "4. Open the notebook again.\n",
    "5. Press the arrow up button to restore the notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "## Add your changes here\n",
    "\n",
    "print(\"modify me!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-block alert-warning\">\n",
    "    <h4><b>Warning</b></h4>\n",
    "    The procedure described above will only work if you don't close the browser window.\n",
    "If you close your browser, it would be better to download the notebook to your computer.\n",
    "To do so, go to <code>File</code> -> <code>Download</code>.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Simple view\n",
    "\n",
    "By default, Jupyter Lab on Binder is opened in the \"Simple view\" mode.\n",
    "This means only the current notebook is visible.\n",
    "\n",
    "To see all the other open notebooks, you can disable the \"Simple\" view in the left sidebar:\n",
    "\n",
    "<img src=\"images/simple_view.png\" alt=\"Simple view\"/>\n",
    "\n",
    "Once this is done, you will see all the open notebooks in the top bar and browse them by clicking on the corresponding tab:\n",
    "\n",
    "<img src=\"images/open_notebooks.png\" alt=\"Tabs\"/>\n",
    "\n",
    "You can even open multiple notebooks side by side by dragging the notebook header to the right or the left."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## File browser\n",
    "\n",
    "You can also browse the files on your Binder instance by clicking on the folder icon in the left sidebar:\n",
    "\n",
    "<img src=\"images/file_browser.png\" alt=\"File browser\"/>\n",
    "\n",
    "Once you are in the file browser, you can navigate the file system of your Binder instance.\n",
    "You can also create new files and folders, rename them, and delete them.\n",
    "To do so, right-click on the file or folder you want to modify and select the corresponding action from the context menu."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Terminal\n",
    "\n",
    "You can also open a terminal on your Binder instance by clicking on the terminal icon in the Launcher:\n",
    "\n",
    "<img src=\"images/terminal.png\" alt=\"Terminal\"/>\n",
    "\n",
    "To start the launcher, go to `File` -> `New Launcher` in the top menu."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Exercises 🌶️\n",
    "\n",
    "For each topic we prepared a bunch of exercises to practice the concepts.\n",
    "\n",
    "In the notebooks, you will see cells like the following one:\n",
    "\n",
    "```python\n",
    "%%ipytest\n",
    "\n",
    "def solution_to_exercise(input_arg):\n",
    "    \"\"\"Write your solution here.\"\"\"\n",
    "    pass\n",
    "```\n",
    "\n",
    "**Unless otherwise noted**, you can delete everything **below** the line starting with `def` and write your solution.\n",
    "Your **should not** modify the name of the function (in this case `solution_to_exercise`) and its arguments (in this case `input_arg`)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercise example\n",
    "\n",
    "Let's try to solve a simple exercise.\n",
    "\n",
    "In the cell below, you are supposed to write a program that returns the sum of two numbers.\n",
    "\n",
    "```python\n",
    "%%ipytest\n",
    "\n",
    "def solution_sum_two_numbers(a: int, b: int) -> int:\n",
    "    \"\"\"Write your solution here.\"\"\"\n",
    "    pass\n",
    "```\n",
    "\n",
    "We need to complete the code of the function above to return the sum of the two arguments, `a` and `b`.\n",
    "\n",
    "Here is how the solution could look like:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "%reload_ext tutorial.tests.testsuite"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "%%ipytest\n",
    "\n",
    "def solution_sum_two_numbers(a: int, b: int) -> int:\n",
    "    correct_sum = a + b\n",
    "    return correct_sum"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Since the solution above was correct, the cell will be executed without errors.\n",
    "\n",
    "Let's try to provide a wrong solution:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "%%ipytest\n",
    "\n",
    "def solution_sum_two_numbers(a: int, b: int) -> int:\n",
    "    wrong_sum = a - b -\n",
    "    return wrong_sum"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you can see, the message quite clearly tells you that the solution is wrong.\n",
    "\n",
    "The tests that are run on your solution also give you an hint on the **expected result**. You need to revisit your code and try to understand what went wrong.\n",
    "\n",
    "After 3 failed attempts, a proposed solution will be revealed.\n",
    "\n",
    "<div class=\"alert alert-block alert-warning\">\n",
    "    <h4><b>Note</b></h4>\n",
    "    The input arguments or the expected results of an exercise can be <strong>quite long</strong>. The output of the tests might be a bit difficult to navigate. If you need help with that, just <strong>ask</strong> 😉.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercise variables\n",
    "\n",
    "Let's look at one important detail about exercises: the variables in **your solution** you are expected to work with.\n",
    "\n",
    "```python\n",
    "%%ipytest\n",
    "\n",
    "def solution_longest_sequence(numbers: list[int]) -> int:\n",
    "    \"\"\"Write your solution here.\"\"\"\n",
    "    pass\n",
    "```\n",
    "You should treat `numbers` as a \"list of integers\".\n",
    "It will be already defined when you run this function, so you don't need to define it yourself.\n",
    "\n",
    "<div class=\"alert alert-block alert-danger\">\n",
    "    <h4><b>Important</b></h4>\n",
    "    The input arguments to the <code>solution_*</code> function <strong>is already available</strong>. We also tell you what <strong>type</strong> you should expect: a string, an integer, a file path, or anything else.\n",
    "</div> \n",
    "\n",
    "\n",
    "Remember: **ask** if you need help.\n",
    "These days should be a practical workshop where we can answer to most of your questions you have as a beginner Python user.\n",
    "Let's make the most out of this time!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "## Exercise difficulty\n",
    "\n",
    "\n",
    "The \"chili\" 🌶️ symbol estimates the effort required.\n",
    "In general, more chilis mean more work and thinking to solve the exercise.\n",
    "\n",
    "Double-check before deleting everything in a solution's cell.\n",
    "There might be useful hints to solve the exercise!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Hands-on sessions\n",
    "\n",
    "There will be plenty of time to work on the exercises."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Let's get started! 🐍"
   ]
  }
 ],
 "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.10.15"
  },
  "vscode": {
   "interpreter": {
    "hash": "fb43f8d381edd655b57a3fa7f8143253a121a168968fa3987191db33f90c378d"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}