diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 2c32c4d..c6110cd 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -7,19 +7,21 @@ on: jobs: job: - name: GitHub Pages + name: Docs runs-on: ubuntu-latest container: ghcr.io/astral-sh/uv:python3.12-bookworm env: UV_PROJECT_ENVIRONMENT: /usr/local + permissions: + contents: write steps: - uses: actions/checkout@v4 - with: - submodules: true + - run: echo "tag=${GITHUB_REF##*/}" >> $GITHUB_OUTPUT + id: tag - run: uv sync --frozen - run: docs/build - uses: peaceiris/actions-gh-pages@v4 with: - force_orphan: true + destination_dir: ${{ steps.tag.outputs.tag }} github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./docs/_build diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml index 4d91c2a..3ba04f1 100644 --- a/.github/workflows/tests.yaml +++ b/.github/workflows/tests.yaml @@ -26,8 +26,6 @@ jobs: - python3.13-bookworm steps: - uses: actions/checkout@v4 - with: - submodules: true - run: uv sync --frozen - run: black --check ${PYTHON_DIRS} - run: pyright ${PYTHON_DIRS} diff --git a/.gitignore b/.gitignore index 5d99a78..eefac9b 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,5 @@ -### Azely ### -.azely/ +# Created by https://www.toptal.com/developers/gitignore/api/python +# Edit at https://www.toptal.com/developers/gitignore?templates=python ### Python ### # Byte-compiled / optimized / DLL files @@ -74,7 +74,7 @@ instance/ # Sphinx documentation docs/readme.rst -docs/_apidoc +docs/_apidoc/ docs/_build/ # PyBuilder @@ -174,3 +174,5 @@ poetry.toml # LSP config files pyrightconfig.json + +# End of https://www.toptal.com/developers/gitignore/api/python diff --git a/CITATION.cff b/CITATION.cff index d612074..d9130fa 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -4,7 +4,8 @@ cff-version: 1.2.0 title: azely message: >- - If you use this software, please cite it using the metadata from this file. + If you use this software, please cite it using the + metadata from this file. type: software authors: - given-names: Akio @@ -16,8 +17,8 @@ identifiers: - type: doi value: 10.5281/zenodo.3680060 repository-code: 'https://github.com/astropenguin/azely' -url: 'https://astropenguin.github.io/azely' -abstract: Azimuth/elevation visualization for astronomy +url: 'https://astropenguin.github.io/azely/1.0.0' +abstract: Azimuth/elevation calculator for astronomical objects keywords: - python - astronomy @@ -27,5 +28,5 @@ keywords: - sidereal-time - visibility license: MIT -version: 0.7.0 -date-released: '2022-11-03' +version: 1.0.0 +date-released: '2025-07-07' diff --git a/README.md b/README.md index 435fc0f..fc48777 100644 --- a/README.md +++ b/README.md @@ -4,229 +4,214 @@ [![Python](https://img.shields.io/pypi/pyversions/azely?label=Python&color=cornflowerblue&style=flat-square)](https://pypi.org/project/azely/) [![Downloads](https://img.shields.io/pypi/dm/azely?label=Downloads&color=cornflowerblue&style=flat-square)](https://pepy.tech/project/azely) [![DOI](https://img.shields.io/badge/DOI-10.5281/zenodo.3680060-cornflowerblue?style=flat-square)](https://doi.org/10.5281/zenodo.3680060) -[![Tests](https://img.shields.io/github/workflow/status/astropenguin/azely/Tests?label=Tests&style=flat-square)](https://github.com/astropenguin/azely/actions) +[![Tests](https://img.shields.io/github/actions/workflow/status/astropenguin/azely/tests.yaml?label=Tests&style=flat-square)](https://github.com/astropenguin/azely/actions) -Azimuth/elevation visualization for astronomy +Azimuth/elevation calculator for astronomical objects -## TL;DR +## Overview -Azely (pronounced as "as-elie") is a Python package for computation and plotting of horizontal coordinates (azimuth and elevation; az/el, hereafter) of astronomical objects at given location and time. -While computation and plotting are realized by [Astropy] and [Matplotlib], what azely provides is high-level API to use them easily. -In fact azely offers one-liner to compute and plot, for example, one-day elevation of the Sun in Tokyo: +**Azely** (pronounced "as-elie") is a Python package for calculation and plotting of horizontal coordinates (azimuth and elevation) of astronomical objects at given location and time. +While the core calculation and plotting are handled by [Astropy](https://astropy.org) and [Matplotlib](https://matplotlib.org), Azely provides a simple API for easier and more intuitive use. +For example, calculating and plotting the elevation of the Sun in Tokyo for today can be done in a single line: ```python ->>> azely.compute('Sun', 'Tokyo').el.plot(ylim=(0, 90)) +import azely + +azely.calc('Sun', 'Tokyo').el.plot(ylim=(0, 90)) ``` -![one-liner.svg](https://raw.githubusercontent.com/astropenguin/azely/v0.7.0/docs/_static/one-liner.svg) +![one-liner.svg](https://raw.githubusercontent.com/astropenguin/azely/1.0.0/docs/_static/one-liner.svg) ## Features -- **High-level API:** azely provides a simple yet powerful `compute()` function. Users can complete most of operation with it (e.g., information acquisition and computation). -- **Handy output:** azely's output (from `compute()`) is [pandas] DataFrame, a de facto standard data structure of Python. Users can convert it to other formats like CSV and plot it by [Matplotlib] using builtin methods. -- **Web information acquisition:** azely can automatically acquire object and location information (i.e., longitude and latitude) from online services (e.g., catalogues or maps). Obtained information is cached in a local [TOML] file for an offline use. -- **User-defined information:** azely also offers to use user-defined object and location information written in a [TOML] file. - -## Requirements - -- **Python:** 3.7, 3.8, 3.9, and 3.10 (tested by author) -- **Dependencies:** See [pyproject.toml](https://github.com/astropenguin/azely/blob/v0.7.0/pyproject.toml) +- **Simple API:** Just pass query strings for the object, location, and time information to the `azely.calc()` function. The output is a [pandas](https://pandas.pydata.org) DataFrame of the calculated azimuth and elevation, which makes it easy to convert to other formats like CSV or plot with Matplotlib. +- **Information Retrieval and Cache:** Azely automatically fetches object coordinates and location details from online services. The fetched information is cached in a local TOML file for offline use. ## Installation ```shell -$ pip install azely +pip install azely ``` -## Basic usage - -This section describes basic az/el computation using `compute()` function. - -### Compute function +## Basic Usage -Azely's `compute()` function receives the following parameters and returns [pandas] DataFrame (`df`): +The easiest way to use Azely is to pass query strings for the object, location, and time information to the `azely.calc()` function to get the azimuth/elevation DataFrame: ```python ->>> import azely ->>> df = azely.compute(object, site, time, view, **options) -``` - -This means that `azely` will `compute` az/el of `object` observed from `site` at (on) `time` in `view`. -For example, the following code will compute az/el of Sun observed from ALMA AOS on Jan. 1st 2020 in Tokyo. +import azely -```python ->>> df = azely.compute('Sun', 'ALMA AOS', '2020-01-01', 'Tokyo') +df = azely.calc(object, location, time) ``` -Acceptable formats of each parameter and examples are as follows. - -| Parameter | Acceptable format | Description | Examples | -| --- | --- | --- | --- | -| `object` | `` | name of object to be searched | `'Sun'`, `'NGC1068'` | -| | `:` | user-defined object to be loaded (see below) | `'user.toml:M42'`, `'user:M42'` (also valid) | -| `site` | `'here'` (default) | current location (guess by IP address) | | -| | `` | name of location to be searched | `'ALMA AOS'`, `'Tokyo'` | -| | `:` | user-defined location to be loaded (see below) | `'user.toml:ASTE'`, `'user:ASTE'` (also valid) | -| `time` | `'today'` (default) | get one-day time range of today | | -| | `'now'` | get current time | | -| | `