{"id":4969,"library":"kerykeion","title":"Kerykeion","description":"Kerykeion is an actively developed Python library for astrological calculations, generating detailed natal charts, house positions, planetary aspects, and high-quality SVG charts. It features a data-driven approach, integrates seamlessly with LLM and AI applications for contextual astrological data, and maintains a frequent release cadence with new features in minor versions and major architectural shifts planned for new major versions.","status":"active","version":"5.12.7","language":"en","source_language":"en","source_url":"https://github.com/g-battaglia/kerykeion","tags":["astrology","horoscope","natal-chart","svg","pydantic","data-driven","ai-llm","celestial-mechanics"],"install":[{"cmd":"pip install kerykeion","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Data modeling and validation","package":"pydantic","optional":false},{"reason":"Timezone handling","package":"pytz","optional":false},{"reason":"SVG chart generation","package":"svgwrite","optional":false},{"reason":"Fetching external data (e.g., GeoNames)","package":"requests","optional":false},{"reason":"Numerical operations","package":"numpy","optional":false},{"reason":"Astronomical calculations","package":"skyfield","optional":false},{"reason":"Astronomical calculations","package":"ephem","optional":false}],"imports":[{"note":"The AstrologicalSubject class was deprecated and replaced by AstrologicalSubjectFactory in v5.0.0.","wrong":"from kerykeion import AstrologicalSubject","symbol":"AstrologicalSubjectFactory","correct":"from kerykeion import AstrologicalSubjectFactory"},{"note":"Part of the new v5.0.0 architecture for separating data computation.","symbol":"ChartDataFactory","correct":"from kerykeion import ChartDataFactory"},{"note":"KerykeionChartSVG was deprecated and replaced by ChartDrawer in v5.0.0 for chart rendering.","wrong":"from kerykeion import KerykeionChartSVG","symbol":"ChartDrawer","correct":"from kerykeion import ChartDrawer"}],"quickstart":{"code":"import os\nfrom kerykeion import AstrologicalSubjectFactory, ChartDataFactory, ChartDrawer\n\n# Set GeoNames username for online calculations. Required for fetching city/nation coordinates.\n# Register for a free account at geonames.org if you don't have one.\nos.environ['KERYKEION_GEONAMES_USERNAME'] = os.environ.get('KERYKEION_GEONAMES_USERNAME', 'demo')\n\n# 1. Create an AstrologicalSubjectFactory instance\nsubject_factory = AstrologicalSubjectFactory(\n    name='John Doe',\n    year=1990, month=5, day=15,\n    hour=10, minute=30,\n    city='London', nation='UK',\n    gender='male'\n)\n\n# 2. Compute chart data using ChartDataFactory\nchart_data_factory = ChartDataFactory(subject_factory)\nnatal_chart_data = chart_data_factory.make_natal_chart_data()\n\n# 3. Draw the chart using ChartDrawer\nchart_drawer = ChartDrawer(natal_chart_data)\n\n# Generate and save the SVG chart\noutput_filename = 'john_doe_natal_chart.svg'\nchart_drawer.save_svg(output_filename, style='classic')\n\nprint(f\"Natal chart saved to {output_filename}\")\n\n# You can also get data as a Pydantic model\n# print(natal_chart_data.model_dump_json(indent=2))","lang":"python","description":"This quickstart demonstrates how to generate a natal chart using Kerykeion's v5+ factory-based architecture. It involves creating an `AstrologicalSubjectFactory` for subject details, using `ChartDataFactory` to compute astrological data, and finally `ChartDrawer` to render the SVG chart. For online location data, a GeoNames username is required, which can be set via an environment variable. The example saves a classic-style SVG chart file."},"warnings":[{"fix":"Migrate to the new factory-based API: use `AstrologicalSubjectFactory` to define subjects, `ChartDataFactory` to compute data, and `ChartDrawer` for rendering. Refer to the official migration guide for v4 to v5.","message":"Version 5.0.0 introduced a complete architectural redesign, replacing legacy classes (e.g., `AstrologicalSubject`, `KerykeionChartSVG`, `NatalAspects`, `SynastryAspects`) with a new factory-based system (`AstrologicalSubjectFactory`, `ChartDataFactory`, `ChartDrawer`). Direct imports and usage of old classes will break.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Avoid using classes from `kerykeion.backword`. Update your code to use the new factory-based API directly to ensure future compatibility.","message":"A backward compatibility layer (`kerykeion.backword`) was introduced in v5.0.0 to ease migration from v4 by providing wrappers for old classes. However, this layer is deprecated and will be removed entirely in v6.0.0.","severity":"deprecated","affected_versions":"5.0.0 - 5.x.x (will be removed in v6.0.0)"},{"fix":"Register for a free account at geonames.org and set the `KERYKEION_GEONAMES_USERNAME` environment variable with your username.","message":"For features requiring online location lookups (e.g., city/nation to coordinates), Kerykeion relies on GeoNames. A valid GeoNames username must be provided either through the `KERYKEION_GEONAMES_USERNAME` environment variable or directly as a parameter to the factory.","severity":"gotcha","affected_versions":"All versions (where online features are used)"},{"fix":"Review the AGPL-3.0 license implications for your project. If open-sourcing your project is not feasible, consider using a compliant third-party API (like AstrologerAPI) that utilizes Kerykeion under a different commercial license.","message":"Kerykeion is licensed under the AGPL-3.0. This open-source license may require projects integrating Kerykeion's functionalities to also be open-sourced under a compatible license. Consult the LICENSE file for details.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Explore `ChartDrawer` and `save_svg` parameters for advanced customization and compatibility options. Consult the documentation for specific version capabilities.","message":"Chart drawing offers 'classic' (default) and 'modern' styles, configurable via `ChartDrawer(style=...)` or `save_svg(style=...)`. Newer features like `show_aspect_icons` and `remove_css_variables` (for improved SVG compatibility) are optional parameters.","severity":"gotcha","affected_versions":">=5.11.0"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}