Merge pull request #1 from jfcarr/feature/publish-refactor

Refactor for PyPI, docs regen

.gitignore

@@ -0,0 +1,3 @@
+dist/*
+
+src/practical_astronomy/__pycache__/*

LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2018 The Python Packaging Authority
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -1,6 +1,8 @@
+PYEXE = python3
+
 default:
 	@echo 'Targets:'
-	@echo '  all'
+	@echo '  all-tests'
 	@echo '  test-easter'
 	@echo '  test-day-number'
 	@echo '  test-julian'
@@ -10,32 +12,44 @@ default:
 	@echo '  test-planet-comet-binary'
 	@echo '  test-moon'
 	@echo '  test-eclipses'
+	@echo '  build'
+	@echo '  upload-test'
+	@echo '  upload'
 
-all: test-easter test-day-number test-julian test-time test-coordinate test-sun test-planet-comet-binary test-moon test-eclipses
+all-tests: test-easter test-day-number test-julian test-time test-coordinate test-sun test-planet-comet-binary test-moon test-eclipses
 
 test-easter:
-	@./test-date-of-easter.py -v
+	@$(PYEXE) test_date_of_easter.py
 
 test-day-number:
-	@./test-day-number.py
+	@$(PYEXE) test_day_number.py
 
 test-julian:
-	@./test-julian.py
+	@$(PYEXE) test_julian.py
 
 test-time:
-	@./test-time.py
+	@$(PYEXE) test_time.py
 
 test-coordinate:
-	@./test-coordinate.py
+	@$(PYEXE) test_coordinate.py
 
 test-sun:
-	@./test-sun.py
+	@$(PYEXE) test_sun.py
 
 test-planet-comet-binary:
-	@./test-planet-comet-binary.py
+	@$(PYEXE) test_planet_comet_binary.py
 
 test-moon:
-	@./test-moon.py
+	@$(PYEXE) test_moon.py
 
 test-eclipses:
-	@./test-eclipses.py
+	@$(PYEXE) test_eclipses.py
+
+build:
+	$(PYEXE) -m build
+
+upload-test: build
+	$(PYEXE) -m twine upload --repository testpypi dist/*
+
+upload: build
+	$(PYEXE) -m twine upload dist/*

README.md

@@ -1,72 +1,117 @@
 # practical-astronomy-python
 
-Algorithms from "[Practical Astronomy with your Calculator or Spreadsheet](https://www.amazon.com/Practical-Astronomy-your-Calculator-Spreadsheet/dp/1108436072)" by Peter Duffett-Smith, implemented in Python 3.  API documentation is published [here](https://jfcarr-astronomy.github.io/practical-astronomy-python/).
+Algorithms from [Practical Astronomy with your Calculator or Spreadsheet](https://www.amazon.com/Practical-Astronomy-your-Calculator-Spreadsheet/dp/1108436072) by Peter Duffett-Smith, implemented in Python 3.  API documentation is published [here](https://jfcarr.github.io/practical-astronomy-python/).
 
 If you're interested in this topic, please buy the book!  It provides far more detail and context.
 
-## CLI
+## Quick Start
 
-Work is started on a command-line interface, but only the date/time functions are implemented, so far.  Results are formatted as JSON.
-
-Invoke as `./pa-cli.py -h` to see all of the options:
+Install:
 
+```bash
+pip install practical-astronomy
 ```
-$ ./pa-cli.py -h
-
-usage: pa-cli.py [-h] [--cd CD] [--ct CT] [--dh DH] [--gd GD] [--gl GL] [--gst GST] [--lst LST] [--jd JD] [--ut UT] [--year YEAR] [--dst] [--st] [--zc ZC] [--doe] [--cd_to_dn] [--gd_to_jd] [--jd_to_gd] [--ct_to_dh] [--dh_to_ct] [--lct_to_ut] [--ut_to_lct] [--ut_to_gst] [--gst_to_ut] [--gst_to_lst] [--lst_to_gst]
-
-Practical Astronomy CLI.
-
-optional arguments:
-  -h, --help    show this help message and exit
-
-Actions:
-  --doe         Calculate date of Easter, for a given year.
-  --cd_to_dn    Convert civil date to day number.
-  --gd_to_jd    Convert Greenwich date to Julian date.
-  --jd_to_gd    Convert Julian date to Greenwich date.
-  --ct_to_dh    Convert civil time to decimal hours.
-  --dh_to_ct    Convert decimal hours to civil time.
-  --lct_to_ut   Convert local civil time to universal time.
-  --ut_to_lct   Convert universal time to local civil time.
-  --ut_to_gst   Convert universal time to Greenwich sidereal time.
-  --gst_to_ut   Convert Greenwich sidereal time to universal time.
-  --gst_to_lst  Convert Greenwich sidereal time to local sidereal time.
-  --lst_to_gst  Convert local sidereal time to Greenwich sidereal time.
-
-Inputs (used by Actions):
-  --cd CD       Civil date. Input format: 'mm/dd/yyyy'
-  --ct CT       Civil time. Input format: 'hh:mm:ss'
-  --dh DH       Decimal hours. Input format: floating point number, e.g., 18.52416667
-  --gd GD       Greenwich date. Input format: 'mm/dd/yyyy'. Fractional day is allowed, e.g., '6/19.75/2009'
-  --gl GL       Geographical longitude. Input format: (+/-)##.##, e.g., -64.00
-  --gst GST     Greenwich sidereal time. Input format: 'hh:mm:ss'
-  --lst LST     Local sidereal time. Input format: 'hh:mm:ss'
-  --jd JD       Julian date. Input format: floating point number, e.g., 2455002.25
-  --ut UT       Universal time. Input format: 'hh:mm:ss'
-  --year YEAR   Calendar year, e.g. 2019.
-
-Inputs (time zone management):
-  --dst         Observe daylight savings time.
-  --st          Observe standard time (default)
-  --zc ZC       Offset, in hours, for time zone correction.
 
-```
+Create `easter.py`:
 
-### Example
+```python
+import practical_astronomy.pa_datetime as pd
+
+print(pd.get_date_of_easter(2024))
+```
 
-Convert universal time to Greenwich sidereal time:
+Run it:
 
+```bash
+python easter.py
 ```
-$./pa-cli.py --ut_to_gst --ut "14:36:51.67" --gd "4/22/1980"
 
-{"greenwichSiderealTimeHours": 4, "greenwichSiderealTimeMinutes": 40, "greenwichSiderealTimeSeconds": 5.23}
+Result:
+
+```
+(3, 31, 2024)
 ```
 
 ## Unit Tests
 
-Unit test run can be invoked via the Make utility:
+If you clone the [repo](https://github.com/jfcarr/practical-astronomy-python) locally, you can run unit tests with the Make utility:
 
 ```
-make all
+make all-tests
 ```
+
+## Library Functions
+
+Documentation [here](https://jfcarr.github.io/practical-astronomy-python/).
+
+### Date/Time
+
+Type | Description
+-----|------------
+Calculate | Date of Easter
+Convert | Civil Date to Day Number
+Convert | Greenwich Date <-> Julian Date
+Convert | Julian Date to Day-of-Week
+Extract | Day, Month, and Year parts of Julian Date
+Convert | Civil Time <-> Decimal Hours
+Extract | Hour, Minutes, and Seconds parts of Decimal Hours
+Convert | Local Civil Time <-> Universal Time
+Convert | Universal Time <-> Greenwich Sidereal Time
+Convert | Greenwich Sidereal Time <-> Local Sidereal Time
+
+### Coordinates
+
+Type | Description
+-----|------------
+Convert | Angle <-> Decimal Degrees
+Convert | Right Ascension <-> Hour Angle
+Convert | Equatorial Coordinates <-> Horizon Coordinates
+Calculate | Obliquity of the Ecliptic
+Convert | Ecliptic Coordinates <-> Equatorial Coordinates
+Convert | Equatorial Coordinates <-> Galactic Coordinates
+Calculate | Angle between two objects
+Calculate | Rising and Setting times for an object
+Calculate | Precession (corrected coordinates between two epochs)
+Calculate | Nutation (in ecliptic longitude and obliquity) for a Greenwich date
+Calculate | Effects of aberration for ecliptic coordinates
+Calculate | RA and Declination values, corrected for atmospheric refraction and geocentric parallax
+Calculate | Heliographic coordinates
+Calculate | Carrington rotation number
+Calculate | Selenographic (lunar) coordinates (sub-Earth and sub-Solar)
+
+### The Sun
+
+Type | Description
+-----|------------
+Calculate | Approximate and precise positions of the Sun
+Calculate | Sun's distance and angular size
+Calculate | Local sunrise and sunset
+Calculate | Morning and evening twilight
+Calculate | Equation of time
+Calculate | Solar elongation
+
+### Planets
+
+Type | Description
+-----|------------
+Calculate | Approximate and precise position of planet
+Calculate | Visual aspects of planet (distance, angular diameter, phase, light time, position angle of bright limb, and apparent magnitude)
+Calculate | Position of comet (elliptical and parabolic)
+Calculate | Binary star orbit data
+
+### The Moon
+
+Type | Description
+-----|------------
+Calculate | Approximate and precise position of Moon
+Calculate | Moon phase and position angle of bright limb
+Calculate | Times of new Moon and full Moon
+Calculate | Moon's distance, angular diameter, and horizontal parallax
+Calculate | Local moonrise and moonset
+
+### Eclipses
+
+Type | Description
+-----|------------
+Calculate | Lunar eclipse occurrence and circumstances
+Calculate | Solar eclipse occurrence and circumstances