Skip to main content

Python Japanese holidays library based on static data published by Cabinet Office, Government of Japan

Project description


Python Japanese holidays library based on static data published by Cabinet Office, Government of Japan

PyPI License        PyPI Downloads      PyPI Version        PyPI Python Versions

flake8 and pytest   Publish to PyPI     Publish to DockerHub RPM and DEB         CodeQL

Important notices

  • This python-shukujitsu package covers only holidays in Japan from 1955 to 2024; will expand to holidays in 2025 in February 2024.
  • This python-shukujitsu package has ZERO relation to the Government of Japan - NEVER EVER assume any authorization as this is just a personal project.
  • The signature key 8A124CD64688ABCC was expired Mon Nov 21 11:31:15 2022 UTC; please file an issue if you hit troubles around DEB/RPM packages due to the expiry.


pip3 install python-shukujitsu


Play the dict-like object.

import shukujitsu

jp_holidays = shukujitsu.Japan()
# or:
# jp_holidays = shukujitsu.JP()
# or:
# jp_holidays = shukujitsu.CountryHoliday('JP')

from datetime import date

date(2020, 7, 24) in jp_holidays  # True
date(2019, 7, 24) in jp_holidays  # False

# The dict-like object also accepts misc. date(time)-like strings
# and int/float representing a Unix timestamp
'2014-01-01' in jp_holidays  # True
'1/1/2014' in jp_holidays    # True
1388597445 in jp_holidays    # True

jp_holidays.get('2014-01-01')  # "元日"

jp_holidays['2014-01-01': '2014-01-03']  # [date(2014, 1, 1)]

Command-Line interface

shukujitsu command is bundled.

$ shukujitsu --help  # or python3 -m shukujitsu --help
usage: shukujitsu [-h] [-i] [-n] [-V] [DATE ...]

Select Japanese holidays from 1955 to 2024

positional arguments:
  DATE                date to be examined

  -h, --help          show this help message and exit
  -i, --invert-match  select non-holidays
  -n, --holiday-name  output holiday name instead
  -V, --version       display version information and exit

With no DATE, read standard input. Exit status is 0 if any date is selected, 1 otherwise.

Pass any dates through command-line arguments or STDIN.

$ # With logical operators
$ shukujitsu 1/1/2020 && echo Holiday found || echo Holiday not found
Holiday found

$ # Select holidays
$ cat <<EOF | shukujitsu > holidays.txt
> 2020-05-02
> 2020-05-03
> 2020-05-04
> 2020-05-05
> 2020-05-06
> 2020-05-07

$ # Select holidays
$ shukujitsu 2020/7/22 2020/7/23 2020/7/24

$ # Output each holiday name
$ shukujitsu -n 2020/7/22 2020/7/23 2020/7/24

$ # Select non-holidays
$ shukujitsu -i 2020/7/22 2020/7/23 2020/7/24

Docker image

Docker Pulls Image Size

$ docker run -it sakuraiyouhei/shukujitsu --help

yum repository

$ sudo yum install -y curl
$ curl -fsSL | sudo tee /etc/yum.repos.d/python-shukujitsu.repo
$ sudo yum install -y python-shukujitsu
$ shukujitsu --help

Note: There is one known issue in the RPM package as of 2023-02-04;

apt repository

$ sudo apt install -y curl gpg
$ curl -fsSL | sudo apt-key add -
$ curl -fsSL | sudo tee /etc/apt/sources.list.d/python-shukujitsu.list
$ sudo apt update
$ sudo apt install -y python-shukujitsu
$ shukujitsu --help

Source data

This python-shukujitsu package bundles the following source data, which is distributed by the Government of Japan under the CC BY compatible conditions according to 内閣府ホームページ利用規約.

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

python-shukujitsu-2023.2.4.tar.gz (13.4 kB view hashes)

Uploaded Source

Built Distribution

python_shukujitsu-2023.2.4-py3-none-any.whl (44.1 kB view hashes)

Uploaded Python 3

Supported by

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