Skip to main content

A List of china stock exchange holidays

Project description

cn_stock_holidays

CI Status

A comprehensive Python package providing China stock exchange holiday data for both Shanghai/Shenzhen (SHSZ) and Hong Kong (HKEX) markets. This package serves as a reliable data source and utility library for financial applications that need to determine trading days.

Features

  • Dual Market Support: Covers both mainland China and Hong Kong markets
  • Multiple Data Sources: Local files, cached data, and remote fetching
  • Zipline Integration: Provides exchange calendars for algorithmic trading
  • CLI Tools: Command-line utilities for data extraction
  • Caching Mechanism: LRU cache for performance optimization
  • Comprehensive API: Functions for trading day calculations

Data Files

Shanghai/Shenzhen Market

cn_stock_holidays/data.txt

Hong Kong Market

cn_stock_holidays/data_hk.txt

Fetch Data via URL

# Shanghai/Shenzhen data
wget https://raw.githubusercontent.com/rainx/cn_stock_holidays/main/cn_stock_holidays/data.txt

# Or using curl
curl https://raw.githubusercontent.com/rainx/cn_stock_holidays/main/cn_stock_holidays/data.txt

Data Format

Shanghai/Shenzhen Market

The data files store all holidays for China stock exchanges (excluding regular weekend closures on Saturday and Sunday), with one date per line in the format:

YYYYMMDD

Hong Kong Market

Hong Kong market data supports both regular holidays and half-day trading days. The format is:

YYYYMMDD    # Regular holiday
YYYYMMDD,h  # Half-day trading day

Half-day trading days are days when the market is open for only part of the day (typically morning session only). Common half-day trading days in Hong Kong include:

  • Christmas Eve (December 24)
  • New Year's Eve (December 31)
  • Lunar New Year's Eve
  • Day before major holidays (Qingming Festival, National Day)

Important: Half-day trading days are still considered trading days by all standard functions (is_trading_day(), next_trading_day(), etc.). Use is_half_day_trading_day() to specifically detect half-day trading days.

Installation

Using uv (Recommended)

This project supports uv, a fast Python package installer:

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

# Install the package
uv pip install cn-stock-holidays

Using pip

pip install cn-stock-holidays

From source

git clone https://github.com/rainx/cn_stock_holidays.git
cd cn_stock_holidays
uv sync --dev  # Install with uv
# or
pip install -e .  # Install with pip

Usage

Import

# For Shanghai/Shenzhen market
import cn_stock_holidays.data as shsz

# For Hong Kong market
import cn_stock_holidays.data_hk as hkex

Core Functions

# Get holiday data
holidays = shsz.get_cached()  # Get from cache or local file
holidays = shsz.get_local()   # Read from package data file
holidays = shsz.get_remote_and_cache()  # Fetch from network and cache

# Trading day operations
is_trading = shsz.is_trading_day(date)  # Check if date is a trading day
prev_day = shsz.previous_trading_day(date)  # Get previous trading day
next_day = shsz.next_trading_day(date)  # Get next trading day

# Get trading days in range
for trading_day in shsz.trading_days_between(start_date, end_date):
    print(trading_day)

# Data synchronization
shsz.sync_data()  # Sync data if expired
shsz.check_expired()  # Check if data needs update

Hong Kong Market with Half-Day Trading Support

# Import Hong Kong market functions
import cn_stock_holidays.data_hk as hkex

# Standard trading day functions (same as Shanghai/Shenzhen)
is_trading = hkex.is_trading_day(date)
prev_day = hkex.previous_trading_day(date)
next_day = hkex.next_trading_day(date)

# Half-day trading detection (Hong Kong market only)
is_half_day = hkex.is_half_day_trading_day(date)  # Check if date is a half-day trading day

# Get data with half-day trading support
holidays, half_days = hkex.get_cached_with_half_day()  # Returns (holidays_set, half_days_set)

# Data synchronization with half-day support
hkex.sync_data_with_half_day()  # Sync data if expired
hkex.check_expired_with_half_day()  # Check if data needs update

Function Details

Help on module cn_stock_holidays.data:

