CCB Meeting Scheduling Repository

This repository contains the Meetings class, which is based on the Python timeboard project. Its primary purpose is to help create the CCB weekly meetings schedule. Additionally, it serves as a template repository for Python projects that require a Docker container with a complete Python development environment and testing capabilities. The repository is also configured to run tests using GitHub Actions.

Installation Locally with Docker

1. Install Docker on your machine.

2. Clone the GitHub project repository to create a local copy:

   git clone [email protected]:ccb-hms/cadence.git

3. Navigate to the repository's directory and build the Docker image:

   cd cadence && docker-compose build

   This image will include all specifications from the Dockerfile based on the official Python 3.12 Docker image, along with all dependencies described in the project's pyproject.toml file. The image is built locally and stored in the Docker cache. To rebuild the image, run docker-compose build again. To remove the image, run docker-compose down --rmi all.

4. Run the Docker container:

   docker-compose up

   This command creates a container and starts a Jupyter server, which can be accessed through a web browser.

5. Access the Jupyter Lab server from your browser by visiting the link that begins with localhost:8888.

Installation without Docker

For installation in a local programming environment, we use uv to create a pure, repeatable application environment. Mac and Windows users should install uv as described in the installation instructions. UV is a fast Python package installer and resolver, written in Rust. It serves as a drop-in replacement for pip and pip-tools, offering significant performance improvements and a more efficient workflow.

UV manages dependencies on a per-project basis. To install this package, change to your project directory and run:

# Install the package. This assumes that Python version 3.12 is set as the current global Python interpreter. 
uv venv --python=3.12.10

# Activate the environment
source .venv/bin/activate 
# On Windows use: .venv\Scripts\activate uv pip install -e .

# Next, install the dependencies
uv sync

# Lastly, run the Jupyter Lab server in the new environment
uv run jupyter lab

Install with Other Python Versions

The package was tested with Python 3.12.10, as defined within the project's configuration. However, it comes with compatibility libraries to ensure that it can be used with lower Python versions. To install this package with a different version of Python, such as Python 3.10, first create a virtual environment with the desired version:

uv venv --python=3.10 
source .venv/bin/activate 
# On Windows use: .venv\Scripts\activate uv pip install -e .

It is also possible to install the package using a local Python interpreter that is installed in a specific directory, for example, within a virtual environment created with Miniconda:

uv venv --python=/home/.../miniconda3/envs/uv-test/bin/python
source .venv/bin/activate 
# On Windows use: .venv\Scripts\activate uv pip install -e .

Here, uv-test is the directory that contains the executable Python interpreter created by Miniconda.

Create a Meeting Schedule

For a detailed example, refer to the scheduling_example notebook. This example demonstrates how easy it is to create a meeting schedule with just a list of names:

from cadence.mscheduler import Meetings

# Let's start with a list of some names
name_list = ['Andreas', 'Eva', 'Matthias', 'Manuela']

# Define the start and end dates for the meeting schedule
start_date = '2024-11-13'
end_date = '2025-01-30'

# Specify that the group will meet once per week on Wednesdays
meeting_day = 2

# Now we create the meeting schedule
meeting = Meetings(name_list=name_list)
schedule = meeting.create_timeboard(start_date=start_date, end_date=end_date, meeting_day=meeting_day)

The output of the create_timeboard method is a DataFrame that can be saved and imported into other applications, such as calendars.

Run Tests

Pytest is a popular testing framework that makes it easy to write small, readable tests.

The pytest framework scales to support complex functional testing for applications and libraries. Pytest will automatically discover and run all the test files in the ./tests directory that follow the naming conventions (i.e., files starting with test_ or ending with _test.py). You can also specify the test directory explicitly by running pytest tests/ if your test directory is named tests. Pytest will execute all the discovered test cases and provide a detailed report.