start refining debugging

Author: fabridamicelli

book/061_dependencies.ipynb

@@ -16,14 +16,14 @@
    "id": "c79acc5e-0543-4994-b09a-1af21a509cd2",
    "metadata": {},
    "source": [
-    "In contrast to the code that we ourselves write and can import or to some built-in modules such as `pathlib` and `json` that we can import directly after installing python, there are third-party libraries that we want to use but need to be first installed, such as `numpy` and `pandas`.  \n",
+    "In contrast to our own code that we can import or to some built-in modules such as `pathlib` that we can import directly after installing python, there are third-party libraries that we want to use but need to be first installed, such as `numpy` and `pandas`.\n",
     "This libraries are also called \"packages\".\n",
-    "There are several repositories where people publish python packages and from which we can download them, but the official one is [PyPI](https://pypi.org) (Python Package Index).\n",
     "\n",
+    "There are several repositories (also called \"indexes\") where people publish python packages and from which we can download them. The official one is [PyPI](https://pypi.org) (Python Package Index).\n",
     "\n",
     "These are open-source libraries maintained mostly by voluntary contributions of people of the community – and you can also contribute to them!\n",
     "\n",
-    "They are being actively developed and thus in permanent evolution.\n",
+    "These packages are being actively developed and thus in permanent evolution.\n",
     "In order to avoid compatibility problems and to ensure reproducibility, we might want to specify the exact versions of the packages we use.\n",
     "It turns out that is not an easy problem and the reason why need a **package manager**.\n",
     "\n",
@@ -110,6 +110,8 @@
     "That will add the dependency to our list as well as updating the \"lock\" file.\n",
     "Read more about this workflow and managing dependencies [here](https://docs.astral.sh/uv/guides/projects/#working-on-projects).\n",
     "\n",
+    "The point is that after installing the dependency we can just import it like any other module.\n",
+    "\n",
     "To remove a package from the dependencies of our project we do:\n",
     "```bash\n",
     "uv remove PACKAGE-NAME\n",
@@ -121,11 +123,9 @@
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "c32b1f81-3a46-460c-b537-4cd56b1e49b0",
+   "cell_type": "markdown",
+   "id": "64fc1a40-04fe-40da-8875-04e4aa5d4d46",
    "metadata": {},
-   "outputs": [],
    "source": []
   }
  ],

book/06_imports.ipynb

