cnworkdays

cnworkdays is Python tool that calculates working days in China by considering both public holidays and compensatory working days. It enables you to efficiently manage schedules around Chinese holidays.

cnworkdays provides three interfaces:

• Web interface: access a web application powered by marimo.
• Terminal interface: use a command-line interface built with Textual.
• Python API: integrate cnworkdays directly into your Python projects.

Installation

To avoid conflicts with your existing Python environment, install cnworkdays using pipx:

pipx install cnworkdays

Getting Started

1. Run the cnworkdays command:

   cnworkdays
   

2. Choose an application:

   • holiparse: parses official holiday announcements. For more information, see Holiday Announcement Parser.
   • workcalc: calculates working days. For more information, see Working Day Calculator.

3. Select an interface (for workcalc):

   • Web interface (default)
   • Terminal interface

4. Configure connection settings (for the web interface):

   • Host address (default: 127.0.0.1)
   • Port number (default: 8080)

Holiday Announcement Parser

The holiparse application extracts structured data from official State Council announcements, including:

• Annual public holidays
• Compensatory working days

Use the web interface

To launch the web application for parsing holiday announcements:

cnworkdays holiparse web

To specify a custom host and port, use the --host and --port flags:

cnworkdays holiparse web --host 0.0.0.0 --port 9000

Working Day Calculator

The workcalc application calculates dates before or after a specified number of working days, taking into account:

• Official public holidays
• Compensatory working days

Use the web interface

To launch the web application for calculating working days:

cnworkdays workcalc web

To specify a custom host and port, use the --host and --port flags:

cnworkdays workcalc web --host 0.0.0.0 --port 9000

Use the terminal interface

To launch the terminal interface for calculating working days:

1. Run the following command:

   # Terminal interface
   cnworkdays workcalc terminal
   

2. Enter the required information:

   • Start Date: enter the start date in the "YYYY-MM-DD" format.
   • Select Subtract or Add.
   • Working Days: enter the number of working days.
   • Result: the result date will be displayed.

3. To save the current calculation record, click Save. The record will appear in the table.

Keyboard shortcuts:

• Ctrl + q: quit
• d: toggle dark mode
• s: save to history
• r: remove a record
• c: clear all history

Use the Python API

You can programmatically calculate working days using the cnworkdays.calculate_working_date() function.

Example usage

from datetime import date
from cnworkdays import calculate_working_date

# Calculate using a string date (YYYYMMDD format)
target_working_date = calculate_working_date("20240607", 1)  # Returns: 2024-06-11

# Calculate using a string date (YYYY-MM-DD format)
target_working_date = calculate_working_date("2024-06-08", 0)  # Returns: 2024-06-11

# Calculate using a date object
start_date = date(2024, 5, 13)
target_working_date = calculate_working_date(start_date, -1)  # Returns: 2024-05-11

API reference

calculate_working_date(start_date, num_days)

Parameters

• start_date (Union[str, datetime, date]): the reference date for calculations.
• num_days (int): the number of working days to calculate.
  • Positive values add working days.
  • Negative values subtract working days.
  • Zero returns the next working day if start_date is non-working.

Returns

• date: the calculated date, considering working days, holidays, and compensatory working days.

Exceptions

• ValueError: for invalid start dates or calculated dates outside the valid range.

Changelog

[2025.1] - 2024-12-22

• Introduce a terminal interface for cnworkdays workcalc, built with Textual.
• Add a Python API with the cnworkdays.calculate_working_date() function.
• Improve error handling for invalid inputs.

[2025.0] - 2024-11-25

• Extend date calculation support for cnworkdays workcalc through December 31, 2025.
• Fix the issue that cnworkdays holiparse fails to parse CY25 announcement.

[2024.1] - 2024-11-25

• Enhance browser application with more descriptive page titles for better user experience.
• Fix the issue that workcalc gets stuck when negative days are provided.

[2024.0] - 2024-11-13

• Launch cnworkdays CLI with two main commands:

  • holiparse: generate data for annual public holidays and compensatory working days based on notifications from the General Office of the State Council.
  • workcalc: calculate the date after or before a specified number of working days, accounting for official public holidays and compensatory working days in China.

• Add support for date calculations spanning from January 1, 2018, to December 31, 2024.