Python packaging revision

_data/data.json

@@ -40,6 +40,14 @@
         "location": "WE5/01.003",
         "details_url": "docs/week_3_python.html"
       },
+      {
+        "week": 4,
+        "title": "Introduction to Python (III)",
+        "date": "2025-11-04",
+        "date_formatted": "November 4, 08.00–12.00",
+        "location": "WE5/01.003",
+        "details_url": "docs/week_3_python.html"
+      },
       {
         "week": 5,
         "title": "Best practices",

docs/syllabus.md

@@ -189,6 +189,7 @@ possibly a “how to succeed” section
   - [Git]({{ site.baseurl }}/output/02-git.html)
   - [Python 1]({{ site.baseurl }}/output/03-python_1.html)
   - [Python 2]({{ site.baseurl }}/output/04-python_2.html)
+  - [Python 3]({{ site.baseurl }}/output/04-python_3.html)
   - [Best Practices]({{ site.baseurl }}/output/05-best_practice.html)
   - [Code Review]({{ site.baseurl }}/output/06-code_review.html)
 
@@ -200,6 +201,7 @@ possibly a “how to succeed” section
   - [Git Merge Conflicts]({{ site.baseurl }}/docs/week_2_git_notebook_merge_conflict.html)
   - [Python 1]({{ site.baseurl }}/docs/week_3_python_notebook_1.html)
   - [Python 2]({{ site.baseurl }}/docs/week_3_python_notebook_2.html)
+  - [Python 3]({{ site.baseurl }}/docs/week_3_python_notebook_3.html)
 
 - Another important resource is the [documentation of CoLRev](https://colrev-environment.github.io/colrev/){: target="_blank"}, in particular the [environment setup](https://colrev-environment.github.io/colrev/dev_docs/setup.html){: target="_blank"} and the [package development](https://colrev-environment.github.io/colrev/dev_docs/packages.html){: target="_blank"} pages.
 

docs/week_3_python.md

@@ -31,6 +31,12 @@ If you have any questions during or after the sessions, we're here to assist. We
 > - Understand how to use other Python modules and libraries
 > - Prepare for extending the functionality of the CoLRev package
 
+> [!NOTE]  
+> Plans for the revision:
+> This page will be based on the [colrev-python-tutorial](https://github.com/CoLRev-Environment/colrev-python-tutorial) repository.
+> Students will run the code outside of a Python package, using `python script.py` (instead of colrev run).
+> For simplicity, data and source code will be in the same directory.
+
 ## Session 1
 
 <br>
@@ -77,5 +83,30 @@ To do this, we recommend starting a Codespace from the fork of your group.
 You will also need to create a separate project directory in the Codespace (as explained in the notebooks).
 Try to run the operations presented in the [asciinema recording](https://colrev-environment.github.io/colrev/){: target="_blank"} in the CoLRev documentation and analyze how the data in the project (Git) repository changes.
 
+---
+
+## Session 3
+
+> [!NOTE]  
+> Plans for the revision:
+> Session 3 will be dedicated to Python packaging. Students will work in the [colrev-python-package-tutorial](https://github.com/CoLRev-Environment/colrev-python-package-tutorial) and create a colrev package "from scratch". Here, we should introduce the distinction between data and src directories (by running pip install ..., the package can be called without specifying a path).
+> TODO: Convert the Python packaging page to a presentation and create a corresponding practice notebook.
+
+<br>
+
+<iframe src="../output/04-python_3.html" 
+        style="width: 100%; aspect-ratio: 16 / 9; border: 1px solid #ccc; border-radius: 5px;" 
+        allowfullscreen>
+</iframe>
+
+<br>
+
+| **Materials**       | **Link**                                                                                                  |
+|----------------------|---------------------------------------------------------------------------------------------------------|
+| Python session 3     | [![View Slides Part 3](https://img.shields.io/badge/View-Slides-orange?logo=html5)](../output/04-python_3.html){: target="_blank"} [![View PDF Slides](https://img.shields.io/badge/Download-PDF-orange?logo=adobe)](../output/04-python_3.pdf){: target="_blank"} |
+| Notebook session 3   | [![Open Notebook](https://img.shields.io/badge/Notebook-blue?logo=github)](week_3_python_notebook_3.html) |
+
+---
+
 {: .deliverable }
 ![tasks logo](../assets/iconmonstr-clipboard-5.svg)Contribute code to a fork, create branches and merge code ([deadline](../index.html#deliverables)).

docs/week_3_python_notebook_1.md

@@ -34,9 +34,7 @@ With this notebook, you can familiarize yourself with Python syntax, create and
 
 **"How do I write and use Python code?"**
 
-### Switch branch
-
-Navigate to the [CoLRev repository](https://github.com/CoLRev-Environment/colrev){: target="_blank"}, select the `tutorial_python` branch and start Codespaces.
+Start a Codespace in the [colrev-python-tutorial](https://github.com/CoLRev-Environment/colrev-python-tutorial) repository.
 
 As a first step, we install the package dependency manager **uv**, which will be used in [part 3](#libraries):
 
@@ -47,28 +45,25 @@ pip install uv
 Next, we reset the state of the repository to the beginning of the tutorial:
 
 ```python
-git reset --hard 8fa941d167503d20659ea87ec6169affbf6574c3
+git reset --hard f0a13be2494181d56eb71a2f1aee8b4511f65919
 ```
 
 - As the session progresses, you can checkout the current commits
 - Whenever you see a `git reset --hard ...` command on the following slides, you can use it to set your repository to the required state (commit).
 
-### Setting up entrypoints
+### Setting up a Python script
 
-We implement a simple version of CoLRev that should be available through a separate command:
+We implement a simple Pyhton script, `run.py`, which should be available through the following command:
 
-```python
-colrev run
+```
+python run.py
 ```
 
-{: .info }
-> The previous command will initially create a `ModuleNotFoundError`. We will create this module in the next step.
-
-**Tasks:**
+**Task**: Create the script, have it print "Hello World" and test the `python run.py` call.
 
-- Check the last commit and the changes that were introduced. Which function does our new `run` command call?
--  Create the `run.py` module (module: file containing Python code) and the function that should be called. The function should print `Start simple colrev run`. Note that calling `colrev.ops.run.main()` means that colrev will try to import and run the `main()` function in the `/workspaces/colrev/colrev/ops/run.py` module.
-- Check the other functions in the module `/workspaces/colrev/colrev/ui_cli/cli.py`, and other modules in the `/workspaces/colrev/colrev` directory if necessary.
+```python
+git reset --hard 1778473e75718277ad2a1b623cde99c4fff674c0
+```
 
 ## Part II: Data items <a id="data"></a>
 
@@ -87,7 +82,7 @@ In this part, we focus on the data structure of dictionaries, which are often us
 }
 ```
 
-**Task**: Create a dictionary containing these data fields and print it when `colrev run` is called.
+**Task**: Create a dictionary containing these data fields and print it when `python run.py` is called.
 
 You can find the syntax for Python dictionaries (and many other data types) in the [W3School](https://www.w3schools.com/python/python_dictionaries.asp){: target="_blank"}.
 
@@ -108,7 +103,7 @@ Start simple colrev run
 To checkout the **solution**, run:
 
 ```python
-git reset --hard dbd583c499da9fe0945ce75f98c32c7babaddd4d
+git reset --hard 728a2dbe5a3c0f15e989eac4faab7b877b2f3a0c
 ```
 
 ## Part III: External libraries <a id="libraries"></a>
@@ -125,43 +120,21 @@ We decide to use the [BibtexParser](https://github.com/sciunto-org/python-bibtex
 pip install bibtexparser
 ```
 
-To add it as a dependency of CoLRev and make it available for users of the CoLRev package, we run
-
-
-```python
-uv add bibtexparser
-```
-
-<b>Task</b>: Check the changes and create a commit.
-
-To checkout the **solution**, run:
-
-
-```python
-git reset --hard c9d89be988d9ec8ab18b2841af74996bf2ad5b43
-cd /workspaces/colrev
-pip install -e .[dev]
-```
-
 ### Using external libraries
 
-Go to the [bibtexparser tutorial](https://bibtexparser.readthedocs.io/){: target="_blank"} and figure out how to load a BibTeX file. An example `records.bib` file is available [here](../assets/records.bib). To use the file in your codespace, it needs to be uploaded. You can simply drag and drop the `records.bib` into `/workspaces/colrev`.
+Go to the [bibtexparser tutorial](https://bibtexparser.readthedocs.io/){: target="_blank"} and figure out how to load a BibTeX file. An example `records.bib` file is available [here](../assets/records.bib). To use the file in your codespace, it needs to be uploaded. You can simply drag and drop the `records.bib` into `/workspaces/colrev-python-tutorial`.
 
 {: .info }
 > Bibtexparser has a pre-release (version 2), but for this session, we use version 1 of bibtexparser.
 
-Instead of defining the dictionary in the `run.py`, use the bibtexparser to load the `records.bib` file. Remember to store the `records.bib` in the **project directory**.
+Instead of defining the dictionary in the `run.py`, use the bibtexparser to load the `records.bib` file.
 
 Afterward, loop over the records (`for ...`) and print the title of each record.
 
-### Code quality
-
-Create a commit, and observe how the code quality checks are triggered ([pre-commit hooks](https://pre-commit.com/){: target="_blank"}). Remember that you have to create the commit in the colrev repository. If there are any code quality problems, these checks will fail and prevent the commit. Try to resolve linting errors (if any). We will address the [typing](https://realpython.com/python-type-checking/){: target="_blank"}-related issues together.
-
 To checkout the **solution**, run:
 
 ```python
-git reset --hard 1de25efdeb8c330c87ea7ad7adeb1378f1f88a5b
+git reset --hard a84c9be1fb215f9cda8920bcdb86ff529bfc83d2
 ```
 
 ## Part IV: Functions <a id="functions"></a>
@@ -173,17 +146,10 @@ Next, we would like to create a function, which adds the `journal_impact_factor`
 | MIS Quarterly            |                    8.3|
 | Information & Management |                  10.3 |
 
-Add your changes to the staging area, run the pre-commit hooks, and address the warnings:
-
-```python
-pre-commit run --all
-```
-
 To checkout the **solution**, run:
 
-
 ```python
-git reset --hard f859208f8ddaf5651f5c2b378e7e07543ca7cdd1
+git reset --hard bc94da869184485f7805dba2b9f8e32af0ff2dfb
 ```
 
 ---
@@ -194,7 +160,7 @@ git reset --hard f859208f8ddaf5651f5c2b378e7e07543ca7cdd1
 
 In this notebook, we have learned to
 
-- Write and execute Python code in Python packages and modules
+- Write and execute Python code in a Python script
 - Create and modify data items, such as dictionaries
 - Install and use external libraries
 - Write modular code by using functions

docs/week_3_python_notebook_2.md

@@ -43,6 +43,14 @@ To checkout the **starting point** (commit), run:
 git reset --hard f859208f8ddaf5651f5c2b378e7e07543ca7cdd1
 ```
 
+## Install colrev
+
+In the following, we start to work with the CoLRev library. To install it, run
+
+```
+uv install colrev
+```
+
 ### Set up the `example` repository<a id="setup"></a>
 
 To use the typical CoLRev environments (objects), we clone an existing CoLRev project:

docs/week_3_python_notebook_3.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: "Python notebook 3"
+parent: "Week 3: Python"
+nav_order: 4
+has_toc: true
+---
+
+# Exercise notebook: Python 3 (packages)
+
+contents:
+
+- package setup (pyproject.toml)
+- unit tests
+- pre-commit to the package tutorial part
+- plugin for colrev (pyproject.toml, base-classes, colrev env --update-package-list)

docs/week_3_python_teaching_notes_3.md

@@ -0,0 +1,11 @@
+---
+layout: default
+title: "Week 3: Python 3"
+nav_exclude: true
+has_toc: true
+search_exclude: true
+---
+
+# Week 3: Python 3 (Teaching notes)
+
+TODO

slides/04-python_3.md

@@ -0,0 +1,23 @@
+---
+marp: true
+header: 'Open Source Project: Introduction to Python'
+theme: ub-theme
+paginate: true
+footer: "<a href='https://github.com/digital-work-lab/open-source-project/issues/new?template=Blank+issue' target='_blank'>♻️</a> <a href='https://github.com/digital-work-lab/open-source-project/edit/main/slides/04-python_2.md' target='_blank'>🛠️</a>"
+---
+
+<!-- _class: centered -->
+
+# WI-Project: Open Source Project
+
+## Introduction to Python (3)
+
+Prof. Dr. Gerit Wagner
+Faculty Information Systems and Applied Computer Sciences
+Otto-Friedrich-Universität Bamberg
+
+![center width:150px](../assets/qr-open-source-project.png)
+
+---
+
+TODO