Development#

This chapter describes how to set up icalendar for development and to contribute changes.

Prerequisites#

You'll need to first install prerequisites on, and clone the icalendar repository to, your local computer.

Tests, code formatting, and documentation builds and checks require that you install GNU Make, uv, and Git.

Note

uv handles the installation of Python and all dependencies for icalendar.

Make#

Make is used to provide an interface to developers to perform repetitive tasks with a single command.

Make comes installed on most Linux distributions. On macOS, you must first install Xcode, then install its command line tools. On Windows, it is strongly recommended to Install Linux on Windows with WSL, which will include Make.

Finally, it is a good idea to update your system's version of Make, because some distributions, especially macOS, have an outdated version. Use your favorite search engine or trusted online resource for how to update Make.

uv#

uv is used for installing Python, creating a Python virtual environment, and managing dependencies for documentation.

Install uv. Read the console output for further instructions, and follow them, if needed.

macOS, Linux, and Windows with WSL

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Other

Other uv installation methods

Git#

Install Git for your operating system.

Configure Git#

Unless you're a maintainer or administrator, you don't have write access to push commits to GitHub repositories under the Collective organization or the icalendar repository. You can, however, push commits to your fork. Thus, a typical workflow will be circular in nature. You'll pull code from the upstream icalendar repository, push your work from your local clone to your remote fork, then make a pull request from your fork to the upstream icalendar repository.

icalendar git workflow

Start by forking icalendar's repository to your account through the GitHub interface.

See also

Fork a repository
Clone your forked repository.
Configure Git to sync your fork with the upstream repository.

Install icalendar for development#

To install icalendar for development—including all of its dependencies for tests, documentation, and formatting code, as well as a Python virtual environment—run the following command.

make dev

Make commands#

With all prerequisites installed, you can run tests, reformat code, make various documentation builds, perform quality checks, and clean your environment. All Make commands use the file Makefile at the root of the repository.

The Make commands may invoke uv, tox, Sphinx, Vale, shell commands, and other programs.

pre-commit#

pre-commit is automatically installed as one of the development requirements when running the following command.

make dev

That command installs a supported Python, creates a Python virtual environment, and installs package and development requirements.

When you commit code to icalendar with git commit, pre-commit runs the following code quality checks and reformats code automatically for you.

debug-statements: Checks for debugger imports and Python 3.7+ breakpoint() calls in Python source code.
ruff check –fix: Runs the Ruff linter on Python files and fixes issues according to the configuration in pyproject.toml.
ruff format: Runs the Ruff formatter on Python files and fixes issues according to the configuration in pyproject.toml.

The configuration file for pre-commit, .pre-commit-config.yaml, is located at the root of the repository.

Contributors to icalendar are encouraged to use pre-commit. Any issues that would be caught by pre-commit shall be caught by GitHub workflows when you push commits to a pull request for icalendar. This could delay merging of your pull request.

However, you may opt out of using pre-commit. You can use the --no-validate flag for the git commit command.

git commit -m "My commit message" --no-validate

Alternatively, configure your editor to use --no-validate for all commits. The screenshot below shows how to configure PyCharm to disable pre-commit by searching for "git commit hooks" in its settings.

Disable pre-commit in PyCharm settings

Run tests#

Through uv, tox manages all test environments across all Python versions.

To run all tests in all environments, run the following command.

make test

The following command shows how to run tests in Python 3.14.

make test TOX_ENV=py314

Format code#

icalendar requires code formatting. You can run the following command to automatically format the code.

make format

Code conventions#

icalendar has adopted code conventions to help make its code more legible and understandable.

Internal use only#

There are no truly private methods in Python. However, icalendar follows the PEP 8 Python style guide regarding the use of a single leading underscore character _ to the object as "internal use only."

"Internal use only" methods and variables are not part of icalendar's public API, and developers should not use them in their code. These are implementation details that may change without notice.

In addition, "internal use only" objects are not displayed in the documentation. Their docstrings, of course, remain in the Python source code.

Type hints#

Type hints in Python help developers catch errors early, improve code documentation, and enhance the functionality of IDEs and linters. icalendar uses type hints, and supports rendering them in its reference API documentation.

icalendar was originally written before the existence of type hints in Python. As such, there are many Python objects in the code base that lack type hints. The icalendar team welcomes contributions to add type hints.

When the type hints in the standard library are not sufficient, you can use subtyping through protocols. The following example demonstrates subtyping through the usage of a protocol and a method using a literal ellipsis ... to indicate that the method signature exists, but the implementation details aren't necessary.

class HasToIcal(Protocol):
    """Protocol for objects with a to_ical method."""

    def to_ical(self) -> bytes:
        """Convert to iCalendar format."""
        ...

Activate a tox environment#

If you'd like to activate a specific tox virtual environment, use the following command, replacing the Python version accordingly.

source .tox/py312/bin/activate

Install icalendar manually#

The best way to test the package is to use tox as described above.

However, if you can't install tox, or you'd like to use your local copy of icalendar in another Python environment, this section describes how to use your installed version of Python and pip.

cd src/icalendar
python -m pip install -e .

The above commands install icalendar and its dependencies in your Python environment so that you can access local changes. If tox fails to install icalendar during its first run, you can activate the environment in the .tox folder and manually set up icalendar as shown above.

To verify installation, launch a Python interpreter, and issue the following statements.

Python 3.12.0 (main, Mar  1 2024, 09:09:21) [GCC 13.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import icalendar
>>> icalendar.Calendar()
VCALENDAR({})