You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Aug 6, 2025. It is now read-only.
Copy file name to clipboardExpand all lines: README.md
+3-68Lines changed: 3 additions & 68 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -27,78 +27,13 @@ The course is organized as follows:
27
27
- Each chapter contains at least two parts: theory and exercises. For this edition on the chapter on `numpy` contains more than one Exercise section, but this may change in the future.
28
28
- The "In a Nutshell" chapters do not contain any interactive elements.
29
29
30
-
## Interactive Python Elements
31
-
32
-
As of Summer 2023, this course uses two methods for providing students the ability to run Python in their internet browser: an IPython console (JupyterLite and Pyodide) and a 3rd party cloud kernel to run a `*.ipynb` file (Binder and Colab). The IPython console is provided in the associated repositor `TUDelft-CITG/learn-python-calculator`. There is also a package that is loaded into the notebooks and IPython console to check student answers, which can be found in `TUDelft-CITG/learn-python-package`.
33
-
34
-
We decided that with the in-browser Python capabilities, there is no longer a requirement to provide separate notebooks for students to run locally (and consequently, no need to install any software!). However, since it is nice to be able to run the cells in the theory and exercise pages, links to open each page with a working Python kernel via Binder and Colab are included (the rocket icon {fa}`rocket` at the top right). Colab initializes much faster and more reliably, but due to GDPR concerns with Google products, Binder is offerred as an alternative. Neither platform will save modifications to the notebook, unless they are downloaded or imported individually.
35
-
36
-
An overview of the interactive elements by Chapter:
37
-
38
-
- Exercises in Chapters 1 and 2 are evaluated using JupyterQuiz only; no execution of Python code is required
39
-
- Exercises in Chapters 3, 4 and 6 use a JupyterLite REPL; the answer-checking package is used here
40
-
- Exercises in Chapter 5 use a mix of JupyterQuiz and a JupyterLite REPL; the answer-checking package is used here
41
-
- Exercises in Chapter 7 use a JupyterLite REPL (separate web page); the answer-checking package is *not* used here
42
-
43
-
### IPython Console
44
-
45
-
An HTML link is created and can be customized to initialize the console fora particular page.
46
-
47
-
To use the IPython console with a bit of front-end setup, use this [link](https://tudelft-citg.github.io/learn-python-calculator/repl/index.html?toolbar=1&kernel=python&code=print(%27You%20may%20begin!%27)), which adds the following to the URL: `?toolbar=1&kernel=python&code=print(%27You%20may%20begin!%27)`.
48
-
49
-
The example below chooses the kernel, imports pandas and the answer-checker and gives a message to begin.
50
-
51
-
````md
52
-
```{admonition} Open the Python Calculator for this page
53
-
:class: tip, dropdown
54
-
Click this <a href="https://tudelft-citg.github.io/learn-python-calculator/repl/index.html?toolbar=1&kernel=python&code=import pandas as pd; import data.check_answers as check; print('You may begin!')" target="_blank">link</a> and wait until the message "<tt>You may begin!</tt>" is printed to start evaluating code. More information about this tool can be found [here](calculator).
55
-
56
-
Remember that all pages in this course can also be opened as an interactive notebook via Binder or Colab using the {fa}rocket icon above (read more about it [here](nb-links)).
57
-
```
58
-
````
59
-
60
-
### Jupyter notebooks
61
-
62
-
Notebooks are set up using built-in features of Jupyter Book and links to Binder and Colab are provided. This automatically uses the notebook to generate the page, and the following cell needs to be added to the notebooks (remember to make it a hidden cell in the Jupyter Book so that it does not display on the website):
63
-
```
64
-
# ##-On Google colab uncomment and run the following code
65
-
# ## to install and import the function that will be used to check your answers.
66
-
# !pip install learn-python-ceg-test
67
-
68
-
# ##-On Binder just uncomment and run the following line
69
-
# import learn_python_ceg_test.check_answers as check
70
-
```
71
-
72
-
### Decision-making notes
73
-
74
-
This section summarizes some key information that led up to the final decision of whether (and how) to include a Python kernel directly in the Jupyter Book (i.e., an interactive page directly in the book) for the Summer 2023 version, which was not trivial. These tools change quickly, so the information may already be out of date or irrelevant.
75
-
76
-
Remember that JupyterLite provides a Jupyter-like interface (Lab, classic notebook, REPL/console) and can be used with one of two kernels: Xeus or Pyodide. The biggest implication for us seems to be that Xeus does not allow dynamic import of packages at runtime (conda-forge only), whereas Pyodide does (via pip). On the other hand, Xeus allows pre-loading packages, whereas Pyodide does not. Future development may combine these two kernels, so it is only a matter of time until something breaks. Stay tuned...
77
-
78
-
Option 1:
79
-
- JupyterLite REPL to create iPython console in a frame on the page, supported by a Xeus kernel
80
-
- Allows conda forge packages (no pip) installed during the build process (not dynamically installed via frontend)
81
-
- Can specify code to run on init but it is visible as the first cell command (no hiding of code)
82
-
- conda forge package only visible in error traceback (important for answer-checking)
83
-
84
-
Option 1.5: same as Option 1 with a notebook, but must include the nb as a separate file in the book repo
85
-
86
-
Option 2:
87
-
- Binder (creates an image) and Colab creates a nb interface on google server (not same container as binder)
88
-
- displays page as nb with live kernel
89
-
- can use pip (conda-forge not sure)
90
-
- cannot hide cells (this is JB only, and all cells need to run and be not hidden)
91
-
- all cells are active
92
-
- need to hide cell in JB for colab pip install (not remove) and run this cell when using nb in colab
93
-
94
-
Option 3: JupyterLite kernel with Thebe to support an interactive Jupyter notebook page. We did not pursue this because it's not fully implemented yet via Jupyter Book (javascript stuff). Although Thebe is functional with a Binder kernel, in our opinion this is too slow and unreliable.
95
-
96
-
In the end, there was a problem with getting `matplotlib` to import when JupyterLite was included in the book build (see [Issue #35](https://github.com/TUDelft-CITG/learn-python/issues/35)). We also realized that it is possible (and much easier!) to create a separate JupyterLite website that uses Lab, classic nb or REPL via GitHub pages (see the [JupyterLite](https://jupyterlite.readthedocs.io/en/latest/) demos), which was a good alternative to complicated workflows and buggy kernel installations required for building the kernel directly into the book.
30
+
This book is
97
31
98
32
## Acknowledgments
99
33
100
-
Financial support for this project was provided through an open education grant from the Educational Management Team for the Civil Engineering and Geosciences Faculty at Delft. The content was first developed for Summer 2022 by Sandra Verhagen and a team of TA's in Jupyter notebooks that were auto-graded in Vocareum. For Summer 2023 a second round of funding was optained to update the content and adapt it to an entirely open and self-paced course without enrollement via a Jupyter Book, led by Robert Lanzafame. Special thanks goes to Miguel Mendoza Lugo who adapted the notebooks into the Jupyter Book format and implemented the interactive features, as well as Ahmed Farahat, who helped create the fun new visual features that make understanding the material easier in the Jupyter Book platform, as well as the In a Nutshell summaries.
34
+
Financial support for this project was provided through an open education grant from the Educational Management Team for the Civil Engineering and Geosciences Faculty at Delft. The content was first developed for Summer 2022 by Sandra Verhagen and a team of TA's in Jupyter notebooks that were auto-graded in Vocareum. For Summer 2023 a second round of funding was optained to update the content and adapt it to an entirely open and self-paced course without enrollement via a Jupyter Book, led by Robert Lanzafame. Special thanks goes to Miguel Mendoza Lugo who adapted the notebooks into the Jupyter Book format and implemented the interactive features, as well as Ahmed Farahat, who helped create the fun new visual features that make understanding the material easier in the Jupyter Book platform, as well as the In a Nutshell summaries. Guilherme Ferreira Sêco de Alvarenga made improvements to the content and set up the interactive Python feature via [TeachBooks](teachbooks.io) tools. Shiya Tang improved the contents and converted exercises from JupyterQuiz to H5p.
101
35
102
36
This Book is maintained and developed by staff of the Faculty of Civil Engineering and Geosciences of TU Delft, the Netherlands.
This book was developed over several years with a number of people.
4
+
5
+
In 2024 the book was upgraded to include Python interactivity via Sphinx-Thebe.
6
+
7
+
8
+
## Pre-2024 README
9
+
10
+
_The contents below are from the README prior to the 2024 upgrade._
11
+
12
+
### Interactive Python Elements
13
+
14
+
As of Summer 2023, this course uses two methods for providing students the ability to run Python in their internet browser: an IPython console (JupyterLite and Pyodide) and a 3rd party cloud kernel to run a `*.ipynb` file (Binder and Colab). The IPython console is provided in the associated repositor `TUDelft-CITG/learn-python-calculator`. There is also a package that is loaded into the notebooks and IPython console to check student answers, which can be found in `TUDelft-CITG/learn-python-package`.
15
+
16
+
We decided that with the in-browser Python capabilities, there is no longer a requirement to provide separate notebooks for students to run locally (and consequently, no need to install any software!). However, since it is nice to be able to run the cells in the theory and exercise pages, links to open each page with a working Python kernel via Binder and Colab are included (the rocket icon {fa}`rocket` at the top right). Colab initializes much faster and more reliably, but due to GDPR concerns with Google products, Binder is offerred as an alternative. Neither platform will save modifications to the notebook, unless they are downloaded or imported individually.
17
+
18
+
An overview of the interactive elements by Chapter:
19
+
20
+
- Exercises in Chapters 1 and 2 are evaluated using JupyterQuiz only; no execution of Python code is required
21
+
- Exercises in Chapters 3, 4 and 6 use a JupyterLite REPL; the answer-checking package is used here
22
+
- Exercises in Chapter 5 use a mix of JupyterQuiz and a JupyterLite REPL; the answer-checking package is used here
23
+
- Exercises in Chapter 7 use a JupyterLite REPL (separate web page); the answer-checking package is *not* used here
24
+
25
+
#### IPython Console
26
+
27
+
An HTML link is created and can be customized to initialize the console fora particular page.
28
+
29
+
To use the IPython console with a bit of front-end setup, use this [link](https://tudelft-citg.github.io/learn-python-calculator/repl/index.html?toolbar=1&kernel=python&code=print(%27You%20may%20begin!%27)), which adds the following to the URL: `?toolbar=1&kernel=python&code=print(%27You%20may%20begin!%27)`.
30
+
31
+
The example below chooses the kernel, imports pandas and the answer-checker and gives a message to begin.
32
+
33
+
````md
34
+
```{admonition} Open the Python Calculator for this page
35
+
:class: tip, dropdown
36
+
Click this <a href="https://tudelft-citg.github.io/learn-python-calculator/repl/index.html?toolbar=1&kernel=python&code=import pandas as pd; import data.check_answers as check; print('You may begin!')" target="_blank">link</a> and wait until the message "<tt>You may begin!</tt>" is printed to start evaluating code. More information about this tool can be found [here](calculator).
37
+
38
+
Remember that all pages in this course can also be opened as an interactive notebook via Binder or Colab using the {fa}rocket icon above (read more about it [here](nb-links)).
39
+
```
40
+
````
41
+
42
+
#### Jupyter notebooks
43
+
44
+
Notebooks are set up using built-in features of Jupyter Book and links to Binder and Colab are provided. This automatically uses the notebook to generate the page, and the following cell needs to be added to the notebooks (remember to make it a hidden cell in the Jupyter Book so that it does not display on the website):
45
+
```
46
+
# ##-On Google colab uncomment and run the following code
47
+
# ## to install and import the function that will be used to check your answers.
48
+
# !pip install learn-python-ceg-test
49
+
50
+
# ##-On Binder just uncomment and run the following line
51
+
# import learn_python_ceg_test.check_answers as check
52
+
```
53
+
54
+
#### Decision-making notes
55
+
56
+
This section summarizes some key information that led up to the final decision of whether (and how) to include a Python kernel directly in the Jupyter Book (i.e., an interactive page directly in the book) for the Summer 2023 version, which was not trivial. These tools change quickly, so the information may already be out of date or irrelevant.
57
+
58
+
Remember that JupyterLite provides a Jupyter-like interface (Lab, classic notebook, REPL/console) and can be used with one of two kernels: Xeus or Pyodide. The biggest implication for us seems to be that Xeus does not allow dynamic import of packages at runtime (conda-forge only), whereas Pyodide does (via pip). On the other hand, Xeus allows pre-loading packages, whereas Pyodide does not. Future development may combine these two kernels, so it is only a matter of time until something breaks. Stay tuned...
59
+
60
+
Option 1:
61
+
- JupyterLite REPL to create iPython console in a frame on the page, supported by a Xeus kernel
62
+
- Allows conda forge packages (no pip) installed during the build process (not dynamically installed via frontend)
63
+
- Can specify code to run on init but it is visible as the first cell command (no hiding of code)
64
+
- conda forge package only visible in error traceback (important for answer-checking)
65
+
66
+
Option 1.5: same as Option 1 with a notebook, but must include the nb as a separate file in the book repo
67
+
68
+
Option 2:
69
+
- Binder (creates an image) and Colab creates a nb interface on google server (not same container as binder)
70
+
- displays page as nb with live kernel
71
+
- can use pip (conda-forge not sure)
72
+
- cannot hide cells (this is JB only, and all cells need to run and be not hidden)
73
+
- all cells are active
74
+
- need to hide cell in JB for colab pip install (not remove) and run this cell when using nb in colab
75
+
76
+
Option 3: JupyterLite kernel with Thebe to support an interactive Jupyter notebook page. We did not pursue this because it's not fully implemented yet via Jupyter Book (javascript stuff). Although Thebe is functional with a Binder kernel, in our opinion this is too slow and unreliable.
77
+
78
+
In the end, there was a problem with getting `matplotlib` to import when JupyterLite was included in the book build (see [Issue #35](https://github.com/TUDelft-CITG/learn-python/issues/35)). We also realized that it is possible (and much easier!) to create a separate JupyterLite website that uses Lab, classic nb or REPL via GitHub pages (see the [JupyterLite](https://jupyterlite.readthedocs.io/en/latest/) demos), which was a good alternative to complicated workflows and buggy kernel installations required for building the kernel directly into the book.
Prior to 2024 the book used Jupyter Quiz, which is based on JSON files. These are easy to set up and use, but don't work properly when a book page uses the interactive mode of Sphinx-Thebe. Therefore, the quiz questions were converted to H5p.
4
+
5
+
To make the change transparent, and possible support future conversion in case H5p is no longer supported, the following actions were taken:
6
+
1. A tag was added to the import statement in the Python cell, `# jupyterquiz-import`. If all exercises in a page are converted, the entire cell can be commented out (but should remain in the notebook with cell tag `remove-input`)
7
+
2. A cell containing a Jupyter Quiz exercises should have a tag of the form: `# jupyterquiz-exercise-x-y-z` where `x`, `y`, and `z` are the chapter, section, and exercise numbers (as they appeared in the original book and Jupyter Quiz question number), respectively. This tag should be added to the cell containing the exercise prompt, and the cell tag `remove-input` should remain in place.
8
+
3. H5p exercises are created and stored on the TU Delft H5P platform, accessible at https://tudelft.h5p.com/content. Each exercise is assigned a unique identifier on this platform, which is correlated with the original Jupyter Quiz exercise tags.
0 commit comments