urnc package

University of Regensburg Notebook Converter

Package for converting jupyter notebook files within a course directory into a format suitable for student use. It simplifies the process of preparing and maintaining course materials by providing easy-to-use commands to check, convert, and manage course versions.

Subpackages

Submodules

urnc.ci module

Functions to be used by CI pipelines

ci(config)

Perform a continuous integration run on a student repository.

This function

  1. Clones the student repository

  2. Clears it

  3. Copies over all files from the course repository

  4. Converts the notebooks

  5. Updates the .gitignore file according to the git.exclude setting from the config.yaml

  6. Commits and pushes the changes if commit is True

Parameters:

config (dict) – The configuration object.

Raises:

Exception – If the repository is dirty and commit is True, an exception is raised.

clear_repo(repo)
clone_student_repo(config)

Clones the student repository if it doesn’t exist locally, or returns the existing local repository. If the ‘student’ key is not found in the ‘git’ section of the config, it initializes a new student repository.

Parameters:

config (dict) – The configuration dictionary.

Returns:

The cloned, existing, or newly initialized local git repository.

Return type:

git.Repo

Raises:

  • Exception – If the ‘student’ key is not found in the ‘git’ section of the config and the initialization of a new repository fails.

  • Exception – If the local repository exists but is not a git repository.

  • Exception – If there is a mismatch between the remote URL and the local repository’s URL.

update_index(repo)
write_gitignore(main_gitignore, student_gitignore, config)

Writes a .gitignore file in the student repository.

This function copies the .gitignore file from the main repository (if it exists) and appends additional patterns to exclude based on the configuration.

