.. SPDX-FileCopyrightText: 2025 icalendar-anonymizer contributors
.. SPDX-License-Identifier: AGPL-3.0-or-later

============
Installation
============

This guide covers installation for end users. For development setup, see :doc:`contributing`.

Requirements
============

- Python 3.11, 3.12, or 3.13

Basic Installation
==================

Install the core package with pip:

.. code-block:: shell

    pip install icalendar-anonymizer

This installs only the Python package with its core dependency, ``icalendar``.

Optional Features
=================

This section describes how to install optional features of ``icalendar-anonymizer``, including a command-line interface (CLI) and web service support.

Command-Line Interface
----------------------

Install the CLI with the following command.

.. code-block:: shell

    pip install icalendar-anonymizer[cli]

This installs the :program:`icalendar-anonymize` and :program:`ican` commands. See :doc:`usage/cli` for usage details.

Web Service
-----------

Install the web service with the following command.

.. code-block:: shell

    pip install icalendar-anonymizer[web]

This installs FastAPI, uvicorn, and dependencies for the REST API server. See :doc:`usage/web-service` for usage details.

All Features
------------

Install all the foregoing optional features with the following command.

.. code-block:: shell

    pip install icalendar-anonymizer[all]

Docker
======

.. note::
    Not yet implemented. See `Issue #8 <https://github.com/mergecal/icalendar-anonymizer/issues/8>`_.

.. When available:
..
.. .. code-block:: shell
..
..     docker pull sashankbhamidi/icalendar-anonymizer

Verifying Installation
======================

Check the installation:

.. code-block:: python

    import icalendar_anonymizer
    print(icalendar_anonymizer.__version__)

Or check the installed version with pip:

.. code-block:: shell

    pip show icalendar-anonymizer

Upgrading
=========

Upgrade to the latest version:

.. code-block:: shell

    pip install --upgrade icalendar-anonymizer

Uninstalling
============

Remove the package:

.. code-block:: shell

    pip uninstall icalendar-anonymizer

Troubleshooting
===============

This section describes how to troubleshoot issues with installation.

Import Error
------------

If you get an ``ImportError`` when importing ``icalendar_anonymizer``, then try the following steps.

#. Verify that the package is installed.

   .. code-block:: shell

       pip list | grep icalendar

#. Check that you're using a supported version of Python.

   .. code-block:: shell

       python --version

#. Ensure that you're in the correct virtual environment.

Dependency Conflicts
--------------------

``icalendar-anonymizer`` requires a compatible version of ``icalendar``.
If you encounter dependency conflicts with ``icalendar``, then perform the following steps.

#. Check that your installed version of ``icalendar`` is supported by ``icalendar-anonymizer``.

   .. code-block:: shell

       pip show icalendar

#. Upgrade ``icalendar``, if needed.

   .. code-block:: shell

       pip install --upgrade icalendar

Getting Help
============

If you encounter installation issues:

- Check the `Issue Tracker <https://github.com/mergecal/icalendar-anonymizer/issues>`_ for existing issues.
- If there isn't an existing issue, then open a new one.
