2026 Feb 01 – Forking Pyswisseph
I've been working with Pyswisseph, the Python extension to the Swiss Ephemeris, since I made my little taskbar ascendant clock back in July. Its lack of live documentation made developing Ephem difficult, but I made do with the C library's docs instead. I wasn't the only one struggling:
#83 from June 2025 got a response from the maintainer. Two months later, one of Swiss Ephemeris' creators and the webmaster of Astrodienst, Alois Treindl, opened #85. I had a stable (and documented!) version of Ephem released by September, so I turned my attention to Pyswisseph and found a few things.
Firstly, it has existing docs written in RST and a conf.py for a Sphinx site, but they hadn't been updated with Pyswisseph's most recent release, 2.10.3.2 from June 2023. The last commit to docs/ was in 2021, and Sphinx has had five major version releases since then. Per the GitHub issues and what I could find in Swiss Ephemeris' groups.io, the docs were hosted and available at least as recently as April 2025.
Secondly, even with these docs down, many outstanding open issues from before last year were about installation and basic Python environment management, some so old they're about Python 3.12 (granted, pyswisseph==2.10.3.2 requires python>=3.5). The Pyswisseph docs are largely conceptual, astronomical articles more in the spirit of the Swiss Ephemeris general documentation, plus an API reference generated from docstrings with sphinx-autodoc. Nothing quite addresses the unique collision of domain expertise, e.g. astrologers and astronomers, and the technical learning curve of handling a low-level library.
I waffled a bit. Sure, I've been a user of open source programs and libraries for some time, but most of these have huge user bases and proportionate contributors. I wouldn't have reached this level of tech literacy with documentation. Even though I experienced firsthand that one could use an undocumented language wrapper, I told myself surely other people could work like that, too. But from April to October is six months offline; April to now makes 10.
I opened #86 Fix #85: Documentation Overhaul (MyST/Diataxis Redesign) in early October and marked it Ready for Review after a week's work of half setting up Sphinx and GitHub Actions, and half technical writing.
I've been writing about astrology for the public on-and-off since 2019, so this was the easy part. I found Diataxis well-suited to something like a library that I knew would be used by people who know both more and less than me about the domain. I'll be first to admit a lot of Hellenistic revival led by my generation enables imprecision about math and astronomy, but that doesn't mean I need to integrate asteroids and ISS debris into my practice, you know? But I'm happy to explain Python dependencies because I learned to set up my own dev environments much more recently, and I'm comfortable explaining more intermediate astrological concepts to my occasional clients. (My practice is really like, unsuccessful marketing for people to learn astrology themselves.)
Besides GitHub, I emailed the maintainer, Stan Marquis, at his publicly listed address three times. Alois suggested LinkedIn, but that required premium. Under #88 Maintainer status that I opened in November, I received a Swiss phone number and Lausanne address, but I live in the States and would find cold-calling incredibly bizarre from my own countrymen, and generally believe no pull request can be urgent enough for such a thing. This was also the time I distrohopped to Void Linux, itself a cautionary tale about open source maintenance. Per Michael Aldridge's account and out of empathy—I, too, have on occasion disappeared from my own life—I err on the side of giving Stan space, and leaving my PR open in case he returns and appreciates modernized docs.
I shipped pysweph starting from 2.10.3.3 to PyPI at the end of January. While my initial goal was just to get the existing wrapper documented, I'm more anxious about maintaining something I didn't write, and about some editorial choices on Pyswisseph's part that diverge from Swiss Ephemeris, such as:
- Multiple buried, non-fatal string errors that inform the user about, more often than not, missing ephemeris files. I exposed string errors in four functions in 2.10.3.3 and it broke the test suite.
- The
swe.houses()family returning a 12-item tuple index 0 to 11 for the house cusps where Swiss Ephemeris returns a 13-item array with an empty index 0. I'm so Python-pilled I didn't think this was a problem, but again: this is a domain where cusps[0] = 1st house and cusps[9] = 10th house becomes illogical.
My C experience before this is QMK keymaps, so I'm learning CFFI on an orphan branch at a slower pace. I wrapped 13 functions in one afternoon, with some gorgeous new docstrings cross-referenced with the Swiss Ephemeris programmers' interface docs. I'll probably ship the CFFI rewrite as pysweph 1.0.0 and break from Swiss Ephemeris' version numbers while documenting which upstream version it wraps, e.g. pysweph==1.0.0 wraps swisseph==2.10.03.