intro.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introduction to the tutorial"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Table of Contents"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "# Table of contents\n",
    "- [Welcome! 🐍](#Welcome!-🐍)\n",
    "- [Timetable](#Timetable)\n",
    "- [How to interact](#How-to-interact)\n",
    "- [Binder only](#Binder-only)\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)\n",
    "- [Let's get started! 🐍](#Let's-get-started!-🐍)"
   ]
  },
  {
   "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 **four** days, we'll see a lot of Python. **Two** topics each day\n",
    "\n",
    "### Day 1\n",
    "1. Introduction to the course\n",
    "2. Basic syntax and data types\n",
    "\n",
    "### Day 2\n",
    "1. Control flow, loops, and exceptions\n",
    "2. Functions\n",
    "\n",
    "\n",
    "### Day 3\n",
    "1. Working with files\n",
    "2. Functional programming\n",
    "\n",
    "### Day 4\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",
    "We'll be following the following schedule for each day:\n",
    "\n",
    "- 8:45-9:00 — Welcome, warm-up questions\n",
    "- 9:00-10:50 — Topic 1 (theory, hands-on, Q&A)\n",
    "- *10:50-11:10 — Break* ☕\n",
    "- 11:10-13:00 — Topic 2\n",
    "- 🥪 – Practice – Offline discussions on Slack"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# How to interact\n",
    "\n",
    "Each block will contain both theory and hands-on.\n",
    "It's an online workshop, so interaction between us is **essential**.\n",
    "\n",
    "A few tips to interact:\n",
    "\n",
    "## On Zoom\n",
    "- Raise your hand 🤚 then ask.\n",
    "- Write in the chat.\n",
    "- We will open a break-out room to address long questions. **Anyone** interested can jump in.\n",
    "\n",
    "\n",
    "## On Slack\n",
    "- Ask your question in the **corresponding channel**. Use `#help` for generic questions.\n",
    "- Reply **in a thread** if you want to add a comment to a question.\n",
    "- Use `@Sasha`, `@Simone`, `@Edoardo` if you want to mention the tutorial instructors directly.\n",
    "\n",
    "Although the chat will be distributed together with the recording, Slack is much better suited to hold continued Q&A and other discussions.\n",
    "Please, use it."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Binder only\n",
    "\n",
    "During the tutorial, we request participants to **exclusively** use [Binder](https://mybinder.org/).\n",
    "Everyone has their own combination of operating systems and software.\n",
    "Supporting all of them is a challenge, which also takes time away from the actual content of the tutorial.\n",
    "\n",
    "Binder 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 on the link in the `#announcements` channel on Slack.\n",
    "Also, you can find 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",
    "We will also share the link on Slack in `#announcements` channel and in Zoom's chat\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",
    "<b>Warning:</b> 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>\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",
    "Since Binder runs in the cloud, you cannot just press `Ctrl+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",
    "<b>Warning:</b> 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**. Look at the following image, an excerpt of the output above:\n",
    "\n",
    "![Error summary](images/error_test_info.png)\n",
    "\n",
    "For example, the first line `assert 4 == -2` means the test was expecting `4`, while your code returned `-2`. You need to revisit your code and try to understand what went wrong.\n",
    "\n",
    "<div class=\"alert alert-block alert-warning\">\n",
    "<b>Important:</b> 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, either on Zoom or Slack.\n",
    "These four 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.\n",
    "\n",
    "Here's how these time slots will be organized **on Zoom**:\n",
    "\n",
    "## Main room\n",
    "\n",
    "- Anyone who is not yet comfortable with Python.\n",
    "- Walkthrough of a few challenging exercises.\n",
    "- **Interactive**: you should participate with suggestions.\n",
    "\n",
    "\n",
    "## Break-out rooms\n",
    "\n",
    "- Anyone who wants to work on their own.\n",
    "- Discussion with someone who wants to share their code.\n",
    "- Specific Q&A."
   ]
  },
  {
   "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.11.3"
  },
  "vscode": {
   "interpreter": {
    "hash": "fb43f8d381edd655b57a3fa7f8143253a121a168968fa3987191db33f90c378d"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}