Report Module #

The ReportGenerator class generates concise, human-readable text reports (tables) from any Kerykeion data model. It is ideal for CLI output, debugging, or log files.

Supported Inputs #

AstrologicalSubjectModel: Basic birth/event data, celestial points, houses.
SingleChartDataModel: Natal, Composite, Returns (includes elements, aspects).
DualChartDataModel: Synastry, Transits (includes comparison tables).
MoonPhaseOverviewModel: Detailed lunar phase context produced by MoonPhaseDetailsFactory (includes moon summary, illumination, upcoming phases, eclipses, sun info, and location).

Usage #

Printing to Console #

The simplest way to use the generator is to print the report directly to stdout. This is useful for CLI applications or debugging.

from kerykeion import ReportGenerator, AstrologicalSubjectFactory

subject = AstrologicalSubjectFactory.from_birth_data("Alice", 1990, 6, 15, 12, 0, "London", "GB")
ReportGenerator(subject).print_report()

Example Output:

+------------------------------+
|         Birth Data           |
+------------------------------+
| Name    : Alice              |
| Date    : 1990-06-15         |
| Time    : 12:00              |
| Location: London, GB         |
+------------------------------+

+------------------------------------------+
|          Celestial Points                |
+------------------------------------------+
| Planet   | Sign | Position | House       |
+----------+------+----------+-------------+
| Sun      | Gem  |  23.81°  | 10th House  |
| Moon     | Pis  |   8.45°  |  7th House  |
| Mercury  | Can  |   5.12°  | 10th House  |
| ...                                      |
+------------------------------------------+

Generating a String #

Use generate_report() to return the string instead of printing it.

from kerykeion import ChartDataFactory

natal_data = ChartDataFactory.create_natal_chart_data(subject)
report_text = ReportGenerator(natal_data).generate_report(include_aspects=True)

with open("report.txt", "w") as f:
    f.write(report_text)

Synastry / Transit Report #

You can also generate reports from dual-chart data models:

subject_b = AstrologicalSubjectFactory.from_birth_data(
    "Bob", 1992, 8, 20, 14, 30,
    lng=-74.006, lat=40.7128, tz_str="America/New_York",
    online=False
)

synastry_data = ChartDataFactory.create_synastry_chart_data(subject, subject_b)
ReportGenerator(synastry_data).print_report(max_aspects=10)

The dual-chart report includes both subjects’ birth data, inter-chart aspects, and house comparison tables (if available).

Moon Phase Overview Report #

You can also generate a report from a MoonPhaseOverviewModel produced by the MoonPhaseDetailsFactory:

from kerykeion import (
    AstrologicalSubjectFactory,
    MoonPhaseDetailsFactory,
    ReportGenerator,
)

subject = AstrologicalSubjectFactory.from_birth_data(
    "Alice", 1990, 6, 15, 12, 0,
    lng=12.4964, lat=41.9028, tz_str="Europe/Rome",
    online=False,
)

overview = MoonPhaseDetailsFactory.from_subject(subject)
ReportGenerator(overview).print_report()

The moon phase overview report includes dedicated sections for Moon Summary, Illumination Details, Upcoming Phases, Next Lunar Eclipse, Sun Info, Next Solar Eclipse, and Location.

See the Moon Phase Details Factory documentation for full details on the data model.

Configuration #

Parameter	Type	Default	Description
`model`	`ChartDataModel`, `AstrologicalSubjectModel`, or `MoonPhaseOverviewModel`	Required	The data model to generate the report for.
`include_aspects`	`bool`	`True`	Include the Aspect table (default: `True`). Ignored for moon phase overview reports.
`max_aspects`	`int`	`None`	Limit the number of aspects shown (default: `None` = all). Ignored for moon phase overview reports.

Public API #

Method	Description
`generate_report(include_aspects=None, max_aspects=None) -> str`	Build the report content as a string.
`print_report(include_aspects=None, max_aspects=None) -> None`	Print the generated report to `stdout`.

Need this in production? Use the Astrologer API for hosted calculations, charts, and AI interpretations - no server setup required. Learn more →