README.md: Add `uv`, and `git` sections

[davidhedlund]

I propose that we update https://github.com/vacanza/holidays/blob/dev/README.md#install

Current https://github.com/vacanza/holidays/blob/dev/README.md#install

The latest stable version can always be installed or updated via pip:

pip install --upgrade holidays

The latest development (dev) version can be installed directly from GitHub:

pip install --upgrade https://github.com/vacanza/holidays/tarball/dev

All new features are always first pushed to dev branch, then released on main branch upon official
version upgrades.

Proposed https://github.com/vacanza/holidays/blob/dev/README.md]

uv

This it applies to all OSes.

Installation

Refer to https://docs.astral.sh/uv/getting-started/installation/ for how to install uvx.

Usage

• Evaluate python code: uvx --with holidays python3
• Execute python file: uvx --with holidays python3 file.py
• Generate calendar file with holidays-ics: uvx --from holidays holidays-ics US

git, or pip

git

Installation

git clone https://github.com/vacanza/holidays.git
cd holidays/

# Enable language support
python3 -c "import polib; from pathlib import Path; [polib.pofile(str(f)).save_as_mofile(str(f.with_suffix('.mo'))) for f in Path('holidays/locale').rglob('*.po')]"

git apt dependencies (Debian, Ubuntu, etc)

Step 1

sudo apt update && sudo apt install -y git python3-polib python3-holidays

Step 2

See the git section.

pip

Note: This method is not recommended for Debian, Ubuntu, or their derivatives. While it requires pip3, you must use the --break-system-packages flag to bypass system restrictions. Avoid using --break-system-packages for routine package installation because it can create conflicts with packages managed by apt. Read more here [add https://github.com/vacanza/holidays/blob/dev/docs/PIPWARNING]

The latest stable version can always be installed or updated via pip:

pip install --upgrade holidays

The latest development (dev) version can be installed directly from GitHub:

pip install --upgrade https://github.com/vacanza/holidays/tarball/dev

PIPWARNING

$ pip install --upgrade holidays
Command 'pip' not found, but can be installed with:
sudo apt install python3-pip
$ sudo apt install python3-pip
The following additional packages will be installed:
  javascript-common libexpat1-dev libjs-jquery libjs-sphinxdoc libjs-underscore libpython3-dev
  libpython3.12-dev python3-dev python3-setuptools python3-wheel python3.12-dev zlib1g-dev
Suggested packages:
  apache2 | lighttpd | httpd python-setuptools-doc
The following NEW packages will be installed:
  javascript-common libexpat1-dev libjs-jquery libjs-sphinxdoc libjs-underscore libpython3-dev
  libpython3.12-dev python3-dev python3-pip python3-setuptools python3-wheel python3.12-dev
  zlib1g-dev
$ pip install --upgrade holidays
error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.
    
    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.
    
    If you wish to install a non-Debian packaged Python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you. Make sure you have pipx installed.
    
    See /usr/share/doc/python3.12/README.venv for more information.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

--break-system-packages is required but not recommend

The workaround relies on pip3, but you'll need to use the --break-system-packages flag to get it to run.

CMD="pip3"
if ! command -v $CMD >/dev/null 2>&1; then
    echo "$CMD not found. Installing..."
    
    # Track the current path before changing directories
    ORIGINAL_PATH=$(pwd)

    cd /tmp/ || exit 1

    # Executing this in a subshell protects the main CMD="pip3" variable from being overwritten
    ( CMD="curl"; command -v "$CMD" >/dev/null 2>&1 || (sudo apt update && sudo apt install -y "$CMD") )

    curl -sS https://bootstrap.pypa.io/get-pip.py -o get-pip.py
    python3 get-pip.py --user --break-system-packages # Reference 1
    rm -f get-pip.py

    # Return to the tracked original path
    cd "$ORIGINAL_PATH" || exit 1

    # Add to .bashrc if it does not already exist
    LINE='export PATH="$HOME/.local/bin:$PATH"'
    grep -qF "$LINE" ~/.bashrc || echo "$LINE" >> ~/.bashrc
    
    # Update the current script's environment path immediately
    export PATH="$HOME/.local/bin:$PATH"
    
    $CMD --version
else
    echo "$CMD is already installed."
fi

pip3 install --upgrade holidays --break-system-packages # Reference 1

# References
# 1: Add the "--break-system-packages" suggested by "pip install --upgrade holidays": "You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages."

Usage

• Evaluate python code: python3
• Execute python file: python3 file.py
• Generate calendar file with holidays-ics: python3 -m holidays.generate_ics US

[davidhedlund]

@PPsyrius This is quite important, as it impacts both Debian and Ubuntu—the foundation for the majority of GNU/Linux distributions, including 100% free distros like Trisquel.

[KJhellico]

I'm not a regular Linux user, so I didn't quite understand the nature of the problem. If someone needs holidays package for development, they can install it in their usual development environment (with pip, uv, poetry, etc.). If only ICS generation script is needed, it’s easier to use uvx than to run some scripts (and commands with ominous-sounding options like --break-system-packages).

[davidhedlund]

I'm not a regular Linux user, so I didn't quite understand the nature of the problem. If someone needs holidays package for development, they can install it in their usual development environment (with pip, uv, poetry, etc.). If only ICS generation script is needed, it’s easier to use uvx than to run some scripts (and commands with ominous-sounding options like --break-system-packages).

The main post now contains two sections

• Current https://github.com/vacanza/holidays/blob/dev/README.md#install
• Proposed https://github.com/vacanza/holidays/blob/dev/README.md#install

I originally planned to add uvx later, as this issue initially focused only on git and apt dependencies. However, I have now updated the main post with a section for uvx under a "Install [proposed]" section.

Please take a fresh look when you get a chance.

[arkid15r]

It kind of signals that the framework needs a CLI. I discussed this idea with @KJhellico about a month ago, and based on the current roadmap, the plan is to build a Go-based implementation packaged for major operating systems. It's a significant amount of work, but it feels like a natural evolution of the project and an important next step.

[KJhellico]

• Proposed

I still don't quite understand the target audience for such a detailed description. 🤷‍♂️

[davidhedlund]

• Proposed

I still don't quite understand the target audience for such a detailed description. 🤷‍♂️

When you factor in everything built directly on Debian, everything derived from Ubuntu, and all the subsequent sub-derivatives (like GNU/Linux Mint or Pop!_OS), this single family tree accounts for well over 200 actively maintained operating systems.

To put that into perspective, out of the roughly 600 to 1,000+ GNU/Linux distributions that have ever existed, this massive Debian-rooted ecosystem makes up 60% to 70% of all active distros today.

[KJhellico]

It seems to me that you're viewing the library solely as a tool for generating iCalendar files. It has a much broader purpose. ;)

[KJhellico]

Yes, uv mention definitely needs to be included.