A List of china stock exchange holidays
Project description
cn_stock_holidays
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:
- Update version in
pyproject.toml
- Create and push a new tag:
git tag v2.0.1 git push origin v2.0.1
- 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
- Fork the repository
- Create a feature branch
- Make your changes
- Run tests and ensure code quality
- Submit a pull request
License
This project is licensed under the MIT License - see the LICENSE file for details.
Links
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
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
Algorithm | Hash digest | |
---|---|---|
SHA256 |
ad523f786fd3e0135185a3cbd0557373b05b26b09a28adc1b5a0b83d6b71c165
|
|
MD5 |
f36632c698b377e1b5cf1e1a0886b2b6
|
|
BLAKE2b-256 |
5a66cd779d8a0193c55a4bf53bf389aceacfe08063d14f0b9cbc4c690e511eb9
|
File details
Details for the file cn_stock_holidays-2.1.3-py3-none-any.whl
.
File metadata
- Download URL: cn_stock_holidays-2.1.3-py3-none-any.whl
- Upload date:
- Size: 18.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: uv/0.7.19
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
b587f4ea11bdf361e79c08411fb1bbcbc0f34a6f7ec45c5a977ad3d7700a81de
|
|
MD5 |
90132c520069a57cee5f202e7f24718b
|
|
BLAKE2b-256 |
5f42b8523fbfd13d50d9829ff578b715235ec873b5982098df45ce566dc57d59
|