Merge branch 'main' into readthedocs_branch

Author: enryH

.github/workflows/cicd.yml

@@ -106,6 +106,8 @@ jobs:
   publish:
     name: Publish package
     if: startsWith(github.ref, 'refs/tags')
+    permissions:
+      id-token: write
     needs:
       - format
       - lint
@@ -125,3 +127,4 @@ jobs:
         with:
           # remove repository key to set the default to pypi (not test.pypi.org)
           repository-url: https://test.pypi.org/legacy/
+          

CITATION.cff

@@ -0,0 +1,12 @@
+# https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+- family-names: "Last"
+  given-names: "First"
+  orcid: "https://orcid.org/0000-0000-0000-0000"
+title: "Python Package Template repository"
+version: 0.0.1
+doi: 10.5281/zenodo.1234
+date-released: 2025-07-23
+url: "https://github.com/biosustain/python_package"

Contributing.md

@@ -0,0 +1,36 @@
+# Contributing code
+
+Install the code with development dependencies:
+
+```bash
+pip install -e '.[dev]'
+```
+
+## Format code and sort imports
+
+```bash
+black .
+isort .
+```
+
+## lint code
+
+```bash
+ruff check .
+```
+
+## Run tests
+
+```bash
+pytest
+```
+
+## Sync notebooks with jupytext
+
+For easier diffs, you can use jupytext to sync notebooks in the `docs/tutorial` directory with the percent format.
+
+```bash
+jupytext --sync docs/tutorial/*.ipynb
+```
+
+This is configured in the [`.jupytext`](docs/tutorial/.jupytext) file in that directory.

README.md