Parameters:

  • main_gitignore (Optional[str]) – The path to the .gitignore file in the main repository. If None, no .gitignore file is copied.

  • student_gitignore (str) – The path to the .gitignore file in the student repository.

  • config (Dict) –

    The configuration dictionary. Can contain a git key with a exclude key, which should be a list of patterns to exclude. Each pattern can be a string or a dictionary with a pattern key and optional after and until keys specifying a date range, e.g.:

    git:
    exclude:
        - *.pyc
        - /tutorials/*.*
        - {pattern: '!tutorials/Tutorial_1.ipynb', after: '2023-10-25 9:30 CET'}
        - {pattern: '!tutorials/Tutorial21.ipynb', after: '2023-10-25 9:30 CET'}

Return type:

None

urnc.config module

class TargetType(*values)

Bases: StrEnum

CLEAR = 'clear'
EXECUTE = 'execute'
FIX = 'fix'
SOLUTION = 'solution'
STUDENT = 'student'
class WriteMode(*values)

Bases: StrEnum

DRY_RUN = 'dry-run'
INTERACTIVE = 'interactive'
OVERWRITE = 'overwrite'
SKIP_EXISTING = 'skip-existing'
default_config(root)

Create a default configuration object with the base path set to the root of the course.

Parameters:

root – The root directory of the course.

Returns:

The configuration dictionary.

Return type:

config

find_file(path, filename)

Finds a file in a given path or any of its parent directories.

Parameters:

  • path (Path) – The path to start the search from.

  • filename (str) – The name of the file to find.

Returns:

The path to the file if found, otherwise None.

Return type:

Optional[Path]

merge_dict(source, target)
read(root)

Reads the configuration from a YAML file named ‘config.yaml’ located at the root of the git repository.

Parameters:

root (Path) – The root directory of the course. Defaults to the root of the git repository when called from within a git repository.

Raises:

  • click.UsageError – If the ‘config.yaml’ file does not exist in the git root folder.

  • click.FileError – If there is an error reading the file or processing its content.

Returns:

The configuration dictionary.

Return type:

dict

resolve_path(config, pathstr)

Resolves a path relative to the course root.

Parameters:

  • config (dict) – The configuration dictionary.

  • path – The path to resolve.

  • pathstr (Path)

Returns:

The resolved absolute path.

Return type:

Path

write_version(root, version)
Parameters:

  • root (Path)

  • version (str)

urnc.convert module

convert(config, input, targets)
Parameters:

  • config (dict)

  • input (Path)

  • targets (List[dict])

convert_target(input, path, type, config)
Parameters:

  • input (Path)

  • path (str)

  • type (str)

  • config (dict)

create_nb_config(config)
Parameters:

config (dict)

Return type:

Config

filter_notebooks(notebooks, ignore_patterns)
Parameters:

  • notebooks (List[Path])

  • ignore_patterns (List[str])

Return type:

List[Path]

find_notebooks(input, output_path)
Parameters:

  • input (Path)

  • output_path (Path | None)

Return type:

List[Path]

write_notebook(notebook, path, config)
Parameters:

path (Path | None)

urnc.format module

class NbPath(path, rootpath)

Bases: object

Path to a jupyter notebook inside a arbitrarily nested directory structure.

Parameters:

  • path (Path)

  • rootpath (Path)

path

Path object initialized from the provided path.

Type:

Path

abspath

Absolute path to the notebook.

Type:

str

absdirpath

Absolute path to the directory containing the notebook.

Type:

str

rootpath

Absolute path to the root directory of the notebook.

Type:

str

relpath

Relative path to the notebook from the root directory.

Type:

str

reldirpath

Relative path to the directory containing the notebook from the root directory.

Type:

str

name

Name of the notebook including extension.

Type:

str

basename

Name of the notebook without extension.

Type:

str

ext

Extension of the notebook without the dot.

Type:

str

Example

>>> path = "C:/Users/max/mycourse/lectures/week2/lecture1.ipynb"
>>> rootpath = "C:/Users/max/mycourse"
>>> nb = NbPath(path, rootpath)
>>> nb.abspath    == "C:/Users/max/mycourse/lectures/week2/lecture1.ipynb"
>>> nb.absdirpath == "C:/Users/max/mycourse/lectures/week2"
>>> nb.rootpath   == "C:/Users/max/mycourse"
>>> nb.relpath    == "lectures/week2/lecture1.ipynb"
>>> nb.reldirpath == "lectures/week2"
>>> nb.name       == "lecture1.ipynb"
>>> nb.basename   == "lecture1"
>>> nb.ext        == "ipynb"
format_path(path, pattern, root)
Parameters:

  • path (Path)

  • pattern (str | None)

  • root (Path)

Return type:

Path | None

is_directory_path(pattern)
Parameters:

pattern (str | None)

Return type:

bool

urnc.git module

branch_exists(repo, branch)
get_repo(path)
git_folder_name(git_url)
set_commit_names(repo)

urnc.init module

init(config, name)
name_to_dirname(name)
Parameters:

name (str)

Return type:

str

write_config(path, name)
Parameters:

  • path (Path)

  • name (str)

write_gitignore(path)
Parameters:

path (Path)

write_notebook(path, config)
Parameters:

  • path (Path)

  • config (dict)

urnc.logger module

Logging functionality for URNC

class CustomFormatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)

Bases: Formatter

Initialize the formatter with specified format strings.

Initialize the formatter either with the specified format string, or a default as described above. Allow for specialized date formatting with the optional datefmt argument. If datefmt is omitted, you get an ISO8601-like (or RFC 3339-like) format.

Use a style parameter of ‘%’, ‘{’ or ‘$’ to specify that you want to use one of %-formatting, str.format() ({}) formatting or string.Template formatting in your format string.

Changed in version 3.2: Added the style parameter.

format(record)

Format the specified record as text.

The record’s attribute dictionary is used as the operand to a string formatting operation which yields the returned string. Before formatting the dictionary, a couple of preparatory steps are carried out. The message attribute of the record is computed using LogRecord.getMessage(). If the formatting string uses the time (as determined by a call to usesTime(), formatTime() is called to format the event time. If there is exception information, it is formatted using formatException() and appended to the message.

add_file_handler(log_file)
Parameters:

log_file (Path)

critical(msg)
Return type:

NoReturn

dbg(msg)
error(msg)
log(msg)
set_verbose()
setup_logger(verbose=False)

Sets up a logger with a custom handler and formatter.

Parameters:

  • use_file – If True, a file handler is added to the logger.

  • verbose (bool) – If True, the logger’s level is set to DEBUG. Otherwise, to INFO.

Returns:

None

Return type:

None

setup_test_logger()
warn(msg)

urnc.main module

Main entry point for urnc when called from command line

urnc.pull module

Fetch and merge the student repo

clone(git_url, output, branch, depth)

Pull (or clone) a remote git repository, but only do a fast-forward pull.

Parameters:

  • git_url (str) – The URL of the git repository to pull.

  • output (str) – The name of the output folder.

  • branch (str) – The branch to pull.

  • depth (int) – The depth for git fetch.

Returns:

None

Raises:

  • Does not raise any exceptions, but logs errors and warnings. –

  • This is required because this function may be called from a jupyter postStart hook, –

  • and exception would prevent the notebook from starting. –

get_repo(git_url, output, branch, depth)
get_upstream_added(repo)
get_upstream_changes(repo)
get_upstream_deleted(repo)
merge(repo)
pull(git_url, output, branch, depth)

Pull (or clone) a remote git repository and try to automatically merge local changes. This is essentially a wrapper around git pull and git merge -Xours.

Parameters:

  • git_url (str) – The URL of the git repository to pull.

  • output (str) – The name of the output folder.

  • branch (str) – The branch to pull.

  • depth (int) – The depth for git fetch.

Returns:

None

Raises:

  • Does not raise any exceptions, but logs errors and warnings. –

  • This is required because this function may be called from a jupyter postStart hook, –

  • and exception would prevent the notebook from starting. –

rename_file_with_timestamp(path)
rename_local_untracked(repo)
reset_deleted_files(repo)

urnc.util module

Utility functions for urnc

branch_exists(repo, branch)
class chdir(path)

Bases: ABC

Non thread-safe context manager to change the current working directory.

Same as contextlib.chdir. We implement it ourselves because contextlib.chdir is only available for python versions >=3.11 and we want to support versions >=3.8.

Example

>>> with chdir(".."):
>>>     # This code will be executed in the parent directory of the current working directory
>>>     pass
get_course_repo()
get_course_root()

This function navigates up the directory tree from the current working directory until it finds a config.yaml file or it reaches the root directory. If it doesn’t find a ‘config.yaml’ file, it raises an Exception.

Returns:

path of the course directory.

Return type:

Path

Raises:

Exception – If no ‘config.yaml’ file is found in the directory hierarchy.

get_urnc_root()

This function navigates up the directory tree from the current working directory until it finds a ‘pyproject.toml’ file that belongs to the ‘urnc’ package, or it reaches the root directory. If it doesn’t find a suitable ‘pyproject.toml’ file, it raises an Exception.

Returns:

The path of the directory containing the ‘pyproject.toml’ file of the ‘urnc’ package.

Return type:

str

Raises:

  • Exception – If no ‘pyproject.toml’ file is found in the directory hierarchy.

  • Exception – If the found ‘pyproject.toml’ file does not belong to the ‘urnc’ package.

git_folder_name(git_url)
tag_exists(repo, tag)
update_repo_config(repo)

urnc.version module

Manage the semantic version of your course

bump(version, action)

Bump the version based on the action

Parameters:

  • version (str) – The current version.

  • action (str) – The action to perform (show, patch, minor, major, prerelease).

Returns:

The new version after bumping, or None if action is ‘show’.

read_pyproject_version(path)
Parameters:

path (Path)

version_course(config, action)

Bump the version of the course.

Parameters:

  • config (dict) – The configuration object.

  • action (str) – The action to perform (show, patch, minor, major).

Return type:

str

version_self(config, action)

Bump the version of the urnc project itself.

Parameters:

  • config (dict) – The configuration object.

  • action (str) – The action to perform (show, patch, minor, major).

Return type:

str

write_pyproject_version(path, version)
Parameters:

  • path (Path)

  • version (str)