How hoishing/natal works
Based on our analysis of the file tree and README, “Natal” is a Python library for generating astrological (natal and composite) charts in SVG format. The project’s purpose is to provide a highly configurable system for computing and rendering astrological data—and even generating statistical analysis and reports from that data—using pure Python. The system is designed as a library (with integrations in both scripts and interactive environments such as Jupyter) and includes comprehensive testing and documentation.
Main Components
• Data and Domain Model: The core “Data” object (see natal/data.py) represents all the astrological inputs (birth time, location, etc.) and computes positions of celestial bodies (planets, houses, aspects). Other domain objects are defined in modules such as natal/classes.py, natal/const.py, and natal/config.py.
• Chart Generation Module: The “Chart” module (natal/chart.py) takes one or two Data objects (for natal/transit, composite charts, etc.) and generates an SVG chart. It leverages the “tagit” library for SVG/HTML generation and may invoke utilities for SVG path cleanup (natal/svg_paths/clean_up.py).
• Statistics and Reporting: The “Stats” module (natal/stats.py) provides functionality to generate statistical reports (in Markdown or HTML) based on the astrological data. This is useful for the analysis and cross-referencing of aspects, houses, etc.
• Configuration Management: The natal/config.py (and related files) provide ways for users to override default settings, customize themes (light, dark, mono), control which celestial objects display, and adjust other visual parameters.
• External Dependencies/Services:
• pyswisseph is used for high-precision astrological calculations.
• tagit is used for generating and manipulating the SVG output.
• mkdocs-material is present to generate the documentation website (docs, mkdocs.yml).
• Optional PDF generation integrates with the natal-report package.
• Testing Suite: The “tests” directory covers unit tests for major components such as chart creation, config handling, constants, data processing, stats, and utilities.
• Developer & CI/CD Tools: GitHub Actions workflows help with continuous integration; configuration files like pyproject.toml and .gitignore define build/test settings.
Relationships and Interactions
• The Data Object receives input parameters (name, UTC datetime, latitude, longitude, and optional config) and initializes domain objects (planets, houses, etc.) using pyswisseph.
• The Chart Module consumes the Data object(s) to generate an SVG chart. It interfaces with tagit for the rendering and with the SVG path utilities for refining the output.
• The Stats Module analyzes a Data object (or two for composite charts) and produces textual reports (Markdown/HTML).
• The Config module customizes behavior and appearance, and its objects can be passed into the Data object.
• Testing components are standalone, verifying each component’s correctness.
Architectural Patterns and Design Principles
• Modular design: Each domain (Data, Chart, Stats, Config, Utils) exists as separate modules under the “natal” package.
• Separation of concerns: Data processing (e.g., calculating astronomical data), visual rendering, and reporting are all managed in dedicated components.
• Dependency injection: Custom configurations and state are injected into Data and Chart objects to allow flexibility.
• Extensibility: The design allows adding additional chart types or reports (e.g., composite charts, PDF reports) without altering core functionality.
Relevant Technologies and Libraries
• Python as the core language.
• pyswisseph for astronomy/astrological calculations.
• tagit for SVG/HTML manipulation.
• MkDocs (with mkdocs-material theme) for documentation generation.
• Pytest for testing.
• GitHub Actions for CI/CD.
Specific Elements
• Use clear labels to denote:
• Data Input Component (Data object with configuration)
• Domain Logic (Modules like classes, consts, config)
• Chart Generation Component (Chart module interfacing with tagit and SVG Path utilities)
• Statistics/Reporting Component (Stats module)
• External Dependencies (pyswisseph, tagit, mkdocs-material)
• Tests and CI/CD components (tests directory, GitHub workflows)
• From Input (Data, Config) to Processing (Chart computation and Stats generation)
• From Processing to Output (SVG chart, Markdown/HTML/PDF reports)
• Differentiate between domain modules, external libraries, developer tools, and testing/infrastructure.
• For example, rectangles for core modules, ellipses for external services, and parallelograms for input/output interfaces.