<h1 align="center">Kerykeion</h1>
<div align="center">
<img src="https://img.shields.io/github/stars/g-battaglia/kerykeion.svg?logo=github" alt="stars">
<img src="https://img.shields.io/github/forks/g-battaglia/kerykeion.svg?logo=github" alt="forks">
</div>
<div align="center">
<img src="https://static.pepy.tech/badge/kerykeion/month" alt="PyPI Downloads">
<img src="https://static.pepy.tech/badge/kerykeion/week" alt="PyPI Downloads">
<img src="https://img.shields.io/github/contributors/g-battaglia/kerykeion?color=blue&logo=github" alt="contributors">
<img src="https://img.shields.io/pypi/v/kerykeion?label=pypi%20package" alt="Package version">
<img src="https://img.shields.io/pypi/pyversions/kerykeion.svg" alt="Supported Python versions">
</div>
<p align="center">⭐ Like this project? Star it on GitHub and help it grow! ⭐</p>
Kerykeion is a Python library for astrology. It computes planetary and house positions, detects aspects, and generates SVG charts—including birth, synastry, transit, and composite charts. You can also customize which planets to include in your calculations.
The main goal of this project is to offer a clean, data-driven approach to astrology, making it accessible and programmable.
Kerykeion also integrates seamlessly with LLM and AI applications.
Here is an example of a birthchart:
**Web API**
---
If you want to use Kerykeion in a web application, you can try the dedicated web API:
**[AstrologerAPI](https://rapidapi.com/gbattaglia/api/astrologer/pricing)**
It is [open source](https://github.com/g-battaglia/Astrologer-API) and directly supports this project.
**Donate**
--
Maintaining this project requires substantial time and effort. The Astrologer API alone cannot cover the costs of full-time development. If you find Kerykeion valuable and would like to support further development, please consider donating:
[](https://ko-fi.com/kerykeion)
## Table of Contents
- [Installation](#installation)
- [Basic Usage](#basic-usage)
- [Generate a SVG Chart](#generate-a-svg-chart)
- [Birth Chart](#birth-chart)
- [External Birth Chart](#external-birth-chart)
- [Synastry Chart](#synastry-chart)
- [Transit Chart](#transit-chart)
- [Composite Chart](#composite-chart)
- [Wheel Only Charts](#wheel-only-charts)
- [Birth Chart](#birth-chart-1)
- [Wheel Only Birth Chart (External)](#wheel-only-birth-chart-external)
- [Synastry Chart](#synastry-chart-1)
- [Change the Output Directory](#change-the-output-directory)
- [Change Language](#change-language)
- [Minified SVG](#minified-svg)
- [SVG without CSS Variables](#svg-without-css-variables)
- [Grid Only SVG](#grid-only-svg)
- [Report](#report)
- [Example: Retrieving Aspects](#example-retrieving-aspects)
- [Ayanamsa (Sidereal Modes)](#ayanamsa-sidereal-modes)
- [House Systems](#house-systems)
- [Perspective Type](#perspective-type)
- [Themes](#themes)
- [Alternative Initialization](#alternative-initialization)
- [Lunar Nodes (Rahu \& Ketu)](#lunar-nodes-rahu--ketu)
- [JSON Support](#json-support)
- [Auto Generated Documentation](#auto-generated-documentation)
- [Development](#development)
- [Integrating Kerykeion into Your Project](#integrating-kerykeion-into-your-project)
- [License](#license)
- [Contributing](#contributing)
- [Citations](#citations)
## Installation
Kerykeion requires **Python 3.9** or higher.
```bash
pip3 install kerykeion
```
## Basic Usage
Below is a simple example illustrating the creation of an astrological subject and retrieving astrological details:
```python
from kerykeion import AstrologicalSubject
# Create an instance of the AstrologicalSubject class.
# Arguments: Name, year, month, day, hour, minutes, city, nation
kanye = AstrologicalSubject("Kanye", 1977, 6, 8, 8, 45, "Atlanta", "US")
# Retrieve information about the Sun:
kanye.sun
# > {'name': 'Sun', 'quality': 'Mutable', 'element': 'Air', 'sign': 'Gem', 'sign_num': 2, ...}
# Retrieve information about the first house:
kanye.first_house
# > {'name': 'First_House', 'quality': 'Cardinal', 'element': 'Water', 'sign': 'Can', ...}
# Retrieve the element of the Moon sign:
kanye.moon.element
# > 'Water'
```
**To avoid using GeoNames online, specify longitude, latitude, and timezone instead of city and nation:**
```python
kanye = AstrologicalSubject(
"Kanye", 1977, 6, 8, 8, 45,
lng=50,
lat=50,
tz_str="Europe/Rome",
city="Rome"
)
```
## Generate a SVG Chart
To generate a chart, use the `KerykeionChartSVG` class. You can create various types of charts, including birth, synastry, transit, and composite charts.
**Tip:**
The optimized way to open the generated SVG files is with a web browser (e.g., Chrome, Firefox).
To improve compatibility across different applications, you can use the `remove_css_variables` parameter when generating the SVG. This will inline all styles and eliminate CSS variables, resulting in an SVG that is more broadly supported.
### Birth Chart
```python
from kerykeion import AstrologicalSubject, KerykeionChartSVG
john = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
birth_chart_svg = KerykeionChartSVG(john)
birth_chart_svg.makeSVG()
```
```python
birth_chart_svg.makeSVG()
```
The SVG file will be saved in the home directory.
### External Birth Chart
```python
from kerykeion import AstrologicalSubject, KerykeionChartSVG
birth_chart = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
birth_chart_svg = KerykeionChartSVG(birth_chart, chart_type="ExternalNatal")
birth_chart_svg.makeSVG()
```
### Synastry Chart
```python
from kerykeion import AstrologicalSubject, KerykeionChartSVG
first = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
second = AstrologicalSubject("Paul McCartney", 1942, 6, 18, 15, 30, "Liverpool", "GB")
synastry_chart = KerykeionChartSVG(first, "Synastry", second)
synastry_chart.makeSVG()
```
### Transit Chart
```python
from kerykeion import AstrologicalSubject
transit = AstrologicalSubject("Transit", 2025, 6, 8, 8, 45, "Atlanta", "US")
subject = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
transit_chart = KerykeionChartSVG(subject, "Transit", transit)
transit_chart.makeSVG()
```
### Composite Chart
```python
from kerykeion import CompositeSubjectFactory, AstrologicalSubject, KerykeionChartSVG
angelina = AstrologicalSubject("Angelina Jolie", 1975, 6, 4, 9, 9, "Los Angeles", "US", lng=-118.15, lat=34.03, tz_str="America/Los_Angeles")
brad = AstrologicalSubject("Brad Pitt", 1963, 12, 18, 6, 31, "Shawnee", "US", lng=-96.56, lat=35.20, tz_str="America/Chicago")
factory = CompositeSubjectFactory(angelina, brad)
composite_model = factory.get_midpoint_composite_subject_model()
composite_chart = KerykeionChartSVG(composite_model, "Composite")
composite_chart.makeSVG()
```
## Wheel Only Charts
For *all* the charts, you can generate a wheel-only chart by using the method `makeWheelOnlySVG()`:
### Birth Chart
```python
from kerykeion import AstrologicalSubject, KerykeionChartSVG
birth_chart = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
birth_chart_svg = KerykeionChartSVG(birth_chart)
birth_chart_svg.makeWheelOnlySVG()
```
### Wheel Only Birth Chart (External)
```python
from kerykeion import AstrologicalSubject, KerykeionChartSVG
birth_chart = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
birth_chart_svg = KerykeionChartSVG(birth_chart, chart_type="ExternalNatal")
birth_chart_svg.makeWheelOnlySVG(
wheel_only=True,
wheel_only_external=True
)
```
### Synastry Chart
```python
from kerykeion import AstrologicalSubject, KerykeionChartSVG
first = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
second = AstrologicalSubject("Paul McCartney", 1942, 6, 18, 15, 30, "Liverpool", "GB")
synastry_chart = KerykeionChartSVG(
first, "Synastry", second
)
synastry_chart.makeWheelOnlySVG()
```
### Change the Output Directory
To save the SVG file in a custom location, specify `new_output_directory`:
```python
from kerykeion import AstrologicalSubject, KerykeionChartSVG
first = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
second = AstrologicalSubject("Paul McCartney", 1942, 6, 18, 15, 30, "Liverpool", "GB")
synastry_chart = KerykeionChartSVG(
first, "Synastry", second,
new_output_directory="."
)
synastry_chart.makeSVG()
```
### Change Language
You can switch chart language by passing `chart_language` to the `KerykeionChartSVG` class:
```python
from kerykeion import AstrologicalSubject, KerykeionChartSVG
first = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
birth_chart_svg = KerykeionChartSVG(
birth_chart,
chart_language="IT" # Change to Italian
)
birth_chart_svg.makeSVG()
```
More details [here](https://www.kerykeion.net/docs/chart-language).
The available languages are:
- EN (English)
- FR (French)
- PT (Portuguese)
- ES (Spanish)
- TR (Turkish)
- RU (Russian)
- IT (Italian)
- CN (Chinese)
- DE (German)
### Minified SVG
To generate a minified SVG, set `minify_svg=True` in the `makeSVG()` method:
```python
from kerykeion import AstrologicalSubject, KerykeionChartSVG
first = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
birth_chart_svg = KerykeionChartSVG(birth_chart)
birth_chart_svg.makeSVG(
minify=True
)
```
### SVG without CSS Variables
To generate an SVG without CSS variables, set `remove_css_variables=True` in the `makeSVG()` method:
```python
from kerykeion import AstrologicalSubject, KerykeionChartSVG
first = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
birth_chart_svg = KerykeionChartSVG(birth_chart)
birth_chart_svg.makeSVG(
remove_css_variables=True
)
```
This will inline all styles and eliminate CSS variables, resulting in an SVG that is more broadly supported.
### Grid Only SVG
It's possible to generate a grid-only SVG, useful for creating a custom layout. To do this, use the `makeGridOnlySVG()` method:
```python
from kerykeion import AstrologicalSubject, KerykeionChartSVG
birth_chart = AstrologicalSubject("John Lennon - Aspect Grid Dark Synastry", 1977, 6, 8, 8, 45, "Atlanta", "US")
aspect_grid_dark_synastry_chart = KerykeionChartSVG(aspect_grid_dark_synastry_subject, "Synastry", second, theme="dark")
aspect_grid_dark_synastry_chart.makeAspectGridOnlySVG()
```
## Report
```python
from kerykeion import Report, AstrologicalSubject
kanye = AstrologicalSubject("Kanye", 1977, 6, 8, 8, 45, "Atlanta", "US")
report = Report(kanye)
report.print_report()
```
Returns:
```txt
+- Kerykeion report for Kanye -+
+----------+------+-------------+-----------+----------+
| Date | Time | Location | Longitude | Latitude |
+----------+------+-------------+-----------+----------+
| 8/6/1977 | 8:45 | Atlanta, US | -84.38798 | 33.749 |
+----------+------+-------------+-----------+----------+
+-----------------+------+-------+------+----------------+
| Planet | Sign | Pos. | Ret. | House |
+-----------------+------+-------+------+----------------+
| Sun | Gem | 17.6 | - | Twelfth_House |
| Moon | Pis | 16.43 | - | Ninth_House |
| Mercury | Tau | 26.29 | - | Eleventh_House |
| Venus | Tau | 2.03 | - | Tenth_House |
| Mars | Tau | 1.79 | - | Tenth_House |
| Jupiter | Gem | 14.61 | - | Eleventh_House |
| Saturn | Leo | 12.8 | - | Second_House |
| Uranus | Sco | 8.27 | R | Fourth_House |
| Neptune | Sag | 14.69 | R | Fifth_House |
| Pluto | Lib | 11.45 | R | Fourth_House |
| Mean_Node | Lib | 21.49 | R | Fourth_House |
| True_Node | Lib | 22.82 | R | Fourth_House |
| Mean_South_Node | Ari | 21.49 | R | Tenth_House |
| True_South_Node | Ari | 22.82 | R | Tenth_House |
| Chiron | Tau | 4.17 | - | Tenth_House |
+-----------------+------+-------+------+----------------+
+----------------+------+----------+
| House | Sign | Position |
+----------------+------+----------+
| First_House | Can | 18.0 |
| Second_House | Leo | 9.51 |
| Third_House | Vir | 4.02 |
| Fourth_House | Lib | 3.98 |
| Fifth_House | Sco | 9.39 |
| Sixth_House | Sag | 15.68 |
| Seventh_House | Cap | 18.0 |
| Eighth_House | Aqu | 9.51 |
| Ninth_House | Pis | 4.02 |
| Tenth_House | Ari | 3.98 |
| Eleventh_House | Tau | 9.39 |
| Twelfth_House | Gem | 15.68 |
+----------------+------+----------+
To export to a file:
```bash
python3 your_script_name.py > file.txt
```
## Example: Retrieving Aspects
```python
from kerykeion import SynastryAspects, AstrologicalSubject
first = AstrologicalSubject("Jack", 1990, 6, 15, 15, 15, "Roma", "IT")
second = AstrologicalSubject("Jane", 1991, 10, 25, 21, 0, "Roma", "IT")
name = SynastryAspects(first, second)
aspect_list = name.get_relevant_aspects()
print(aspect_list[0])
#> {'p1_name': 'Sun', 'p1_abs_pos': 84.17867971515636, 'p2_name': 'Sun', 'p2_abs_pos': 211.90472999502984, 'aspect': 'trine', 'orbit': 7.726050279873476, 'aspect_degrees': 120, 'color': '#36d100', 'aid': 6, 'diff': 127.72605027987348, 'p1': 0, 'p2': 0}
```
## Ayanamsa (Sidereal Modes)
By default, the zodiac type is **Tropical**. To use **Sidereal**, specify the sidereal mode:
```python
johnny = AstrologicalSubject(
"Johnny Depp", 1963, 6, 9, 0, 0,
"Owensboro", "US",
zodiac_type="Sidereal",
sidereal_mode="LAHIRI"
)
```
More examples [here](https://www.kerykeion.net/docs//sidereal-modes/).
Full list of supported sidereal modes [here](https://www.kerykeion.net/pydocs/kerykeion/kr_types/kr_literals.html#SiderealMode).
## House Systems
By default, houses are calculated using **Placidus**. Configure a different house system as follows:
```python
johnny = AstrologicalSubject(
"Johnny Depp", 1963, 6, 9, 0, 0,
"Owensboro", "US",
houses_system="M"
)
```
More examples [here](https://www.kerykeion.net/docs//houses-systems/).
Full list of supported house systems [here](https://www.kerykeion.net/pydocs/kerykeion/kr_types/kr_literals.html#HousesSystem).
So far all the available houses system in the Swiss Ephemeris are supported but the Gauquelin Sectors.
## Perspective Type
By default, Kerykeion uses the **Apparent Geocentric** perspective (the most standard in astrology). Other perspectives (e.g., **Heliocentric**) can be set this way:
```python
johnny = AstrologicalSubject(
"Johnny Depp", 1963, 6, 9, 0, 0,
"Owensboro", "US",
perspective_type="Heliocentric"
)
```
More examples [here](https://www.kerykeion.net/docs//perspective-type/).
Full list of supported perspective types [here](https://www.kerykeion.net/pydocs/kerykeion/kr_types/kr_literals.html#PerspectiveType).
## Themes
Kerykeion provides several chart themes:
- **Classic** (default)
- **Dark**
- **Dark High Contrast**
- **Light**
Each theme offers a distinct visual style, allowing you to choose the one that best suits your preferences or presentation needs. If you prefer more control over the appearance, you can opt not to set any theme, making it easier to customize the chart by overriding the default CSS variables. For more detailed instructions on how to apply themes, check the [documentation](https://www.kerykeion.net/docs/theming)
Here's an example of how to set the theme:
```python
from kerykeion import AstrologicalSubject, KerykeionChartSVG
dark_theme_subject = AstrologicalSubject("John Lennon - Dark Theme", 1940, 10, 9, 18, 30, "Liverpool", "GB")
dark_theme_natal_chart = KerykeionChartSVG(dark_high_contrast_theme_subject, theme="dark_high_contrast")
dark_theme_natal_chart.makeSVG()
```
## Alternative Initialization
Create an `AstrologicalSubject` from a UTC ISO 8601 string:
```python
subject = AstrologicalSubject.get_from_iso_utc_time(
"Johnny Depp", "1963-06-09T05:00:00Z", "Owensboro", "US"
)
```
If you set `online=True`, provide a `geonames_username` to allow city-based geolocation:
```python
from kerykeion.astrological_subject import AstrologicalSubject
subject = AstrologicalSubject.get_from_iso_utc_time(
"Johnny Depp", "1963-06-09T05:00:00Z", "Owensboro", "US", online=True
)
```
## Lunar Nodes (Rahu & Ketu)
Kerykeion supports both **True** and **Mean** Lunar Nodes:
- **True North Lunar Node**: `"true_node"` (name kept without "north" for backward compatibility).
- **True South Lunar Node**: `"true_south_node"`.
- **Mean North Lunar Node**: `"mean_node"` (name kept without "north" for backward compatibility).
- **Mean South Lunar Node**: `"mean_south_node"`.
In instances of the AstrologicalSubject class, all of them are active by default.
In instances of the classes used to generate aspects and SVG charts, only the mean nodes are active. To activate the true nodes, you need to pass the `active_points` parameter to the `KerykeionChartSVG` class.
Example:
```python
from kerykeion import AstrologicalSubject, KerykeionChartSVG
subject = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
chart = KerykeionChartSVG(
subject,
active_points=[
"Sun",
"Moon",
"Mercury",
"Venus",
"Mars",
"Jupiter",
"Saturn",
"Uranus",
"Neptune",
"Pluto",
"Mean_Node",
"Mean_South_Node",
"True_Node", # Activates True North Node
"True_South_Node", # Activates True South Node
"Ascendant",
"Medium_Coeli",
"Descendant",
"Imum_Coeli"
]
)
chart.makeSVG()
```
## JSON Support
You can serialize the astrological subject (the base data used throughout the library) to JSON:
```python
from kerykeion import AstrologicalSubject
johnny = AstrologicalSubject("Johnny Depp", 1963, 6, 9, 0, 0, "Owensboro", "US")
print(johnny.json(dump=False, indent=2))
```
## Auto Generated Documentation
You can find auto-generated documentation [here](https://www.kerykeion.net/pydocs/kerykeion.html). Most classes and functions include docstrings.
## Development
Clone the repository or download the ZIP via the GitHub interface.
## Integrating Kerykeion into Your Project
If you would like to incorporate Kerykeion’s astrological features into your application, please reach out via [email](mailto:kerykeion.astrology@gmail.com?subject=Integration%20Request). Whether you need custom features, support, or specialized consulting, I am happy to discuss potential collaborations.
## License
This project is covered under the AGPL-3.0 License. For detailed information, please see the [LICENSE](LICENSE) file. If you have questions, feel free to contact me at [kerykeion.astrology@gmail.com](mailto:kerykeion.astrology@gmail.com?subject=Kerykeion).
As a rule of thumb, if you use this library in a project, you should open-source that project under a compatible license. Alternatively, if you wish to keep your source closed, consider using the [AstrologerAPI](https://rapidapi.com/gbattaglia/api/astrologer/), which is AGPL-3.0 compliant and also helps support the project.
Since the AstrologerAPI is an external third-party service, using it does *not* require your code to be open-source.
## Contributing
Contributions are welcome! Feel free to submit pull requests or report issues.
## Citations
If using Kerykeion in published or academic work, please cite as follows:
```
Battaglia, G. (2025). Kerykeion: A Python Library for Astrological Calculations and Chart Generation.
https://github.com/g-battaglia/kerykeion
```
Raw data
{
"_id": null,
"home_page": "https://www.kerykeion.net/",
"name": "kerykeion",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "astrology, ephemeris, astrology library, birtchart, svg, zodiac, zodiac-sing, astronomical-algorithms, synastry, astrology-calculator",
"author": "Giacomo Battaglia",
"author_email": "kerykeion.astrology@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/1b/49/f8b955eb3459e49844265e394561e8428a698eb4c9d41bd6b8966fae7998/kerykeion-4.26.2.tar.gz",
"platform": null,
"description": "<h1 align=\"center\">Kerykeion</h1>\n\n<div align=\"center\">\n <img src=\"https://img.shields.io/github/stars/g-battaglia/kerykeion.svg?logo=github\" alt=\"stars\">\n <img src=\"https://img.shields.io/github/forks/g-battaglia/kerykeion.svg?logo=github\" alt=\"forks\">\n</div>\n<div align=\"center\">\n <img src=\"https://static.pepy.tech/badge/kerykeion/month\" alt=\"PyPI Downloads\">\n <img src=\"https://static.pepy.tech/badge/kerykeion/week\" alt=\"PyPI Downloads\">\n <img src=\"https://img.shields.io/github/contributors/g-battaglia/kerykeion?color=blue&logo=github\" alt=\"contributors\">\n <img src=\"https://img.shields.io/pypi/v/kerykeion?label=pypi%20package\" alt=\"Package version\">\n <img src=\"https://img.shields.io/pypi/pyversions/kerykeion.svg\" alt=\"Supported Python versions\">\n</div>\n<p align=\"center\">\u2b50 Like this project? Star it on GitHub and help it grow! \u2b50</p>\n \n\nKerykeion is a Python library for astrology. It computes planetary and house positions, detects aspects, and generates SVG charts\u2014including birth, synastry, transit, and composite charts. You can also customize which planets to include in your calculations.\n\nThe main goal of this project is to offer a clean, data-driven approach to astrology, making it accessible and programmable.\n\nKerykeion also integrates seamlessly with LLM and AI applications. \n\nHere is an example of a birthchart:\n\n\n\n**Web API**\n---\n\nIf you want to use Kerykeion in a web application, you can try the dedicated web API:\n\n**[AstrologerAPI](https://rapidapi.com/gbattaglia/api/astrologer/pricing)**\n\nIt is [open source](https://github.com/g-battaglia/Astrologer-API) and directly supports this project.\n\n**Donate**\n--\n\nMaintaining this project requires substantial time and effort. The Astrologer API alone cannot cover the costs of full-time development. If you find Kerykeion valuable and would like to support further development, please consider donating:\n\n[](https://ko-fi.com/kerykeion)\n\n\n## Table of Contents\n- [Installation](#installation)\n- [Basic Usage](#basic-usage)\n- [Generate a SVG Chart](#generate-a-svg-chart)\n - [Birth Chart](#birth-chart)\n - [External Birth Chart](#external-birth-chart)\n - [Synastry Chart](#synastry-chart)\n - [Transit Chart](#transit-chart)\n - [Composite Chart](#composite-chart)\n- [Wheel Only Charts](#wheel-only-charts)\n - [Birth Chart](#birth-chart-1)\n - [Wheel Only Birth Chart (External)](#wheel-only-birth-chart-external)\n - [Synastry Chart](#synastry-chart-1)\n - [Change the Output Directory](#change-the-output-directory)\n - [Change Language](#change-language)\n - [Minified SVG](#minified-svg)\n - [SVG without CSS Variables](#svg-without-css-variables)\n - [Grid Only SVG](#grid-only-svg)\n- [Report](#report)\n- [Example: Retrieving Aspects](#example-retrieving-aspects)\n- [Ayanamsa (Sidereal Modes)](#ayanamsa-sidereal-modes)\n- [House Systems](#house-systems)\n- [Perspective Type](#perspective-type)\n- [Themes](#themes)\n- [Alternative Initialization](#alternative-initialization)\n- [Lunar Nodes (Rahu \\& Ketu)](#lunar-nodes-rahu--ketu)\n- [JSON Support](#json-support)\n- [Auto Generated Documentation](#auto-generated-documentation)\n- [Development](#development)\n- [Integrating Kerykeion into Your Project](#integrating-kerykeion-into-your-project)\n- [License](#license)\n- [Contributing](#contributing)\n- [Citations](#citations)\n\n## Installation\n\nKerykeion requires **Python 3.9** or higher.\n\n```bash\npip3 install kerykeion\n```\n\n## Basic Usage\n\nBelow is a simple example illustrating the creation of an astrological subject and retrieving astrological details:\n\n```python\nfrom kerykeion import AstrologicalSubject\n\n# Create an instance of the AstrologicalSubject class.\n# Arguments: Name, year, month, day, hour, minutes, city, nation\nkanye = AstrologicalSubject(\"Kanye\", 1977, 6, 8, 8, 45, \"Atlanta\", \"US\")\n\n# Retrieve information about the Sun:\nkanye.sun\n# > {'name': 'Sun', 'quality': 'Mutable', 'element': 'Air', 'sign': 'Gem', 'sign_num': 2, ...}\n\n# Retrieve information about the first house:\nkanye.first_house\n# > {'name': 'First_House', 'quality': 'Cardinal', 'element': 'Water', 'sign': 'Can', ...}\n\n# Retrieve the element of the Moon sign:\nkanye.moon.element\n# > 'Water'\n```\n\n**To avoid using GeoNames online, specify longitude, latitude, and timezone instead of city and nation:**\n\n```python\nkanye = AstrologicalSubject(\n \"Kanye\", 1977, 6, 8, 8, 45,\n lng=50,\n lat=50,\n tz_str=\"Europe/Rome\",\n city=\"Rome\"\n)\n```\n\n## Generate a SVG Chart\n\nTo generate a chart, use the `KerykeionChartSVG` class. You can create various types of charts, including birth, synastry, transit, and composite charts.\n\n**Tip:** \nThe optimized way to open the generated SVG files is with a web browser (e.g., Chrome, Firefox).\nTo improve compatibility across different applications, you can use the `remove_css_variables` parameter when generating the SVG. This will inline all styles and eliminate CSS variables, resulting in an SVG that is more broadly supported.\n\n### Birth Chart\n\n```python\nfrom kerykeion import AstrologicalSubject, KerykeionChartSVG\n\njohn = AstrologicalSubject(\"John Lennon\", 1940, 10, 9, 18, 30, \"Liverpool\", \"GB\")\nbirth_chart_svg = KerykeionChartSVG(john)\nbirth_chart_svg.makeSVG()\n```\n\n```python\nbirth_chart_svg.makeSVG()\n```\n\nThe SVG file will be saved in the home directory.\n\n\n### External Birth Chart\n\n```python\nfrom kerykeion import AstrologicalSubject, KerykeionChartSVG\nbirth_chart = AstrologicalSubject(\"John Lennon\", 1940, 10, 9, 18, 30, \"Liverpool\", \"GB\")\nbirth_chart_svg = KerykeionChartSVG(birth_chart, chart_type=\"ExternalNatal\")\nbirth_chart_svg.makeSVG()\n```\n\n\n### Synastry Chart\n\n```python\nfrom kerykeion import AstrologicalSubject, KerykeionChartSVG\n\nfirst = AstrologicalSubject(\"John Lennon\", 1940, 10, 9, 18, 30, \"Liverpool\", \"GB\")\nsecond = AstrologicalSubject(\"Paul McCartney\", 1942, 6, 18, 15, 30, \"Liverpool\", \"GB\")\n\nsynastry_chart = KerykeionChartSVG(first, \"Synastry\", second)\nsynastry_chart.makeSVG()\n```\n\n\n\n\n### Transit Chart\n\n```python\nfrom kerykeion import AstrologicalSubject\n\ntransit = AstrologicalSubject(\"Transit\", 2025, 6, 8, 8, 45, \"Atlanta\", \"US\")\nsubject = AstrologicalSubject(\"John Lennon\", 1940, 10, 9, 18, 30, \"Liverpool\", \"GB\")\n\ntransit_chart = KerykeionChartSVG(subject, \"Transit\", transit)\ntransit_chart.makeSVG()\n```\n\n\n\n### Composite Chart\n\n```python\nfrom kerykeion import CompositeSubjectFactory, AstrologicalSubject, KerykeionChartSVG\n\nangelina = AstrologicalSubject(\"Angelina Jolie\", 1975, 6, 4, 9, 9, \"Los Angeles\", \"US\", lng=-118.15, lat=34.03, tz_str=\"America/Los_Angeles\")\n\nbrad = AstrologicalSubject(\"Brad Pitt\", 1963, 12, 18, 6, 31, \"Shawnee\", \"US\", lng=-96.56, lat=35.20, tz_str=\"America/Chicago\")\n\nfactory = CompositeSubjectFactory(angelina, brad)\ncomposite_model = factory.get_midpoint_composite_subject_model()\n\ncomposite_chart = KerykeionChartSVG(composite_model, \"Composite\")\ncomposite_chart.makeSVG()\n```\n\n\n\n## Wheel Only Charts\n\nFor *all* the charts, you can generate a wheel-only chart by using the method `makeWheelOnlySVG()`:\n\n### Birth Chart\n```python\nfrom kerykeion import AstrologicalSubject, KerykeionChartSVG\n\nbirth_chart = AstrologicalSubject(\"John Lennon\", 1940, 10, 9, 18, 30, \"Liverpool\", \"GB\")\nbirth_chart_svg = KerykeionChartSVG(birth_chart)\nbirth_chart_svg.makeWheelOnlySVG()\n```\n\n\n### Wheel Only Birth Chart (External)\n\n```python\nfrom kerykeion import AstrologicalSubject, KerykeionChartSVG\nbirth_chart = AstrologicalSubject(\"John Lennon\", 1940, 10, 9, 18, 30, \"Liverpool\", \"GB\")\nbirth_chart_svg = KerykeionChartSVG(birth_chart, chart_type=\"ExternalNatal\")\nbirth_chart_svg.makeWheelOnlySVG(\n wheel_only=True,\n wheel_only_external=True\n)\n```\n\n\n\n### Synastry Chart\n```python\nfrom kerykeion import AstrologicalSubject, KerykeionChartSVG\nfirst = AstrologicalSubject(\"John Lennon\", 1940, 10, 9, 18, 30, \"Liverpool\", \"GB\")\nsecond = AstrologicalSubject(\"Paul McCartney\", 1942, 6, 18, 15, 30, \"Liverpool\", \"GB\")\nsynastry_chart = KerykeionChartSVG(\n first, \"Synastry\", second\n)\nsynastry_chart.makeWheelOnlySVG()\n```\n\n\n\n### Change the Output Directory\n\nTo save the SVG file in a custom location, specify `new_output_directory`:\n\n```python\nfrom kerykeion import AstrologicalSubject, KerykeionChartSVG\n\nfirst = AstrologicalSubject(\"John Lennon\", 1940, 10, 9, 18, 30, \"Liverpool\", \"GB\")\nsecond = AstrologicalSubject(\"Paul McCartney\", 1942, 6, 18, 15, 30, \"Liverpool\", \"GB\")\n\nsynastry_chart = KerykeionChartSVG(\n first, \"Synastry\", second,\n new_output_directory=\".\"\n)\nsynastry_chart.makeSVG()\n```\n\n### Change Language\n\nYou can switch chart language by passing `chart_language` to the `KerykeionChartSVG` class:\n\n```python\nfrom kerykeion import AstrologicalSubject, KerykeionChartSVG\n\nfirst = AstrologicalSubject(\"John Lennon\", 1940, 10, 9, 18, 30, \"Liverpool\", \"GB\")\nbirth_chart_svg = KerykeionChartSVG(\n birth_chart,\n chart_language=\"IT\" # Change to Italian\n)\nbirth_chart_svg.makeSVG()\n```\n\nMore details [here](https://www.kerykeion.net/docs/chart-language).\n\nThe available languages are:\n- EN (English)\n- FR (French)\n- PT (Portuguese)\n- ES (Spanish)\n- TR (Turkish)\n- RU (Russian)\n- IT (Italian)\n- CN (Chinese)\n- DE (German)\n\n\n### Minified SVG\nTo generate a minified SVG, set `minify_svg=True` in the `makeSVG()` method:\n\n```python\nfrom kerykeion import AstrologicalSubject, KerykeionChartSVG\nfirst = AstrologicalSubject(\"John Lennon\", 1940, 10, 9, 18, 30, \"Liverpool\", \"GB\")\nbirth_chart_svg = KerykeionChartSVG(birth_chart)\nbirth_chart_svg.makeSVG(\n minify=True\n)\n```\n\n### SVG without CSS Variables\nTo generate an SVG without CSS variables, set `remove_css_variables=True` in the `makeSVG()` method:\n\n```python\nfrom kerykeion import AstrologicalSubject, KerykeionChartSVG\n\nfirst = AstrologicalSubject(\"John Lennon\", 1940, 10, 9, 18, 30, \"Liverpool\", \"GB\")\nbirth_chart_svg = KerykeionChartSVG(birth_chart)\nbirth_chart_svg.makeSVG(\n remove_css_variables=True\n)\n```\nThis will inline all styles and eliminate CSS variables, resulting in an SVG that is more broadly supported.\n\n\n### Grid Only SVG\n\nIt's possible to generate a grid-only SVG, useful for creating a custom layout. To do this, use the `makeGridOnlySVG()` method:\n\n```python\nfrom kerykeion import AstrologicalSubject, KerykeionChartSVG\nbirth_chart = AstrologicalSubject(\"John Lennon - Aspect Grid Dark Synastry\", 1977, 6, 8, 8, 45, \"Atlanta\", \"US\")\naspect_grid_dark_synastry_chart = KerykeionChartSVG(aspect_grid_dark_synastry_subject, \"Synastry\", second, theme=\"dark\")\naspect_grid_dark_synastry_chart.makeAspectGridOnlySVG()\n```\n\n\n## Report\n\n```python\nfrom kerykeion import Report, AstrologicalSubject\n\nkanye = AstrologicalSubject(\"Kanye\", 1977, 6, 8, 8, 45, \"Atlanta\", \"US\")\nreport = Report(kanye)\nreport.print_report()\n```\n\nReturns:\n\n```txt\n+- Kerykeion report for Kanye -+\n+----------+------+-------------+-----------+----------+\n| Date | Time | Location | Longitude | Latitude |\n+----------+------+-------------+-----------+----------+\n| 8/6/1977 | 8:45 | Atlanta, US | -84.38798 | 33.749 |\n+----------+------+-------------+-----------+----------+\n+-----------------+------+-------+------+----------------+\n| Planet | Sign | Pos. | Ret. | House |\n+-----------------+------+-------+------+----------------+\n| Sun | Gem | 17.6 | - | Twelfth_House |\n| Moon | Pis | 16.43 | - | Ninth_House |\n| Mercury | Tau | 26.29 | - | Eleventh_House |\n| Venus | Tau | 2.03 | - | Tenth_House |\n| Mars | Tau | 1.79 | - | Tenth_House |\n| Jupiter | Gem | 14.61 | - | Eleventh_House |\n| Saturn | Leo | 12.8 | - | Second_House |\n| Uranus | Sco | 8.27 | R | Fourth_House |\n| Neptune | Sag | 14.69 | R | Fifth_House |\n| Pluto | Lib | 11.45 | R | Fourth_House |\n| Mean_Node | Lib | 21.49 | R | Fourth_House |\n| True_Node | Lib | 22.82 | R | Fourth_House |\n| Mean_South_Node | Ari | 21.49 | R | Tenth_House |\n| True_South_Node | Ari | 22.82 | R | Tenth_House |\n| Chiron | Tau | 4.17 | - | Tenth_House |\n+-----------------+------+-------+------+----------------+\n+----------------+------+----------+\n| House | Sign | Position |\n+----------------+------+----------+\n| First_House | Can | 18.0 |\n| Second_House | Leo | 9.51 |\n| Third_House | Vir | 4.02 |\n| Fourth_House | Lib | 3.98 |\n| Fifth_House | Sco | 9.39 |\n| Sixth_House | Sag | 15.68 |\n| Seventh_House | Cap | 18.0 |\n| Eighth_House | Aqu | 9.51 |\n| Ninth_House | Pis | 4.02 |\n| Tenth_House | Ari | 3.98 |\n| Eleventh_House | Tau | 9.39 |\n| Twelfth_House | Gem | 15.68 |\n+----------------+------+----------+\n\nTo export to a file:\n\n```bash\npython3 your_script_name.py > file.txt\n```\n\n## Example: Retrieving Aspects\n\n```python\nfrom kerykeion import SynastryAspects, AstrologicalSubject\n\nfirst = AstrologicalSubject(\"Jack\", 1990, 6, 15, 15, 15, \"Roma\", \"IT\")\nsecond = AstrologicalSubject(\"Jane\", 1991, 10, 25, 21, 0, \"Roma\", \"IT\")\n\nname = SynastryAspects(first, second)\naspect_list = name.get_relevant_aspects()\nprint(aspect_list[0])\n#> {'p1_name': 'Sun', 'p1_abs_pos': 84.17867971515636, 'p2_name': 'Sun', 'p2_abs_pos': 211.90472999502984, 'aspect': 'trine', 'orbit': 7.726050279873476, 'aspect_degrees': 120, 'color': '#36d100', 'aid': 6, 'diff': 127.72605027987348, 'p1': 0, 'p2': 0}\n\n```\n\n## Ayanamsa (Sidereal Modes)\n\nBy default, the zodiac type is **Tropical**. To use **Sidereal**, specify the sidereal mode:\n\n```python\njohnny = AstrologicalSubject(\n \"Johnny Depp\", 1963, 6, 9, 0, 0,\n \"Owensboro\", \"US\",\n zodiac_type=\"Sidereal\",\n sidereal_mode=\"LAHIRI\"\n)\n```\n\nMore examples [here](https://www.kerykeion.net/docs//sidereal-modes/).\n\nFull list of supported sidereal modes [here](https://www.kerykeion.net/pydocs/kerykeion/kr_types/kr_literals.html#SiderealMode).\n\n## House Systems\n\nBy default, houses are calculated using **Placidus**. Configure a different house system as follows:\n\n```python\njohnny = AstrologicalSubject(\n \"Johnny Depp\", 1963, 6, 9, 0, 0,\n \"Owensboro\", \"US\",\n houses_system=\"M\"\n)\n```\n\nMore examples [here](https://www.kerykeion.net/docs//houses-systems/).\n\nFull list of supported house systems [here](https://www.kerykeion.net/pydocs/kerykeion/kr_types/kr_literals.html#HousesSystem).\n\nSo far all the available houses system in the Swiss Ephemeris are supported but the Gauquelin Sectors.\n\n## Perspective Type\n\nBy default, Kerykeion uses the **Apparent Geocentric** perspective (the most standard in astrology). Other perspectives (e.g., **Heliocentric**) can be set this way:\n\n```python\njohnny = AstrologicalSubject(\n \"Johnny Depp\", 1963, 6, 9, 0, 0,\n \"Owensboro\", \"US\",\n perspective_type=\"Heliocentric\"\n)\n```\n\nMore examples [here](https://www.kerykeion.net/docs//perspective-type/).\n\nFull list of supported perspective types [here](https://www.kerykeion.net/pydocs/kerykeion/kr_types/kr_literals.html#PerspectiveType).\n\n## Themes\n\nKerykeion provides several chart themes:\n\n- **Classic** (default)\n- **Dark**\n- **Dark High Contrast**\n- **Light**\n \nEach theme offers a distinct visual style, allowing you to choose the one that best suits your preferences or presentation needs. If you prefer more control over the appearance, you can opt not to set any theme, making it easier to customize the chart by overriding the default CSS variables. For more detailed instructions on how to apply themes, check the [documentation](https://www.kerykeion.net/docs/theming)\n\nHere's an example of how to set the theme:\n\n```python\nfrom kerykeion import AstrologicalSubject, KerykeionChartSVG\n\ndark_theme_subject = AstrologicalSubject(\"John Lennon - Dark Theme\", 1940, 10, 9, 18, 30, \"Liverpool\", \"GB\")\ndark_theme_natal_chart = KerykeionChartSVG(dark_high_contrast_theme_subject, theme=\"dark_high_contrast\")\ndark_theme_natal_chart.makeSVG()\n```\n\n\n\n## Alternative Initialization\n\nCreate an `AstrologicalSubject` from a UTC ISO 8601 string:\n\n```python\nsubject = AstrologicalSubject.get_from_iso_utc_time(\n \"Johnny Depp\", \"1963-06-09T05:00:00Z\", \"Owensboro\", \"US\"\n)\n```\n\nIf you set `online=True`, provide a `geonames_username` to allow city-based geolocation:\n\n```python\nfrom kerykeion.astrological_subject import AstrologicalSubject\n\nsubject = AstrologicalSubject.get_from_iso_utc_time(\n \"Johnny Depp\", \"1963-06-09T05:00:00Z\", \"Owensboro\", \"US\", online=True\n)\n```\n\n## Lunar Nodes (Rahu & Ketu)\n\nKerykeion supports both **True** and **Mean** Lunar Nodes:\n\n- **True North Lunar Node**: `\"true_node\"` (name kept without \"north\" for backward compatibility).\n- **True South Lunar Node**: `\"true_south_node\"`.\n- **Mean North Lunar Node**: `\"mean_node\"` (name kept without \"north\" for backward compatibility).\n- **Mean South Lunar Node**: `\"mean_south_node\"`.\n\nIn instances of the AstrologicalSubject class, all of them are active by default.\n\nIn instances of the classes used to generate aspects and SVG charts, only the mean nodes are active. To activate the true nodes, you need to pass the `active_points` parameter to the `KerykeionChartSVG` class.\n\nExample:\n\n```python\nfrom kerykeion import AstrologicalSubject, KerykeionChartSVG\n\nsubject = AstrologicalSubject(\"John Lennon\", 1940, 10, 9, 18, 30, \"Liverpool\", \"GB\")\n\nchart = KerykeionChartSVG(\n subject,\n active_points=[\n \"Sun\", \n \"Moon\", \n \"Mercury\", \n \"Venus\", \n \"Mars\", \n \"Jupiter\", \n \"Saturn\",\n \"Uranus\", \n \"Neptune\", \n \"Pluto\", \n \"Mean_Node\", \n \"Mean_South_Node\", \n \"True_Node\", # Activates True North Node \n \"True_South_Node\", # Activates True South Node\n \"Ascendant\",\n \"Medium_Coeli\", \n \"Descendant\", \n \"Imum_Coeli\"\n ]\n)\nchart.makeSVG()\n```\n\n## JSON Support\n\nYou can serialize the astrological subject (the base data used throughout the library) to JSON:\n\n```python\nfrom kerykeion import AstrologicalSubject\n\njohnny = AstrologicalSubject(\"Johnny Depp\", 1963, 6, 9, 0, 0, \"Owensboro\", \"US\")\n\nprint(johnny.json(dump=False, indent=2))\n```\n\n## Auto Generated Documentation\n\nYou can find auto-generated documentation [here](https://www.kerykeion.net/pydocs/kerykeion.html). Most classes and functions include docstrings.\n\n## Development\n\nClone the repository or download the ZIP via the GitHub interface.\n\n## Integrating Kerykeion into Your Project\n\nIf you would like to incorporate Kerykeion\u2019s astrological features into your application, please reach out via [email](mailto:kerykeion.astrology@gmail.com?subject=Integration%20Request). Whether you need custom features, support, or specialized consulting, I am happy to discuss potential collaborations.\n\n## License\n\nThis project is covered under the AGPL-3.0 License. For detailed information, please see the [LICENSE](LICENSE) file. If you have questions, feel free to contact me at [kerykeion.astrology@gmail.com](mailto:kerykeion.astrology@gmail.com?subject=Kerykeion).\n\nAs a rule of thumb, if you use this library in a project, you should open-source that project under a compatible license. Alternatively, if you wish to keep your source closed, consider using the [AstrologerAPI](https://rapidapi.com/gbattaglia/api/astrologer/), which is AGPL-3.0 compliant and also helps support the project.\n\nSince the AstrologerAPI is an external third-party service, using it does *not* require your code to be open-source.\n\n## Contributing\n\nContributions are welcome! Feel free to submit pull requests or report issues.\n\n## Citations\n\nIf using Kerykeion in published or academic work, please cite as follows:\n\n```\nBattaglia, G. (2025). Kerykeion: A Python Library for Astrological Calculations and Chart Generation.\nhttps://github.com/g-battaglia/kerykeion\n```\n",
"bugtrack_url": null,
"license": "AGPL-3.0",
"summary": "A python library for astrology.",
"version": "4.26.2",
"project_urls": {
"Homepage": "https://www.kerykeion.net/",
"Repository": "https://github.com/g-battaglia/kerykeion"
},
"split_keywords": [
"astrology",
" ephemeris",
" astrology library",
" birtchart",
" svg",
" zodiac",
" zodiac-sing",
" astronomical-algorithms",
" synastry",
" astrology-calculator"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "84aecd2c87324056278b416a8da4ec94422af8933fe0ed5a0464e1e925b78fdb",
"md5": "98e6d59f1d90ff21bb52db91ea03b35b",
"sha256": "3444e2df2b62aa470f40e907aabc20993f6b8b4afb0599eb1272b61694d067db"
},
"downloads": -1,
"filename": "kerykeion-4.26.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "98e6d59f1d90ff21bb52db91ea03b35b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 396851,
"upload_time": "2025-04-27T21:44:05",
"upload_time_iso_8601": "2025-04-27T21:44:05.794104Z",
"url": "https://files.pythonhosted.org/packages/84/ae/cd2c87324056278b416a8da4ec94422af8933fe0ed5a0464e1e925b78fdb/kerykeion-4.26.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1b49f8b955eb3459e49844265e394561e8428a698eb4c9d41bd6b8966fae7998",
"md5": "0bc961c3f4bee40fdd320cca0f940c41",
"sha256": "7f094118883c6b8d524e362c965caf5842aecb7739fd08387939c39e62d89276"
},
"downloads": -1,
"filename": "kerykeion-4.26.2.tar.gz",
"has_sig": false,
"md5_digest": "0bc961c3f4bee40fdd320cca0f940c41",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 379104,
"upload_time": "2025-04-27T21:44:09",
"upload_time_iso_8601": "2025-04-27T21:44:09.695087Z",
"url": "https://files.pythonhosted.org/packages/1b/49/f8b955eb3459e49844265e394561e8428a698eb4c9d41bd6b8966fae7998/kerykeion-4.26.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-04-27 21:44:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "g-battaglia",
"github_project": "kerykeion",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "kerykeion"
}
JSON
