Metadata-Version: 2.3
Name: cnexchcal
Version: 0.3.3
Summary: Holidays in China
Author: rhozhang
Author-email: rhozhang <rhozhang@163.com>
Requires-Dist: polars>=1.43.0
Requires-Dist: typer>=0.27.0
Requires-Python: >=3.14
Description-Content-Type: text/markdown

# Holidays in China

## Background

We classify calendar days into:

- **regular workdays**: working days not on weekends
- **regular weekends**: weekends (Saturday and Sunday) not working
- **festivals**: true or legal holidays. e.g. 2026-01-01 (Thursday) is New Year holiday; 2023-01-02 (Monday), which is shifted from 2023-01-01 (Sunday), is also a legal holiday
- **quasi-holidays**: extra holidays swapped with weekend workdays
- **weekend workdays**：workdays in weekends for swapped extra holidays

For example, 2025-12-31 (Wednesday) is a regular workday.

2025-01-01 (Thursday) is a festival holiday (New Year)

2025-01-02 (Friday) is a quasi-holiday, though we need not to work on this day, but we need to work on 2026-01-04 (Sunday) to swap with this extra holiday.

2025-01-03 (Saturday) is a regular weekend.

2025-01-04 (Sunday) is a weekend workday. Though it a weekend, but we to work on this day to swap with extra extra holiday on 2025-01-02.

On weekend workdays, exchanges in China mainland are closed, although they are workdays.

In November each year, the state council of China announces the holiday arrangement for next year. Please update the holiday data accordingly.

There is a special festival on Feb. 9, 2024. On this date, exchanges are closed to celebrate the Anti-Fascist 70th Day (中国人民抗日战争暨世界反法西斯战争胜利70周年纪念日)

## cnexchcal Package

This package provides a class to handle holidays and trading days in China mainland since year 2004. We does not touch holidays before 2004.

### Installation

```
pip install cnexchcal
```

### Usage

**Instantiation**:

```
import cnholidays
```

To return holiday names in Chinese or English, along with number of holidays, use:

```
cnholidays.listholidays()
```

To determine if a given date is a holiday or workday, uese:

```
cnholidays.isholiday('2026-01-04')   # False
cnholidays.isworkday('2026-01-04')   # True
```

To determine if a given date is a trading day:

```
cnholidays.issession('2026-01-04')   # False
```

To get the previous trading day, use:

```
cnholidays.previoussession('2026-01-04')   # 2025-12-31
```

To get the next trading day, use:

```
cnholidays.nextsession('2026-01-01')   # 2026-01-05
```

To get the n-th trading day after a given date, use:

```
cnholidays.next_nth_tradingday('2026-01-01', 3)   # 2026-01-07
``` 

To get the n-th trading day before a given date, use:

```
cnholidays.previous_nth_tradingday('2026-01-01', 3)   # 2025-12-29
``` 

To get all trading dates between two given dates, use:

```
cnholidays.trade_date_range('2025-12-20', '2026-02-28')
```

To get the number of trading days in a given year, use:

```
cnholidays.ntradedays(2025)
```