@@ -11,14 +11,15 @@ see [GitHub documentation](https://docs.github.com/en/repositories/creating-and-
 You will need to find and replace occurences of
 
 - `python_package` -> `your_package_name`
-    - also the folder `src/python_package` 
+  - also the folder `src/python_package`
 - `RasmussenLab` -> `GitHub_user_name` (or `organization`)
-with the name of your package and GitHub user name (or organization).
+  with the name of your package and GitHub user name (or organization).
 
 - look for `First Last` to see where to replace with your name
 - choose a license, see [GitHub documentation](https://docs.github.com/en/repositories/creating-and-managing-repositories/licensing-a-repository)
   and [Creative Commons](https://creativecommons.org/chooser/).
   Replace [`LICENSE`](LICENSE) file with the license you choose.
+- Update the `CITATION.cff` file with your information.
 
 ## Development environment
 
@@ -41,7 +42,7 @@ print(hello_world(4))
 ## Readthedocs
 
 The documentation can be build using readthedocs automatically. See
-[project on Readthedocs](https://readthedocs.org/projects/rasmussenlab-python-package/) 
+[project on Readthedocs](https://readthedocs.org/projects/rasmussenlab-python-package/)
 for the project based on this template. A new project needs
 to [be registered on ReadTheDocs](https://docs.readthedocs.com/platform/stable/intro/add-project.html).
 

docs/tutorial/.jupytext

@@ -1,2 +1,6 @@
-# all notebooks in this directory are in the percent format
+# all notebooks in this directory are synced percent format when typing
+# (jupytext is a dev dependency)
+# jupytext --sync *.ipynb
+# or from root directory
+# jupytext --sync docs/api_examples/*.ipynb
 formats = "ipynb,py:percent"

pyproject.toml

@@ -1,14 +1,13 @@
 # ref: https://setuptools.pypa.io/en/stable/userguide/pyproject_config.html
 [project]
-authors = [
-  { name = "First Last", email = "first.last@gmail.com" },
-]
+authors = [{ name = "First Last", email = "first.last@gmail.com" }]
 description = "A small example package"
 name = "python_package"
 # This means: Load the version from the package itself.
 # See the section below: [tools.setuptools.dynamic]
-dynamic = ["version", # version is loaded from the package
-#"dependencies", # add if using requirements.txt
+dynamic = [
+  "version", # version is loaded from the package
+  #"dependencies", # add if using requirements.txt
 ]
 readme = "README.md"
 requires-python = ">=3.9" # test all higher Python versions
@@ -44,20 +43,19 @@ docs = [
   "sphinx-copybutton",
 ]
 # local development options
-dev = ["black[jupyter]", "ruff", "pytest"]
+dev = ["black[jupyter]", "ruff", "pytest", "isort", "jupytext"]
 
-# Configure the Ruff linter: Ignore error number 501
 [tool.ruff]
 # https://docs.astral.sh/ruff/rules/#flake8-bandit-s
-# lint.ignore = ["E501"] # Ignore line length errors
-# Allow lines to be as long as (default is 88 in black)
 
 [tool.ruff.lint]
 # https://docs.astral.sh/ruff/tutorial/#rule-selection
 # 1. Enable flake8-bugbear (`B`) rules
 # 2. Enable pycodestyle (`E`) errors and (`W`) warnings
 # 3. Pyflakes (`F`) errors
 extend-select = ["E", "W", "F", "B"]
+# Ignore line length errors:
+# ignore = ["E501"]
 
 [build-system]
 build-backend = "setuptools.build_meta"

src/python_package/__init__.py

@@ -4,8 +4,8 @@
 
 __version__ = metadata.version("python_package")
 
-from .mockup import hello_world
+from .mockup import hello_world, saved_world
 
 # The __all__ variable is a list of variables which are imported
 # when a user does "from example import *"
-__all__ = ["hello_world"]
+__all__ = ["hello_world", "saved_world"]

src/python_package/mockup.py

@@ -13,5 +13,33 @@ def hello_world(n: int) -> str:
     -------
     str
         str of 'hello world' n-times
+
+    Examples
+    --------
+    >>> hello_world(3)
+    'hello world hello world hello world'
     """
     return " ".join(repeat("hello world", n))
+
+
+def saved_world(filename: str) -> int:
+    """
+    Count how many times 'hello world' is in a file.
+
+    Parameters
+    ----------
+    filename : str
+        The file to read
+
+    Returns
+    -------
+    int
+        How many times 'hello world' is in the file
+
+    Examples
+    --------
+    >>> saved_world("not-real.txt") # doctest: +SKIP
+    """
+    with open(filename, "r") as f:
+        content = f.read()
+    return content.count("hello world")

tests/README.md

@@ -0,0 +1,112 @@
+---
+marp: true
+theme: uncover
+paginate: true
+backgroundColor: #fff
+---
+
+# **Getting started with pytesting**
+
+---
+
+## Quick start
+
+### Installation
+
+Install pytest. e.g., from the "dev" dependencies
+
+```bash
+pip install ".[dev]"
+```
+
+### How to use
+
+To execute the tests run e.g.
+
+```bash
+pytest
+```
+
+---
+
+## Test development tips
+
+---
+
+### Folder and test naming
+
+1. The tests for functions in `<filename>.py` should go in `tests/test_<filename>.py`
+
+   e.g., the tests for [python_package/mockup.py](../src/python_package/mockup.py) are in [tests/test_mockup.py](test_mockup.py)
+
+2. The test names should start with `def test_<corresponding_function_name> ...`
+
+   e.g., `def test_hello_world(): ...`
+
+---
+
+### Some Pytest decorators
+
+1. To indicate that the test function is expected to fail you can prepend
+
+   ```python
+   @pytest.mark.xfail(raises=TypeError)
+   def test_hello_world_str(): ...
+   ```
+
+---
+
+2. To setup and cleanup any resources for a test you can use [pytest fixtures with `yield`](https://dev.to/dawidbeno/understanding-yield-in-pytest-fixtures-4m38)
+
+   ```python
+   @pytest.fixture
+   def temp_file():
+       # set up
+       < code to create a file>
+       # return
+       yield
+           the_file
+       # clean up
+       < code to remove the file>
+   ```
+
+---
+
+### Doctests
+
+You can also include tests in your docstrings using `>>>` followed by the expected result e.g.
+
+```python
+def hello_world(n):
+    """
+    Prints 'hello world' n-times.
+        ...
+
+    Examples
+    --------
+    >>> hello_world(3)
+    'hello world hello world hello world'
+        ...
+    """
+```
+
+Needs `addopts = --doctest-modules` in `pytest.ini` in root of directory
+
+---
+
+### Skipping in doctests
+
+If you know that the test cannot succeed but would like to include an example usage in the docstring still then you can add `# doctest: +SKIP` e.g.
+
+```python
+def saved_world(filename):
+    """
+    Count how many times 'hello world' is in a file.
+        ...
+
+    Examples
+    --------
+    >>> saved_world("not-real.txt") # doctest: +SKIP
+        ...
+    """
+```

tests/test_mockup.py

@@ -1,7 +1,31 @@
-from python_package import hello_world
+from python_package import hello_world, saved_world
+import pytest
 
 
 def test_hello_world_3times():
     expected = "hello world hello world hello world"
     result = hello_world(3)
     assert result == expected
+
+
+@pytest.mark.xfail(raises=TypeError)
+def test_hello_world_str():
+    hello_world("3")
+
+
+@pytest.fixture
+def temp_file():
+    # set up
+    filename = "temp_hellooo.txt"
+    with open(filename, "w") as f:
+        f.write("hello world hello world hello world")
+    yield filename
+    # clean up
+    import os
+
+    os.remove(filename)
+
+
+def test_saved_world_3times(temp_file):
+    result = saved_world(temp_file)
+    assert result == 3