@@ -156,17 +156,19 @@
    "id": "3b452c0b-682f-4868-9fd6-4dc6f7a5ff69",
    "metadata": {},
    "source": [
-    "## Script vs. Importable Code\n",
-    "We can also import code that we wrote ourselves with the same syntax.\n",
-    "For example, if we have a python file called `mymodule.py` we can import it from another file with:\n",
+    "## Importable Code vs. Scripting\n",
+    "We can also import our own code.\n",
+    "For example, if we have a python file called `mymodule.py` we can use it in another file:\n",
     "\n",
     "```python\n",
+    "# anotherfile.py\n",
+    "\n",
     "import mymodule\n",
     "```\n",
     "\n",
-    "A Python module (any `.py` file) might contain code that we want to run as a script alongside code that we only want to use somewhere else (importing parts of it).\n",
+    "Sometimes we have a Python module (any `.py` file) that contain code that we only want to run as a script alongside code that we only want to use somewhere else (importing parts of it).\n",
     "\n",
-    "We can isolate part of the code that we want to run as a script with a trick that's easier to show than to explain, so let's do some exercises."
+    "We can isolate part of the code that we want to run as a script with a special syntax, let's do some exercises to show it."
    ]
   },
   {
@@ -181,11 +183,13 @@
     "\n",
     "```python\n",
     "# data.py\n",
+    "\n",
     "RAWDATA = ...  # 3 dots are called \"Ellipsis\" and act as placeholder\n",
     "\n",
     "def fetch_data(raw_data):\n",
     "    ... \n",
     "\n",
+    "# This block will only run when calling `python data.py`\n",
     "if __name__ == \"__main__\":\n",
     "    print(\"Fetching data\")    \n",
     "    data = fetch_data(RAWDATA)\n",

book/111_debugging.ipynb

@@ -12,35 +12,50 @@
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "3d0080c9-01ad-4120-ad3d-37700cdf2a6f",
+   "cell_type": "markdown",
+   "id": "bd498d45-9d1e-4860-854b-a94993ffa77b",
    "metadata": {},
-   "outputs": [],
    "source": [
-    "🚧\n",
-    "Material under construction\n",
-    "🚧"
+    "We are humans, we make mistakes – that's very much true for coding.\n",
+    "Finding errors in our code is fundamental skill to train.\n",
+    "\n",
+    "We will cover here a few tools that help us find and fix errors more quickly."
    ]
   },
   {
    "cell_type": "markdown",
-   "id": "bd498d45-9d1e-4860-854b-a94993ffa77b",
+   "id": "3789894a-e176-4cc5-872a-c328b66b1359",
    "metadata": {},
    "source": [
-    "We are humans, we make mistakes and that's very much true for coding.\n",
-    "Finding errors in our code is fundamental skill to train since we cannot avoid making mistakes.\n",
-    "The goal is to get better at finding and fixing them quickly."
+    "## What is a debugger?\n",
+    "\n",
+    "A debugger is a device that allows us to interrupt code execution and jump into the execution context in a interactive mode, so that we can inspect and run code to find out what's going on.  \n",
+    "We called that to \"set a breakpoint\" or \"set a trace\".\n",
+    "\n",
+    "There are a few options to do that natively in python."
    ]
   },
   {
    "cell_type": "markdown",
    "id": "55a9413f-5a5a-40c1-a2b7-b642f0a54aec",
    "metadata": {},
    "source": [
-    "## Python debugger, breakpoints"
+    "## Python debugger, breakpoints\n",
+    "The python standard library includes `pdb` module.\n",
+    "\n",
+    "```python\n",
+    "import pdb; pdb.set_trace()\n",
+    "```"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b40ea608-89a9-4cbd-b07f-4f9a33699d89",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  },
   {
    "cell_type": "markdown",
    "id": "4ae14f36-84e6-4def-9240-7a423c587e9c",
@@ -74,7 +89,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.13"
+   "version": "3.13.3"
   }
  },
  "nbformat": 4,

book/_quarto.yml

@@ -45,14 +45,14 @@ book:
     - 062_read_and_write.ipynb
     - 061_dependencies.ipynb
     - 063_common_data_formats.ipynb
-    - 051_oop.ipynb
+    - 111_debugging.ipynb
     - 08_numpy.ipynb
     - 081_pandas.ipynb
     - 09_plotting.ipynb
     - 10_tests.ipynb
     - 11_cli.ipynb
-    - 111_debugging.ipynb
     - 13_tools.ipynb
+    - 051_oop.ipynb
     - lab_explore_data_exercises.ipynb
     - notebook_workflow.ipynb
     - 999_glossary.ipynb

book/index.qmd

@@ -3,13 +3,11 @@ This is a free, **short introduction** to the Python programming language, empha
 The goal is to get you just enough tools under your belt for you to pursue your own learning path according to your interests. 
 What's in for you:
 
-
 ✅ Core concepts of the language explained in _simple words_  
-✅ Focus on "data-stack" ([numpy](https://numpy.org), [pandas](https://pandas.pydata.org/), [matplotlib](https://matplotlib.org/), etc.)  
 ✅ Software engineering best-practices (project/dependency management, [`uv`](https://docs.astral.sh/uv/), testing with [pytest](https://docs.pytest.org/en/stable/), error handling, etc.)  
-✅ Exercises on each chapter to get comfortable with the new concepts   
-✅ Integrative "Labs" with real-world datasets to put all concepts together  
 ✅ Useful references to deepen your knowledge (talks, books, cheatsheets, etc.)  
+✅ Exercises for each chapter to ramp up your skills with deliberate practice   
+✅ Integrative "Labs" with real-world datasets  
 
 Code notebooks and report any problems on [this GitHub repository](https://www.github.com/fabridamicelli/python-course).
 
@@ -18,6 +16,6 @@ Off we go! 🚀
 
 # About the Author
 Fabrizio Damicelli (PhD, Computational Neuroscience) is a self-taught coder who prefers solid intuitions to unnecessary sophistication and fancy jargon.  
-Open source advocate, creator and maintainer of a few of Python packages.  
+Open source advocate, creator and maintainer of a few of Python packages and Open Source projects.  
 Learn more about him [here](https://fabridamicelli.github.io).