AsteroidPy

AsteroidPy is a command-line tool for astronomers to schedule and manage asteroid observations. It integrates with the Minor Planet Center and other astronomical data sources to provide ephemerides, NEO confirmation candidates, weather forecasts, and observing aids—all from an interactive terminal interface.

---

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Configuration
• FAQ
• Data Sources
• For Contributors
  • Project architecture
  • How to add a translation
  • Release process
• Release History
• License

---

Features

Feature	Description
Weather forecast	Astronomical weather (cloud cover, seeing, transparency) up to 72 hours via 7Timer
Observation scheduling	Plan sessions with target lists and visibility windows
NEOcp candidates	List and filter Near-Earth Object candidates from the MPC Confirmation Page
Object ephemeris	Retrieve detailed ephemeris data for any minor body
Twilight & Sun/Moon	Civil, nautical, and astronomical twilight; rise/set times
Virtual horizon	Simulate horizon obstructions for visibility calculations

---

Requirements

• Python 3.9 or later
• pip (or another Python package manager)

AsteroidPy runs on Linux, macOS, and Windows.

---

Installation

From source

1. Clone the repository:

   git clone https://github.com/ziriuz84/asteroidpy.git
   cd asteroidpy

2. (Recommended) Create and activate a virtual environment:

   python -m venv .venv
   source .venv/bin/activate   # On Windows: .venv\Scripts\activate

3. Install in editable mode:

   pip install -e .

   Or in normal mode:

   pip install .

---

Quick Start

Run the application:

asteroidpy

On first launch, AsteroidPy creates a config directory at ~/.asteroidpy with default settings. Use the Configuration menu to set:

• Observatory: coordinates, altitude, MPC code
• Virtual horizon: minimum altitude per cardinal direction
• General: interface language

---

Configuration

Configuration is stored in ~/.asteroidpy. Use the in-app Configuration → General menu to change:

Option	Description
Observatory	Latitude, longitude, altitude, MPC observatory code
Virtual horizon	Minimum altitude (in degrees) per cardinal direction for visibility
Language	Interface language (English, Italiano, Deutsch, Français, Español, Português)

---

FAQ

Where do I find my MPC observatory code?
The Minor Planet Center publishes the list of observatory codes. If your site is not listed, use XXX or another temporary code until you register it with the MPC.

Why do ephemerides differ from Stellarium or other tools?
Small differences can arise from different orbital elements, epoch dates, or time handling. AsteroidPy uses MPC data directly; ensure your observatory coordinates and time (UTC vs local) match across tools.

The application fails to start or shows errors.
Check that all dependencies are installed (pip install .), that ~/.asteroidpy is writable, and that you have internet access (required for weather and ephemeris queries). If the config file is corrupted, you can remove ~/.asteroidpy and let the app recreate it on next run.

Which languages are supported?
English (default), Italiano, Deutsch, Français, Español, Português. Change the language in Configuration → General; only locales with compiled .mo files are shown.

---

Data Sources

AsteroidPy relies on:

• 7Timer — meteorological forecasts (cloud cover, seeing, transparency)
• Minor Planet Center (MPC) — ephemerides and NEO Confirmation Page data

---

For Contributors

Thank you for considering contributing to AsteroidPy. Please read the Code of Conduct before participating.

Types of contributions we welcome

• Code: bug fixes, new features, refactoring
• QA: bug reports with repro steps and environment details
• Documentation: improvements to this README, docstrings, or Sphinx docs
• Community: presenting the project, organizing local meetups

Development setup

1. Clone the repository and install in editable mode (see Installation).

2. Install development dependencies (optional, for tests and linting):

   pip install pytest ruff mypy black isort

3. Run the test suite:

   pytest -q

   Run a single test:

   pytest tests/test_scheduling.py::test_name -q

4. Lint and type-check:

   ruff check .
   mypy .

5. Build the package:

   python -m build

Code style

• Imports: standard library → third-party → local; explicit imports only
• Formatting: Black for style; isort for import order
• Types: type hints on public APIs; snake_case for functions/variables; CamelCase for classes
• Errors: avoid bare except; raise or propagate clear exceptions; validate inputs early
• Tests: small, isolated tests; prefer parameterized tests where sensible

Getting involved

• Browse open issues and comment or pick one to work on
• Open issues for bugs or feature ideas—the more detail, the better
• Pull requests are welcome; please ensure tests pass and style is consistent

Project architecture

asteroidpy/
├── __init__.py      # Entry point; loads config, launches interface
├── interface.py     # CLI menus, user I/O, gettext setup
├── scheduling.py    # Ephemerides, weather, NEOcp, twilight
├── configuration.py # Observatory config, horizon, language
└── locales/         # gettext translations (en, it, de, fr, es, pt)

• interface — Main entry for the interactive UI. Loads config, sets up gettext, and delegates to scheduling for ephemeris/weather/NEOcp and to configuration for settings.
• scheduling — Astronomy logic: MPC queries, 7Timer weather, twilight, Sun/Moon ephemeris. Uses configuration.load_config() to read observatory data.
• configuration — Persists and loads settings in ~/.asteroidpy; handles observatory coordinates, virtual horizon, and language. Used by both interface and scheduling.

How to add a translation

AsteroidPy uses GNU gettext with a single catalog base. Translations live under locales/<lang>/LC_MESSAGES/.

1. Create a new locale directory:

   mkdir -p locales/nl/LC_MESSAGES

2. Copy and adapt an existing .po file, or create one from the template:

   cp locales/it/LC_MESSAGES/base.po locales/nl/LC_MESSAGES/base.po

   Edit locales/nl/LC_MESSAGES/base.po, set Language: nl, and translate all msgstr entries.

3. Compile the .po file into a .mo file (required for the language to appear in the menu):

   msgfmt -o locales/nl/LC_MESSAGES/base.mo locales/nl/LC_MESSAGES/base.po

   The msgfmt command comes with the gettext package (gettext on most Linux distros).

4. The new language will appear in Configuration → General after restart.

To add or update translatable strings for all locales, update locales/base.pot (e.g. with xgettext or pybabel), then merge into each .po with msgmerge, translate, and recompile with msgfmt.

Release process

1. Update asteroidpy/version.py (__version__, used by setuptools and the UI); keep setup.py in sync if you still rely on it.
2. Add the corresponding entry to CHANGELOG.md under a new [X.Y.Z] heading with date and link to the tag.
3. Run tests and build:

   pytest -q
   python -m build

4. Commit the version bump and changelog, then create and push a tag:

   git tag vX.Y.Z -m "Release vX.Y.Z"
   git push origin main --tags

   (Use git tag -s for a signed tag if you have GPG configured.)
5. Create a release on GitHub from the new tag and attach the built artifacts (e.g. from dist/).

---

Release History

See CHANGELOG.md.

---

TODO

• NEOcp alert integration
• Observation registration

---

License

AsteroidPy is licensed under the GPL-3.0 license.