125 better documentation

AGENTS.md

@@ -0,0 +1,20 @@
+# AGENTS.md
+
+Purpose: guidance for agentic edits in asteroidpy.
+
+**Build / Lint / Test Commands**
+- `python -m build` to build artifacts.
+- `pytest -q` to run the test suite.
+- `pytest <path>::<test_name> -q` for a single test.
+- `ruff check .` (or `flake8`) for linting; `mypy` for type checks.
+
+**Code Style**
+- **Imports**: standard library first, then third‑party, then local; explicit imports only.
+- **Formatting**: format with Black; sort imports with isort; auto‑format on save if available.
+- **Types & Naming**: use type hints; snake_case for functions/vars; CamelCase for classes.
+- **Errors**: avoid bare excepts; raise/propagate clear exceptions; validate inputs early.
+- **Tests**: tests should be small, isolated; prefer parameterized tests when sensible.
+
+**Cursor / Copilot Rules**
+- Cursor rules: none found in this repo.
+- Copilot instructions: none found in this repo.

CHANGELOG.md

@@ -1,41 +1,65 @@
-## Changelog
-
-### [Unreleased]
-- i18n: Load translations from `locales/` using config `General.lang`; reinitialize on change
-- UI: Language menu lists installed locales with native names
-- Locales: Added it, en, de, fr, es, pt and compiled `.mo`
-- Weather: Handle unknown forecast codes gracefully (avoid KeyError)
-- Weather: Narrow exception handling when formatting forecast time (catch only TypeError/ValueError to avoid masking bugs)
-- Configuration: Avoid creating the user's home directory; write to `~/.asteroidpy` directly
-- Configuration: Use `~/.asteroidpy` for config and correct defaults; align tests
-- Configuration: Gracefully handle unreadable or invalid `~/.asteroidpy` by falling back to initialize
-- tests: Add coverage for unreadable config file permissions scenario
-- tests: Add coverage for corrupted/invalid config content fallback in `load_config` (closes #88)
-- i18n: Clarify that checking only `base.po/.mo` may not guarantee translation availability
-- Weather/UI: Improve default wind direction display (avoid ambiguous '?')
-- Docs/Security: Add `SECURITY.md` policy
-- Fix: Make `skycoord_format` robust to invalid strings and accept colon-separated input; return original string on invalid tokens (closes #90)
-- Fix: Accept case-insensitive `coordid` in `skycoord_format` (allow 'RA'/'Dec')
-- Fix: Apply `min_altitude` filtering in `neocp_confirmation` and expose it via the menu (closes #86)
-- tests: Add positive-path test for NEOCP confirmation including a valid object passing all filters
-- Fix: Make `observing_target_list_scraper` robust when the MPC page has fewer than four tables or unexpected/missing headers; return an empty list when no suitable table is found (closes #85)
-- Fix: Make `observing_target_list` skip malformed rows and unparseable times defensively
-- tests: Add coverage for no-table, wrong-headers, and malformed-row cases in observing target list scraping
-- Fix: Add robust error handling to `httpx_get`/`httpx_post`; return safe defaults on exceptions and preserve non-200 status codes; gracefully handle JSON parse failures
-- tests: Add coverage for non-200 responses and request exceptions in `httpx_get`/`httpx_post` (closes #84)
-- Fix: Make `is_visible` inclusive at boundary azimuths (45/135/225/315) and correct north-sector wrap-around; compare in degrees and allow altitude ≥ threshold (closes #83)
-- tests: Add edge-case tests for boundary azimuths and equal-to-threshold altitudes in `is_visible`
-- tests: Add coverage for `object_ephemeris` invalid stepping code; default to 1-hour on unknown code (closes #87)
-
-### 2025-08-11
-- types: Add and refine type hints across package and configure mypy
-- chore(mypy): Extend type checking to tests and docs config
-- tests: Add isolated test suite for configuration and scheduling
-- docs: Better formatting in setup.py
-
-### 2022-05 to 2022-10 (historical)
-- docs: Documentation added and finalized for multiple modules
-- feature: Object ephemeris, twilight times, sun/moon ephemeris
-- feature: Virtual horizon configuration and visibility checks
-- refactor: Observing target list and menus; convert to QTable
-- chore: Dependency updates and various maintenance commits
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.0](https://github.com/ziriuz84/asteroidpy/releases/tag/v1.0.0) (2026-02-14)
+
+### Features
+
+- **configuration:** implement get_observatory_coordinates ([4cbba90](https://github.com/ziriuz84/asteroidpy/commit/4cbba90d0b52f8c9b1085598bcdc03035b931eea))
+- **scheduling:** add velocity and direction to NEO confirmation ([4e08187](https://github.com/ziriuz84/asteroidpy/commit/4e081871be4a2919b1a6641754f3758c3bf831cf))
+- **i18n:** load translations from locales and add multi-language menu ([a75d4a4](https://github.com/ziriuz84/asteroidpy/commit/a75d4a44fae7c2b5c13541e66f2200f9f9f64956))
+- **types:** add and refine type hints across package and configure mypy ([d2c2943](https://github.com/ziriuz84/asteroidpy/commit/d2c2943a2a405e6e8e07e1db30fc681882f679b8))
+
+### Bug Fixes
+
+- **scheduling:** remove debug print and translate Italian comments ([833be34](https://github.com/ziriuz84/asteroidpy/commit/833be3430ce8be2ed26d02ab97823bf100236d28))
+- **interface:** replace eval with get_integer in config_menu ([272e293](https://github.com/ziriuz84/asteroidpy/commit/272e293d5a0f449d61c504cdc75fd977f66485aa))
+- **pyproject.toml:** correct license syntax from colon to equals sign for proper TOML format ([22e186a](https://github.com/ziriuz84/asteroidpy/commit/22e186ab91365ae5a2bbaf310b1b54ef2594afdc))
+- **pyproject.toml:** change license format from string to dictionary to comply with PEP 621 standards ([d55ab48](https://github.com/ziriuz84/asteroidpy/commit/d55ab488f42584b049836ceacbf094c703f228b7))
+- **scheduling:** add robust error handling to httpx_get/post and tests for non-200 responses and exceptions ([9a70541](https://github.com/ziriuz84/asteroidpy/commit/9a70541061bd7071f7595c388eb06a216c8f8896))
+- **scheduling:** make target list scraping robust to missing/malformed HTML tables and rows ([48da712](https://github.com/ziriuz84/asteroidpy/commit/48da712410ca69e174d07dfe4b6d1d7d8d2b81da))
+- **scheduling:** apply altitude filter and add positive NEOCP test ([10275cc](https://github.com/ziriuz84/asteroidpy/commit/10275cc671934324885bd2dc224f64ab1bc630b4))
+- **configuration:** handle unreadable or invalid config file in load_config ([0022a1d](https://github.com/ziriuz84/asteroidpy/commit/0022a1d03de6b6f6d6c038ffa3669dd200127425))
+- **scheduling:** accept case-insensitive coordid in skycoord_format ([5188fb0](https://github.com/ziriuz84/asteroidpy/commit/5188fb0a885ba8a5b2f7533a6f88b82e941fa87d))
+- **scheduling:** make skycoord_format robust to invalid strings and accept colon-separated input ([8fa3e3d](https://github.com/ziriuz84/asteroidpy/commit/8fa3e3da39fcae2bb800b6d8154b94d683dfac13))
+- **configuration:** stop creating user's home directory ([889a718](https://github.com/ziriuz84/asteroidpy/commit/889a718b3dfd8fe64c7cc98ecbd63675a0894fc2))
+- **configuration:** use ~/.asteroidpy for config and correct defaults; fix tests ([abb4e51](https://github.com/ziriuz84/asteroidpy/commit/abb4e51a7da9305ddaba915316a1dd6affc93b6c))
+- **scheduling:** narrow exception handling in weather time formatting ([a59bb84](https://github.com/ziriuz84/asteroidpy/commit/a59bb84abcecea5ad28dfa640dc3d6a7f1815ee5))
+- **scheduling:** The use of a try/except block in map_or_na may be unnecessary. ([8618439](https://github.com/ziriuz84/asteroidpy/commit/861843943cc90c99245b2362bc1ef1d9c454566e))
+
+### Code Refactoring
+
+- **tests:** inline simple conditional in fake_expanduser for clarity ([08df765](https://github.com/ziriuz84/asteroidpy/commit/08df765a118d3a3e55b0547ddea6a81ad8f29598))
+
+### Documentation
+
+- **README:** improve structure and content ([2796555](https://github.com/ziriuz84/asteroidpy/commit/2796555d15d55971f585981c32cd44961e94de49))
+- **interface:** improve docstrings ([b423698](https://github.com/ziriuz84/asteroidpy/commit/b423698c6fd7ddef59eb049277d71d783c0e767f))
+- improve code and user documentation ([b86a79c](https://github.com/ziriuz84/asteroidpy/commit/b86a79ca034138edf927b65f8684ca713f552501))
+- **changelog:** document is_visible boundary fixes and new tests ([28673a4](https://github.com/ziriuz84/asteroidpy/commit/28673a4c215dfc014437d902f2a40d57fe9173f9))
+- **changelog:** note robust httpx error handling and new tests (closes #84) ([ce7c8a4](https://github.com/ziriuz84/asteroidpy/commit/ce7c8a423dd968105924baff08b19d5584294138))
+- **changelog:** document robust parsing for observing target list and new tests (closes #85) ([5284843](https://github.com/ziriuz84/asteroidpy/commit/528484336f609cec66c59c023010dddb5e5e5900))
+- **changelog:** note min_altitude filter and new NEOCP test ([7c26619](https://github.com/ziriuz84/asteroidpy/commit/7c26619d42f415155ac2c928163fa1797c5fb1a2))
+- **changelog:** note corrupted/invalid config test for load_config ([82a6482](https://github.com/ziriuz84/asteroidpy/commit/82a6482faa29b488f908b30bcec1f28177a3f1c1))
+- **changelog:** note fallback on unreadable config and new tests ([6e35a65](https://github.com/ziriuz84/asteroidpy/commit/6e35a65bbf031f2bd532accaecc79fc570ea30e5))
+- **changelog:** note case-insensitive coordid handling in skycoord_format ([fe6ec20](https://github.com/ziriuz84/asteroidpy/commit/fe6ec202b75c5b37476e8a559ac30db032aed76c))
+- **changelog:** note skycoord_format robustness improvement and reference #90 ([abfd2cd](https://github.com/ziriuz84/asteroidpy/commit/abfd2cdf52911bbdb862c6ea18e19f5690cd1811))
+- **changelog:** add missing entries for recent changes ([49bc446](https://github.com/ziriuz84/asteroidpy/commit/49bc446ae968a0c92d9f8001e0c097abacc9c649))
+- **changelog:** note narrowed exception handling in weather() ([be03194](https://github.com/ziriuz84/asteroidpy/commit/be031947e35623fb1ecc6ee4cb32e98c39f73682))
+- **changelog:** add CHANGELOG summarizing recent changes ([28fbfe0](https://github.com/ziriuz84/asteroidpy/commit/28fbfe046ba7bcd7fe3b89cae41596038ed91a3b))
+
+### Tests
+
+- **configuration:** add print_obs_config redaction tests ([fbe4187](https://github.com/ziriuz84/asteroidpy/commit/fbe41879cf3b376271cbdb273aa69276fd08cbcf))
+- **configuration:** add coverage for corrupted/invalid config file ([694519b](https://github.com/ziriuz84/asteroidpy/commit/694519b949805e8ca92d09f4d883a9f6505d4f72))
+- **configuration,scheduling:** add isolated test suite ([4a755ab](https://github.com/ziriuz84/asteroidpy/commit/4a755abdcea898c8a4813bd8a84d9abbf64ff997))
+
+### Chores
+
+- **pyproject.toml:** comment out the GPL v3 license classifier to avoid confusion ([c984bf4](https://github.com/ziriuz84/asteroidpy/commit/c984bf4d75f66d9755666fc869af9cd2e2b0e90d))
+- **pyproject.toml:** update license format from table to string for consistency and clarity ([d1e6f1d](https://github.com/ziriuz84/asteroidpy/commit/d1e6f1dae36a64a0716bb8bb5545b35e3c338e7c))
+- **pyproject.toml:** remove unnecessary 'i' character from the file to clean up the configuration ([f4bc4a6](https://github.com/ziriuz84/asteroidpy/commit/f4bc4a66bce272048a3491db4e88203d6e3e87aa))
+- better setup tools ([7ec4157](https://github.com/ziriuz84/asteroidpy/commit/7ec4157e043cca94f97ea1224535d89fcf884f9a))
+- **mypy:** extend type checking to tests and docs config ([520179b](https://github.com/ziriuz84/asteroidpy/commit/520179b805d14475dd70e3154f98ad42b7ca86d1))
+- **setup.py:** better formatting ([5a6a542](https://github.com/ziriuz84/asteroidpy/commit/5a6a542da0c64c86af108e633395e7f9aab02837))

README.md

@@ -1,84 +1,104 @@
 # AsteroidPy
 
-A simple tool to manage Asteroid observations and misurements
+A simple tool to manage Asteroid observations and measurements
 
 ![GitHub](https://img.shields.io/github/license/ziriuz84/asteroidpy)
-[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](code_of_conduct.md)
+[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)
 
 ## Description
 
-AsteroidPy is a simple tool to help astronomers to Schedule and manage asteroidal observation and misurements. It uses the main sources in minor planets research to provide punctual prevision of ephemerides and Neocp candidates.
+AsteroidPy is a simple tool to help astronomers schedule and manage asteroidal observations and measurements. It uses the main sources in minor planets research to provide accurate predictions of ephemerides and NEOcp candidates.
 
 ## Features
 
 - Weather forecast
 - Observation scheduling
-- NeoCP Candidates Listing
+- NEOcp candidates listing
 - Object ephemeris
 - Twilight, Sun and Moon times
-- Virtual Horizon simulation
+- Virtual horizon simulation
 
 ## Getting Started
 
-Using AsteroidPy is very easy. Here you can find instructions
-
 ### Requirements
 
-- Python 3.x installed and configured
-- Pip installed
+- Python 3.8 or later
+- pip
 
 ### Installation
 
-#### From Source:
+#### From source
+
+- Clone the repository:
+  ```bash
+  git clone https://github.com/ziriuz84/asteroidpy
+  cd asteroidpy
+  ```
+
+- (Optional) Create and activate a virtual environment:
+  ```bash
+  python -m venv env
+  source env/bin/activate  # On Windows: env\Scripts\activate
+  ```
 
-- Clone the repository in your directory
-   `git clone https://github.com/ziriuz84/asteroipy`
-- Enter the folder with the command of your choice, usually
-   `cd asteroidpy`
-- (Optional) create a Virtualenv for your installation
-   `virtualenv env`
-- Install AsteroidPy
-   `pip install .`
+- Install AsteroidPy:
+  ```bash
+  pip install .
+  ```
 
 ### Execution
 
-Simply launch the command
+Run the application:
+
+```bash
+asteroidpy
+```
+
+### Configuration
 
-`asteroidpy`
+Configuration is stored in `~/.asteroidpy`. On first run, the application creates it with defaults. Use the configuration menu to set:
 
-## Release History
+- Observatory location (coordinates, altitude, MPC code)
+- Virtual horizon (minimum altitude per cardinal direction)
+- Interface language
 
-## Library used
+### Internationalization
 
-- Requests
-- BeautifoulSoup 4
-- Configparser
-- Astropy
-- Astroquery
-- Astroplan
-- LXML
+AsteroidPy supports multiple languages. Change the language from Configuration → General in the main menu. Available locales include English, Italiano, Deutsch, Français, Español, and Português (depending on installed translation files).
 
-## Data provenience
+## Dependencies
 
-- [7Timer](https://7timer.info)
-- [Minor Planet Center](https://www.minorplanetcenter.net/)
+- requests
+- BeautifulSoup4
+- astropy
+- astroplan
+- astroquery
+- httpx
+- lxml
+- platformdirs
 
-## Contributing [![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/ziriuz84/asteroidpy/issues)
+## Data sources
 
+- [7Timer](https://7timer.info) — weather forecasts
+- [Minor Planet Center](https://www.minorplanetcenter.net/) — ephemerides and NEOcp data
 
-Thank you for considering contributing to Your Project Name!
+## Release history
 
-Please first note we have a code of conduct, please follow it in all your
-interactions with the project.
+See [CHANGELOG.md](CHANGELOG.md).
+
+## Contributing
+
+[![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/ziriuz84/asteroidpy/issues)
+
+Thank you for considering contributing to AsteroidPy!
+
+Please first note we have a code of conduct; please follow it in all your interactions with the project.
 
 We welcome any type of contribution, not only code. You can help with:
-- **QA**: File bug reports, the more details you can give the better (e.g.
-screenshots with the console open)
-- **Community**: Presenting the project at meetups, organizing a dedicated
-meetup for the local community
-- **Code**: Take a look at the [open issues](https://github.com/ziriuz84/asteroidpy/issues).
-Even if you can't write the code yourself, you can comment on them, showing that
-you care about a given issue matters. It helps us triage them
+
+- **QA**: File bug reports; the more details you can give, the better (e.g. screenshots with the console open)
+- **Community**: Presenting the project at meetups, organizing a dedicated meetup for the local community
+- **Code**: Take a look at the [open issues](https://github.com/ziriuz84/asteroidpy/issues). Even if you can't write the code yourself, you can comment on them—showing that you care about a given issue helps us triage them.
 
 ## TODO
 

asteroidpy/__init__.py

@@ -1,8 +1,24 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
-import asteroidpy.interface as interface
+"""AsteroidPy - A tool for asteroid observation scheduling and analysis.
+
+AsteroidPy is a Python application designed to help astronomers schedule
+and manage asteroid observations. It integrates with the Minor Planet Center
+and other astronomical data sources to provide:
+
+- Weather forecasts for observatory locations
+- Observation scheduling with target lists
+- NEOcp (Near Earth Object Confirmation Page) candidate listings
+- Object ephemeris calculations
+- Twilight and Sun/Moon ephemeris
+- Virtual horizon visibility calculations
+
+The application provides an interactive command-line interface with support
+for multiple languages and comprehensive observatory configuration options.
+"""
 import configparser
-import cProfile, pstats
+import cProfile
+import pstats
 from configparser import ConfigParser
 
 import asteroidpy.interface as interface
@@ -12,8 +28,22 @@
 config: ConfigParser = configparser.ConfigParser()
 
 def main() -> None:
+    """Main entry point for the AsteroidPy application.
+
+    Initializes the configuration and launches the user interface. Optionally
+    enables profiling if the PROFILE flag is set to True.
+
+    Returns
+    -------
+    None
+        This function does not return a value.
 
-    """Main function"""
+    Notes
+    -----
+    If PROFILE is True, the function runs with cProfile enabled and saves
+    profiling statistics to 'asteroidpy.prof'. Otherwise, it directly
+    launches the interface.
+    """
     if PROFILE:
         profiler = cProfile.Profile()
         profiler.enable()