xcals

A Python library for managing Chinese A-share trading calendars.

Development workflow (uv)

This project uses uv to manage the virtual environment, dependencies, and package build.

uv sync --dev
uv run ruff check .
uv run pytest
uv build

uv build generates distribution artifacts under dist/.

Use xcals in other projects (without PyPI)

Option 1: local editable dependency

uv add --editable ../xcals

Option 2: git dependency

uv add "xcals @ git+ssh://git@github.com/<org>/xcals.git@main"

Option 3: wheel artifact

uv build
uv add ../xcals/dist/xcals-0.1.0-py3-none-any.whl

Runtime calendar source

xcals reads calendar data from a local file. By default, it uses ~/.xcals.

The package bundles a seed calendar file. If ~/.xcals does not exist, xcals will initialize it from the bundled seed first, then continue normally.

Environment variables:

• XCALS_FILE_PATH: override local calendar file path.
• XCALS_FILE_URL: override remote calendar URL used by update().
• XCALS_AUTO_UPDATE: whether to auto-download when file is missing (1 by default, set 0 to disable).

Usage

from xcals import get_tradingdays, is_tradeday, shift_tradeday

# Get trading days in a range
days = get_tradingdays("2024-01-01", "2024-01-31")
print(days)

# Check if a date is a trading day
print(is_tradeday("2024-01-01"))  # False
print(is_tradeday("2024-01-02"))  # True

# Shift by trading days
print(shift_tradeday("2024-01-02", 1))  # Next trading day

License

MIT