add built-in labs; review funcs

Author: fabridamicelli

book/02_types_data_structures.ipynb

@@ -2031,6 +2031,20 @@
     "d[1,2,3]  # optionally without parenthesis"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "122a32d9-0707-4f3f-a71c-47ba7d30f5d5",
+   "metadata": {},
+   "source": [
+    "All these built-in types that we've seen so far can take you already pretty far in manipulating data, both for quick exploration and for more detailed analysis.\n",
+    "So it will really pay off to have a good grasp on them, take your time to learn them!\n",
+    "\n",
+    "Here's a talk for you to watch later that hammers home this point with great mastery:\n",
+    "\n",
+    "\n",
+    "{{< video https://www.youtube.com/watch?v=lyDLAutA88s&t=1850s >}}"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "c1d38ca9-5a02-4b4a-b793-82da9aa3ed29",

book/03_flow_control.ipynb book/03_1_flow_control.ipynbbook/03_flow_control.ipynb renamed to book/03_1_flow_control.ipynb

@@ -17,9 +17,7 @@
    "id": "493c0563-f1b4-4438-af55-0915a3c6a48d",
    "metadata": {},
    "source": [
-    "Let's take a look at a few syntax aspects that allow us to control how our program flows.\n",
-    "\n",
-    "We can loop over *things* (we'll get back to this later):"
+    "Let's take a look at a few syntax aspects that allow us to control how our program flows."
    ]
   },
   {
@@ -132,7 +130,7 @@
    "id": "bc862721-3251-44c2-87b9-79fb6d4b4770",
    "metadata": {},
    "source": [
-    "If you really need the indices to carry some other operation, you can get them as you go with `enumerate`, which returns a tuple:"
+    "If you really need the indices to carry out some other operation, you can get them as you go with `enumerate`, which returns a tuple:"
    ]
   },
   {
@@ -190,7 +188,7 @@
    "id": "9dd95ac6-450a-4eb5-b6a1-b68ef8150691",
    "metadata": {},
    "source": [
-    "Importantly, Python doesn't care about `what` data type we are looping over – all that matters is the data \"knows\" how to be looped over:"
+    "Importantly, Python doesn't care about _what_ data type we are looping over – all that matters is the data \"knows\" how to be looped over:"
    ]
   },
   {
@@ -291,9 +289,9 @@
    "id": "0a4ee03e-973a-42c9-a22d-515ba2f1dca2",
    "metadata": {},
    "source": [
-    "We say something is \"falsy\" when it evaluates to `False`, despite it not being the boolen value `False`.\n",
+    "We say something is \"falsy\" when it evaluates to `False`, despite it not being the literal boolean value `False`.\n",
     "\n",
-    "Empty containers (lists, tuples, dicts, sets) are \"falsy\", which can be handy:"
+    "For example, the number 0, empty strings, empty collections (lists, tuples, dicts, sets) are \"falsy\", which can be handy:"
    ]
   },
   {
@@ -436,7 +434,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.13"
+   "version": "3.13.3"
   }
  },
  "nbformat": 4,

book/031_error_handling.ipynb book/03_2_error_handling.ipynbbook/031_error_handling.ipynb renamed to book/03_2_error_handling.ipynb

@@ -17,9 +17,10 @@
    "metadata": {},
    "source": [
     "## Exceptions\n",
-    "When our program runs into an error, Python throws an Exception.\n",
+    "When our program runs into an error, the execution stops and Python throws a so-called _Exception_.  \n",
     "There several different types of exceptions and they work as a way to communicate what went wrong.\n",
-    "Sometimes we simply want to let the program crash because the problem is completely unexpected or because we do not have a good solution to deal with it at run time.\n",
+    "Sometimes we simply want to let the program crash because the problem is completely unexpected or because we do not have a good solution to deal with it, for example we divide by 0.  \n",
+    "But some other times we want to handle it differently, for example if we are getting data from a website that is transiently unavailable we might want to retry after a few seconds.\n",
     "\n",
     "One of the language constructs to deal with errors in Python is `try-except`, which has this structure:\n",
     "```python\n",
@@ -274,7 +275,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.13"
+   "version": "3.13.3"
   }
  },
  "nbformat": 4,

book/04_functions.ipynb

@@ -37,7 +37,7 @@
    "outputs": [],
    "source": [
     "def identity(a, b):  # only positional arguments\n",
-    "    return a, b"
+    "    return a, b      # we can return more than one thing"
    ]
   },
   {
@@ -99,7 +99,7 @@
    "metadata": {},
    "source": [
     "::: {.callout-important }\n",
-    "Python functions **always** return a value, even without a `return` statement, in which case the return value will be `None`.\n",
+    "Python functions **always** return a value, **even without** a `return` statement, in which case the return value will be `None`.\n",
     ":::"
    ]
   },
