{"id":44089037,"url":"https://github.com/theriftlab/immanuel-python","last_synced_at":"2026-04-19T01:16:00.356Z","repository":{"id":167996447,"uuid":"643619033","full_name":"theriftlab/immanuel-python","owner":"theriftlab","description":"Quickly produce both human-readable and JSON-formatted astrology chart data based on the Swiss Ephemeris and astro.com.","archived":false,"fork":false,"pushed_at":"2026-04-12T01:01:20.000Z","size":9398,"stargazers_count":108,"open_issues_count":0,"forks_count":26,"subscribers_count":14,"default_branch":"master","last_synced_at":"2026-04-12T03:06:33.438Z","etag":null,"topics":["astrodienst","astrology","astrology-api","astrology-calculator","pyswisseph","python","swisseph","swissephemeris"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/theriftlab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-05-21T18:25:20.000Z","updated_at":"2026-04-12T01:01:28.000Z","dependencies_parsed_at":"2023-10-17T07:31:53.631Z","dependency_job_id":"60d2b49a-492c-4f31-90d4-e823ff1417a9","html_url":"https://github.com/theriftlab/immanuel-python","commit_stats":null,"previous_names":["theriftlab/immanuel-python"],"tags_count":33,"template":false,"template_full_name":null,"purl":"pkg:github/theriftlab/immanuel-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theriftlab%2Fimmanuel-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theriftlab%2Fimmanuel-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theriftlab%2Fimmanuel-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theriftlab%2Fimmanuel-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theriftlab","download_url":"https://codeload.github.com/theriftlab/immanuel-python/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theriftlab%2Fimmanuel-python/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31990761,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"ssl_error","status_checked_at":"2026-04-18T20:23:29.375Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["astrodienst","astrology","astrology-api","astrology-calculator","pyswisseph","python","swisseph","swissephemeris"],"created_at":"2026-02-08T10:40:40.358Z","updated_at":"2026-04-19T01:16:00.341Z","avatar_url":"https://github.com/theriftlab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# \u003cp align=\"center\"\u003e\u003cimg src=\"https://github.com/theriftlab/immanuel-python/assets/370745/b834a4b1-9558-410f-8cbd-94018a9e2f1d\"\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://img.shields.io/pypi/v/immanuel\"\u003e\n    \u003cimg src=\"https://img.shields.io/python/required-version-toml?tomlFilePath=https://raw.githubusercontent.com/theriftlab/immanuel-python/master/pyproject.toml\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/issues/theriftlab/immanuel-python\"\u003e\n    \u003cimg src=\"https://img.shields.io/pepy/dt/immanuel\"\u003e\n\u003c/p\u003e\n\nImmanuel is a Python \u003e= 3.10 package to painlessly provide your application with simple yet detailed chart-centric astrology data for planets, points, signs, houses, aspects, weightings, etc. all based on the [Swiss Ephemeris](https://github.com/astrorigin/pyswisseph). Extra calculations, notably secondary progressions and dignity scores, are modeled on those of [astro.com](https://astro.com) and [Astro Gold](https://www.astrogold.io).\n\nData for natal charts, solar returns, progressions, and composites are available, as well as the ability to point the aspects from any one chart instance to the planets in another, creating a flexible method to build synastries.\n\nSimply pass in a date and coordinates to one of the available chart classes, and the returned instance will contain all data necessary to construct a full astrological chart. A serializer is bundled to easily output all data as JSON, or it can simply be printed out as human-readable text.\n\n## Translations\n\nImmanuel's output is currently available in the following locales / languages:\n\n* **en_US:** (default) US English\n* **pt_BR:** Brazilian Portuguese\n* **es_ES:** Spanish\n* **de_DE:** German\n\nSee [here](https://github.com/theriftlab/immanuel-python/tree/v1.5.4/docs/5-settings.md#locale) for details on how to switch. The documentation itself is not currently available in other translations. To contribute in-software translations, see [here](https://github.com/theriftlab/immanuel-python/tree/v1.5.4/docs/7-contributions.md).\n\n## Documentation\n\nFull documentation is available [here](https://github.com/theriftlab/immanuel-python/tree/v1.5.4/docs/0-contents.md), or follow the Quick Start below to see how to quickly generate a natal chart.\n\n## Quick Start\n\nYou can get started with full natal chart data in minutes. Simply install Immanuel:\n\n```bash\npip install immanuel\n```\n\nOnce you've imported Immanuel's chart classes into your application, you will need to hand them a person or event. This is made easy with the Subject class, which takes a date and geographical coordinates. The date can be an ISO-formatted string or a Python datetime instance, and coordinates can be strings or decimals.\n\n```python\nfrom immanuel import charts\n\n\nnative = charts.Subject(\n        date_time='2000-01-01 10:00',\n        latitude='32n43',\n        longitude='117w09',\n    )\n\n# or, alternatively...\n\nfrom datetime import datetime\n\nnative = charts.Subject(\n        date_time=datetime(2000, 1, 1, 10, 0, 0),\n        latitude=32.71667,\n        longitude=-117.15,\n    )\n\n# and then...\n\nnatal = charts.Natal(native)\n\nfor object in natal.objects.values():\n    print(object)\n```\n\nThis will output all the chart objects (planets, points, asteroids etc.) in this format:\n\n```\nSun 10°37'26\" in Capricorn, 11th House\nMoon 16°19'29\" in Scorpio, 8th House\nMercury 02°16'43\" in Capricorn, 10th House\nVenus 01°52'05\" in Sagittarius, 9th House\nMars 28°09'26\" in Aquarius, 12th House\nJupiter 25°15'48\" in Aries, 2nd House\nSaturn 10°23'27\" in Taurus, 2nd House, Retrograde\nUranus 14°49'19\" in Aquarius, 12th House\nNeptune 03°12'07\" in Aquarius, 12th House\nPluto 11°27'49\" in Sagittarius, 9th House\n...\n```\n\nAdd asteroid Ceres into the mix:\n\n```python\nfrom immanuel import charts\nfrom immanuel.const import chart\nfrom immanuel.setup import settings\n\n\nnative = charts.Subject(\n        date_time='2000-01-01 10:00',\n        latitude='32n43',\n        longitude='117w09'\n    )\n\nsettings.objects.append(chart.CERES)\nnatal = charts.Natal(native)\n\nfor object in natal.objects.values():\n    print(object)\n```\n\nNow you will see this appended to the list:\n\n```\nCeres 04°30'28\" in Libra, 7th House\n```\n\nMore on the settings \u0026 constants in the full documentation - for now, we can see much more data by serializing the chart's `objects` property to JSON like this:\n\n```python\nimport json\n\nfrom immanuel.classes.serialize import ToJSON\nfrom immanuel import charts\n\n\nnative = charts.Subject(\n        date_time='2000-01-01 10:00',\n        latitude='32n43',\n        longitude='117w09'\n    )\n\nnatal = charts.Natal(native)\n\nprint(json.dumps(natal.objects, cls=ToJSON, indent=4))\n```\n\nWhich will output each of the chart's objects in this format:\n\n```json\n{\n    \"index\": 4000001,\n    \"name\": \"Sun\",\n    \"type\": {\n        \"index\": 4000000,\n        \"name\": \"Planet\"\n    },\n    \"latitude\": {\n        \"raw\": 0.0002259471008556382,\n        \"formatted\": \"00\\u00b000'01\\\"\",\n        \"direction\": \"+\",\n        \"degrees\": 0,\n        \"minutes\": 0,\n        \"seconds\": 1\n    },\n    \"longitude\": {\n        \"raw\": 280.6237802656368,\n        \"formatted\": \"280\\u00b037'26\\\"\",\n        \"direction\": \"+\",\n        \"degrees\": 280,\n        \"minutes\": 37,\n        \"seconds\": 26\n    },\n    \"sign_longitude\": {\n        \"raw\": 10.62378026563681,\n        \"formatted\": \"10\\u00b037'26\\\"\",\n        \"direction\": \"+\",\n        \"degrees\": 10,\n        \"minutes\": 37,\n        \"seconds\": 26\n    },\n    \"sign\": {\n        \"number\": 10,\n        \"name\": \"Capricorn\",\n        \"element\": \"Earth\",\n        \"modality\": \"Cardinal\"\n    },\n    \"decan\": {\n        \"number\": 2,\n        \"name\": \"2nd Decan\"\n    },\n    \"house\": {\n        \"index\": 2000011,\n        \"number\": 11,\n        \"name\": \"11th House\"\n    },\n    \"distance\": 0.9833259257690341,\n    \"speed\": 1.0194579691359147,\n    \"movement\": {\n        \"direct\": true,\n        \"stationary\": false,\n        \"retrograde\": false,\n        \"formatted\": \"Direct\"\n    },\n    \"declination\": {\n        \"raw\": -23.01236501586868,\n        \"formatted\": \"-23\\u00b000'45\\\"\",\n        \"direction\": \"-\",\n        \"degrees\": 23,\n        \"minutes\": 0,\n        \"seconds\": 45\n    },\n    \"out_of_bounds\": false,\n    \"in_sect\": true,\n    \"dignities\": {\n        \"ruler\": false,\n        \"exalted\": false,\n        \"triplicity_ruler\": false,\n        \"term_ruler\": false,\n        \"face_ruler\": false,\n        \"mutual_reception_ruler\": false,\n        \"mutual_reception_exalted\": false,\n        \"mutual_reception_triplicity_ruler\": true,\n        \"mutual_reception_term_ruler\": false,\n        \"mutual_reception_face_ruler\": false,\n        \"detriment\": false,\n        \"fall\": false,\n        \"peregrine\": false,\n        \"formatted\": [\n            \"Triplicity Ruler by mutual reception\"\n        ]\n    },\n    \"score\": 3\n}\n```\n\nNote that the entire chart can also be serialized to JSON, eg.:\n\n```python\nprint(json.dumps(natal, cls=ToJSON, indent=4))\n```\n\n## Chart Types\n\nCurrently Immanuel supports the following chart types:\n\n* Natal\n* Solar return\n* Progressed\n* Composite\n* Transits\n\nSynastry is also available with an extra step - all chart classes allow an instance of another chart class to be passed as an argument, which will then calculate the main chart's aspects in relation to the passed chart. This way synastry (and transit) charts can be generated with great flexibility.\n\n## Returned Chart Data\n\nThe various chart types return their own sets of data, but you can expect to receive at least the following in all of them:\n\n* Chart date\n* Chart coordinates\n* House system\n* Chart shape type (eg. bowl, splash etc.)\n* Whether the chart is diurnal (ie. daytime)\n* Moon phase\n* All chart objects (eg. planets, asteroids, primary angles etc.) and their positions \u0026 dignities if applicable\n* Houses\n* Aspects\n* Weightings (ie. which objects are in which elements / modalities etc.)\n\nAll properties are available in both human-readable and JSON format as demonstrated above.\n\n## Calculations\n\nImmanuel offers the same three methods for MC progression as astro.com, and will produce the same progressed date, sidereal time, and house positions.\n\nPlanetary dignity scores are based on those of Astro Gold, although these are somewhat flexible via the settings.\n\n## Settings\n\nThe full documentation covers settings in detail, but much of the output can be customized. The settings class allows you to specify and personalize:\n\n* Locale / language\n* The house system to use\n* What data each chart returns\n* What planets, points, asteroid etc. to include\n* Details of the aspect calculations\n* Which dignities to use and their scores\n* The progression method to use for secondary progressions\n* ...and much more.\n\n## Tests\n\nTests are available via pytest. If you have cloned the repo, simply run pytest from the root:\n\n```bash\npython -m pytest\n```\n\n## License\n\nThis program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the [GNU Affero General Public License](LICENSE.md) for more details.\n\n## Credits\n\nImmanuel is forever indebted to the pioneering work of Alois Treindl and Dieter Koch at Astrodienst, and to João Ventura for the incredibly detailed [flatlib](https://github.com/flatangle/flatlib) which first inspired the development of this package.\n\nA big thank-you goes to Nathan Octavio who suggested translations, and who translated Immanuel into both Brazilian Portuguese and Spanish. Thanks also goes to [@cosmosandapi](https://github.com/comosandapi) who provided the German translation.\n\n## Contact\n\nPlease post any issues, feature requests, PRs etc. on GitHub. For anything else email robert@theriftlab.com.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheriftlab%2Fimmanuel-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheriftlab%2Fimmanuel-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheriftlab%2Fimmanuel-python/lists"}