FUNCTIONS
    check_expired()
        Check if local or cached data needs update
        :return: True/False

    get_cached()
        Get from cache version, if not existing, use txt file in package data
        :return: A set/list contains all holiday data, elements with datetime.date format

    get_local()
        Read data from package data file
        :return: A list contains all holiday data, elements with datetime.date format

    get_remote_and_cache()
        Get newest data file from network and cache on local machine
        :return: A list contains all holiday data, elements with datetime.date format

    is_trading_day(dt)
        :param dt: datetime.datetime or datetime.date
        :return: True if trading day, False otherwise

    next_trading_day(dt)
        :param dt: datetime.datetime or datetime.date
        :return: Next trading day as datetime.date

    previous_trading_day(dt)
        :param dt: datetime.datetime or datetime.date
        :return: Previous trading day as datetime.date

    sync_data()
        Synchronize data if expired

    trading_days_between(start, end)
        :param start, end: Start and end time, datetime.datetime or datetime.date
        :return: A generator for available trading dates in Chinese market

Cache Management

From version 0.10 onwards, we use functools.lru_cache on get_cached for better performance. If needed, you can clear the cache using:

get_cached.cache_clear()

Command Line Tools

Data Synchronization

# Sync Shanghai/Shenzhen data
cn-stock-holiday-sync

# Sync Hong Kong data
cn-stock-holiday-sync-hk

Get Trading Days List

# Get trading days between dates
get-day-list --start 2024-01-01 --end 2024-01-31 --daytype workday

# Get holidays between dates
get-day-list --start 2024-01-01 --end 2024-01-31 --daytype holiday

# For Hong Kong market
get-day-list --market hk --start 2024-01-01 --end 2024-01-31 --daytype workday

Keeping Data Up-to-Date

The package includes scripts to check data expiration and fetch updates from the web. You can set up automatic updates using cron:

# Daily sync at midnight
0 0 * * * /usr/local/bin/cn-stock-holiday-sync > /tmp/cn_stock_holiday_sync.log

Find the absolute path of sync commands:

# Shanghai/Shenzhen
which cn-stock-holiday-sync

# Hong Kong
which cn-stock-holiday-sync-hk

Zipline Integration

For algorithmic trading with Zipline:

from cn_stock_holidays.zipline import SHSZExchangeCalendar, HKExchangeCalendar

# Use in Zipline
calendar = SHSZExchangeCalendar()  # Shanghai/Shenzhen
calendar = HKExchangeCalendar()     # Hong Kong

Development

Setup Development Environment

# Clone and setup
git clone https://github.com/rainx/cn_stock_holidays.git
cd cn_stock_holidays

# Install with uv (recommended)
uv sync --dev

# Or with pip
pip install -e .[dev]

Run Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=cn_stock_holidays

# Format code
uv run black .

# Type checking
uv run mypy cn_stock_holidays/

Publishing

This project uses PyPI Trusted Publisher for secure automated publishing. The CI workflow automatically publishes to PyPI when a new tag is pushed.

To publish a new version:

  1. Update version in pyproject.toml
  2. Create and push a new tag:
    git tag v2.0.1
    git push origin v2.0.1
    
  3. The CI workflow will automatically test, build, and publish to PyPI

Security Benefits:

  • No need to manage long-lived API tokens
  • Short-lived authentication tokens (15 minutes)
  • Repository-specific permissions
  • Automated OIDC authentication

See Trusted Publisher Setup for detailed configuration instructions.

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Run tests and ensure code quality
  5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Links

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cn_stock_holidays-2.1.3.tar.gz (89.5 kB view details)

Uploaded Source

Built Distribution

cn_stock_holidays-2.1.3-py3-none-any.whl (18.2 kB view details)

Uploaded Python 3

File details

Details for the file cn_stock_holidays-2.1.3.tar.gz.

File metadata

  • Download URL: cn_stock_holidays-2.1.3.tar.gz
  • Upload date:
  • Size: 89.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: uv/0.7.19

File hashes

Hashes for cn_stock_holidays-2.1.3.tar.gz
Algorithm Hash digest
SHA256 ad523f786fd3e0135185a3cbd0557373b05b26b09a28adc1b5a0b83d6b71c165
MD5 f36632c698b377e1b5cf1e1a0886b2b6
BLAKE2b-256 5a66cd779d8a0193c55a4bf53bf389aceacfe08063d14f0b9cbc4c690e511eb9

See more details on using hashes here.

File details

Details for the file cn_stock_holidays-2.1.3-py3-none-any.whl.

File metadata

File hashes

Hashes for cn_stock_holidays-2.1.3-py3-none-any.whl
Algorithm Hash digest
SHA256 b587f4ea11bdf361e79c08411fb1bbcbc0f34a6f7ec45c5a977ad3d7700a81de
MD5 90132c520069a57cee5f202e7f24718b
BLAKE2b-256 5f42b8523fbfd13d50d9829ff578b715235ec873b5982098df45ce566dc57d59

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page