@@ -150,7 +150,7 @@
    "id": "10383a76-442f-4ece-9a44-cbfcae681403",
    "metadata": {},
    "source": [
-    "This three definitions are equivalent:"
+    "These three definitions are equivalent:"
    ]
   },
   {
@@ -169,8 +169,7 @@
     "    return\n",
     "    \n",
     "def f():\n",
-    "    print(\"hello\")\n",
-    "    # The return statement is implicitly here    "
+    "    print(\"hello\")"
    ]
   },
   {
@@ -186,7 +185,7 @@
    "id": "cd15c9c6-2067-48ca-b35b-a715d2a762ad",
    "metadata": {},
    "source": [
-    "We can write a function with arbitrary arguments.\n",
+    "We can write a function with an arbitrary (undefined) number of arguments.\n",
     "For that, we use the syntax `*args`.\n",
     "The `args` will be put into a tuple:"
    ]
@@ -347,14 +346,24 @@
     "general(1, 2, first=\"hello\", second=\"world\")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "4f6cdcf8-c9f6-46e7-9cba-cfa35e2a67a9",
+   "metadata": {},
+   "source": [
+    "::: {.callout-tip}\n",
+    "Use key-word (named) arguments by default, it will make your code much more readable, maintainable and easier to debug.\n",
+    ":::"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "38e5d4a8-0df5-4c34-9dab-67f93dab46af",
    "metadata": {},
    "source": [
     "## Functions are values\n",
     "\n",
-    "We can assign functions to variables and pass them around, like any other object (people call this to have \"functions as first-class citizen\")."
+    "We can assign functions to variables and pass them around, like any other object (people call this to have \"_functions as first-class citizen_\" in the language)."
    ]
   },
   {
@@ -647,7 +656,7 @@
     "def early():\n",
     "    if 1 > 0:\n",
     "        return \"first condition\"\n",
-    "    if 2 > 0:  # This code will never be evaluated\n",
+    "    if 2 > 0:  # This code will never be reached \n",
     "        return \"second condition\""
    ]
   },
@@ -887,7 +896,7 @@
    "source": [
     "## Exercises\n",
     "1) Write a function called `intro` that takes two positional arguments, name and age, and prints a sentence introducing a person. The function should return nothing.\n",
-    "2) Repeat it, but adding an optional argument, city. The function should now return the introducing string (consider handling the city)\n",
+    "2) Repeat it, but adding an optional argument, city. The function should now return the introducing string and handle the city input too.\n",
     "3) Write a function called `sort_dict_by_value` that takes a dictionary and returns a dictionary sorted by value.\n",
     "4) Write a function that takes an arbitrary number of key-word __only__ arguments representing pairs (name, age) and returns a list of tuples sorted by age.\n",
     "For example:\n",
@@ -937,7 +946,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.13"
+   "version": "3.13.3"
   }
  },
  "nbformat": 4,

book/05_comprehensions.ipynb

@@ -17,8 +17,8 @@
    "id": "493c0563-f1b4-4438-af55-0915a3c6a48d",
    "metadata": {},
    "source": [
-    "A commonly used language construct are comprehensions.\n",
-    "They can have performance advantages and can improve readability if properly used."
+    "A commonly used language construct are comprehensions.  \n",
+    "They can have performance advantages and improve readability if properly used."
    ]
   },
   {

book/081_pandas.ipynb

@@ -87,7 +87,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.13"
+   "version": "3.13.3"
   }
  },
  "nbformat": 4,

book/_quarto.yml

@@ -1,6 +1,5 @@
 project:
   type: book
-  # output-dir: ../docs
 
 book:
   title: "Python Course"
@@ -36,16 +35,17 @@ book:
     - 01_1_getting_started.ipynb
     - 01_2_executing_code.ipynb
     - 02_types_data_structures.ipynb
-    - 03_flow_control.ipynb
-    - 031_error_handling.ipynb
+    - 03_1_flow_control.ipynb
+    - 03_2_error_handling.ipynb
     - 04_functions.ipynb
     - 041_scope.ipynb
     - 05_comprehensions.ipynb
-    - 051_oop.ipynb
+    - lab_syntax.ipynb
     - 06_imports.ipynb
     - 061_dependencies.ipynb
     - 062_read_and_write.ipynb
     - 063_common_data_formats.ipynb
+    - 051_oop.ipynb
     - 08_numpy.ipynb
     - 081_pandas.ipynb
     - 09_plotting.ipynb
@@ -58,7 +58,7 @@ book:
     - 999_glossary.ipynb
     - references.qmd
 
-bibliography: references.bib
+# bibliography: references.bib
 
 format:
   html:

book/lab_explore_data_solutions.ipynb

@@ -1690,7 +1690,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.13"
+   "version": "3.13.3"
   }
  },
  "nbformat": 4,