sxtwl

What it is and what it does

sxtwl is a Python wrapper around a C++ calendar library that implements astronomical calendar calculations for Chinese lunar and solar calendars. It provides bidirectional conversion between Gregorian dates and lunar dates, computes heavenly stems and earthly branches (used in Chinese astrology and traditional timekeeping), identifies the 24 solar terms (seasonal markers in traditional Chinese astronomy), and retrieves associated metadata like zodiac animals, constellations, and day-of-week information. The underlying C++ implementation supports a wide historical range (from BC 722 onwards) and runs on multiple platforms including Android, iOS, Windows, macOS, and Linux.

The package exposes its functionality through SWIG-generated Python bindings and requires no runtime dependencies beyond the pre-compiled binary wheels. It is primarily designed for applications that need accurate Chinese calendar calculations—such as scheduling tools, astrology apps, or cultural calendar systems—where the astronomical basis of the calculations matters more than a simple lookup table.

Use it for:

• Convert between Gregorian and lunar dates in Chinese calendar applications or scheduling systems.
• Calculate heavenly stems and earthly branches for Chinese astrology, fortune-telling, or traditional medicine timing.
• Identify solar terms (seasonal markers) for agricultural planning or traditional Chinese seasonal observances.
• Retrieve zodiac animal signs and other calendar metadata for cultural or astrological applications.
• Query lunar month lengths and leap months for calendar display or date validation in Chinese contexts.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Converts between solar (Gregorian) and lunar calendars, computes heavenly stems and earthly branches (干支), identifies solar terms (节气), and retrieves calendar metadata like zodiac signs and day-of-week information.

Yes, if you need accurate Chinese lunar calendar conversions and astronomical calculations. The package is stable (no known vulnerabilities), permissively licensed, and widely used. However, it is dormant—the last release was 2024-09-05 and the repository shows no recent commits—so do not expect bug fixes or new features. Verify that your Python version and platform are in the available wheel distributions before installing.

Install

sxtwl on PyPI

pip install sxtwl

uv add sxtwl

poetry add sxtwl

Installing sxtwl

Before you install

Medium install friction: the package distributes pre-built wheels across multiple platforms (macOS, Linux, Windows) for several Python versions, but has been dormant since its last release on 2024-09-05, with no recent maintenance activity.

License in practice

Licensed under BSD (permissive), which allows use in commercial and private projects with minimal restrictions, though you should retain the license notice.

Quickstart

pip install sxtwl

import sxtwl

# Convert from solar (Gregorian) date
day = sxtwl.fromSolar(2021, 11, 7)
print(day.getSolarYear(), day.getSolarMonth(), day.getSolarDay())

# Convert from lunar date
day = sxtwl.fromLunar(2020, 12, 1)
print(day.getLunarYear(), day.getLunarMonth(), day.getLunarDay())

Verify before relying

• Which Python versions are supported (wheels shown for 2.7, 3.10, 3.11, 3.12 but full version coverage unclear)
• Current accuracy of constellation calculation (documentation notes a potential bug)
• Whether the four-pillar reverse-lookup feature is fully functional (documentation notes potential bugs)
• Exact historical date range where calculations are reliable beyond BC 722

Package facts

Evidence: sxtwl-2.0.7-cp27-cp27m-macosx_12_0_x86_64.whl; sxtwl-2.0.7-cp27-cp27m-manylinux_2_5_i686.manylinux1_i686.whl; sxtwl-2.0.7-cp27-cp27m-manylinux_2_5_x86_64.manylinux1_x86_64.whl; sxtwl-2.0.7-cp27-cp27mu-manylinux_2_5_i686.manylinux1_i686.whl; sxtwl-2.0.7-cp27-cp27mu-manylinux_2_5_x86_64.manylinux1_x86_64.whl; sxtwl-2.0.7-cp27-cp27m-win32.whl; sxtwl-2.0.7-cp27-cp27m-win_amd64.whl; sxtwl-2.0.7-cp310-cp310-macosx_12_0_x86_64.whl; sxtwl-2.0.7-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl; sxtwl-2.0.7-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl; sxtwl-2.0.7-cp310-cp310-win32.whl; sxtwl-2.0.7-cp310-cp310-win_amd64.whl; sxtwl-2.0.7-cp311-cp311-macosx_12_0_x86_64.whl; sxtwl-2.0.7-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl; sxtwl-2.0.7-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl; sxtwl-2.0.7-cp311-cp311-win32.whl; sxtwl-2.0.7-cp311-cp311-win_amd64.whl; sxtwl-2.0.7-cp312-cp312-macosx_12_0_x86_64.whl; sxtwl-2.0.7-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl; sxtwl-2.0.7-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl

Tags

More Utilities packages