fcalendar

Use fcalendar to identify time expressions in text and query Chinese public holiday schedules.
All commands output single-line JSON to stdout; errors go to stderr.

[!IMPORTANT]
Always invoke fcalendar as python3 -m fcalendar ... — this bypasses all PATH issues and works
regardless of virtual environments, system Python, or installation prefix. Never rely on the bare
fcalendar command being on PATH.

Quick Start

1. 1. Check if already installed (do this first — skip install if it succeeds):

   python3 -c "import fcalendar; print('fcalendar installed, version:', fcalendar.__version__)"
   

If this prints a version number, skip to step 3.

1. 2. Install (only if step 1 failed):

> [!NOTE]
> Package Source: The fcalendar package is available on PyPI at https://pypi.org/project/fcalendar/
>
> Source Code: You can review the source code at https://github.com/youngfreefjs/fcalendar
>
> Security: This package only performs local date/time parsing and does not access network resources or collect user data.

CODEBLOCK1

For enhanced security, consider installing in a virtual environment:
CODEBLOCK2

1. 3. Verify:

   python3 -m fcalendar --help
   

Confirm help output is shown. If this fails but step 1 succeeded, the package is installed but may not support -m invocation — fall back to the full binary path: CODEBLOCK4

1. 4. Get current date when needed: INLINECODE7

[!NOTE]
Invocation rule: In all commands below, replace fcalendar with python3 -m fcalendar.
Example: fcalendar query "明天" → INLINECODE11

Core Capabilities

1. Time Expression Recognition — query

Identifies and annotates time expressions in natural language, resolving them to exact dates.

Command:
CODEBLOCK5

Arguments:

Argument	Required	Description
INLINECODE13	yes	Natural language text containing time expressions
INLINECODE14

no | Reference date (YYYY-MM-DD). Defaults to system date |
| --lang | no | Language: zh or en. Defaults to auto-detect |

Output:
CODEBLOCK6

Examples:
CODEBLOCK7

Supported time expression types:

For a comprehensive list of all supported time expression types with detailed examples, see references/time-expressions.md.

Key categories include:

• - Relative days (明天、后天、tomorrow)
• Relative weeks (本周一、下周五、next Monday)
• Chinese holidays (春节、国庆节、清明节)
• Lunar festivals (元宵节、七夕、除夕)
• Western festivals (Christmas、Halloween、Valentine's Day)
• 24 solar terms (春分、冬至、立春)
• And many more...

---

2. Holiday Query — holiday

Queries public holidays and normal weekends within a specified time range. Excludes workdays-on-weekends (调休上班) to avoid confusion.

For detailed information about Chinese public holidays and solar terms, see references/holidays.md.

Command:
CODEBLOCK8

Arguments:

Argument	Required	Default	Description
INLINECODE19	no	INLINECODE20	Time range (see below)
INLINECODE21

no | system date | Reference date (YYYY-MM-DD) |

Supported scope values (Chinese and English both accepted):

Scope	Alias	Description
INLINECODE22	INLINECODE23, INLINECODE24	Next 180 days (default)
INLINECODE25

本周, 这周 | Mon–Sun of current week |
| next_week | 下周, 下一周 | Mon–Sun of next week |
| next_month | 下个月, 下一个月, 下月 | Full next calendar month |
| weeks=N | N周, 未来N周 | Next N weeks from today |
| months=N | N个月, 未来N个月 | Next N months from today |

N supports Chinese numerals: 一、两、三、四...十二, and Arabic numerals.

Output: JSON array, sorted by start date ascending.

CODEBLOCK9

Output fields:

Field	Type	Description
INLINECODE42	string	INLINECODE43 = Chinese public holiday; "weekend" = normal restful weekend
INLINECODE45

string | Holiday name (e.g. "春节", "周末") |
| start | string | Start date, ISO format (YYYY-MM-DD) |
| end | string | End date, ISO format (YYYY-MM-DD) |
| days | int | Number of days |

Note: Workdays-on-weekends (调休上班) are NOT included in the output. The list only shows days off.

Examples:

fcalendar holiday                          # next 180 days (default)
fcalendar holiday --scope this_week        # this week
fcalendar holiday --scope 本周             # same as above (Chinese)
fcalendar holiday --scope next_week        # next week
fcalendar holiday --scope next_month       # next full month
fcalendar holiday --scope weeks=3          # next 3 weeks
fcalendar holiday --scope 三周             # same as weeks=3 (Chinese numeral)
fcalendar holiday --scope months=2         # next 2 months
fcalendar holiday --scope 未来两个月       # same as months=2
fcalendar holiday --scope half_year --today 2026-09-01  # 180 days from Sep 1

---

Friendly Display Requirements

[!IMPORTANT]
Strict Output Rule: Always use the exact content returned by the fcalendar CLI.
Do NOT paraphrase, rewrite, supplement, or infer beyond what the CLI returns.
The result field (for query) and the JSON array (for holiday) are the single
source of truth. Present them as-is after formatting; never modify their semantic content.

• - General principle: output must be valid Markdown with clear structure.
• For query: display the result field directly as the annotated response. Do not display raw JSON to the user.
• For holiday:

- Group results by type: list holiday entries first, then weekend entries. - Use a Markdown table or bullet list to present each item. - Highlight key facts: name, date range, number of days. - If the result is empty, tell the user there are no holidays in that period.

Recommended output structure for holiday

CODEBLOCK11

Error handling

• - If the --scope value is invalid, the CLI exits with a non-zero code and prints an error to stderr. Inform the user of valid scope formats.
• Always get the current date with date +%Y-%m-%d before calling if real-time accuracy is required.