wndsn-tycho 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- wndsn_tycho-0.1.0/CHANGELOG.md +19 -0
- wndsn_tycho-0.1.0/LICENSE +21 -0
- wndsn_tycho-0.1.0/MANIFEST.in +4 -0
- wndsn_tycho-0.1.0/PKG-INFO +187 -0
- wndsn_tycho-0.1.0/README.md +164 -0
- wndsn_tycho-0.1.0/docs/api.md +115 -0
- wndsn_tycho-0.1.0/pyproject.toml +39 -0
- wndsn_tycho-0.1.0/setup.cfg +4 -0
- wndsn_tycho-0.1.0/src/wndsn_tycho/__init__.py +86 -0
- wndsn_tycho-0.1.0/src/wndsn_tycho/__main__.py +3 -0
- wndsn_tycho-0.1.0/src/wndsn_tycho/_version.py +1 -0
- wndsn_tycho-0.1.0/src/wndsn_tycho/calculators.py +430 -0
- wndsn_tycho-0.1.0/src/wndsn_tycho/cli.py +49 -0
- wndsn_tycho-0.1.0/src/wndsn_tycho/client.py +359 -0
- wndsn_tycho-0.1.0/src/wndsn_tycho/py.typed +0 -0
- wndsn_tycho-0.1.0/src/wndsn_tycho/results.py +348 -0
- wndsn_tycho-0.1.0/src/wndsn_tycho.egg-info/PKG-INFO +187 -0
- wndsn_tycho-0.1.0/src/wndsn_tycho.egg-info/SOURCES.txt +25 -0
- wndsn_tycho-0.1.0/src/wndsn_tycho.egg-info/dependency_links.txt +1 -0
- wndsn_tycho-0.1.0/src/wndsn_tycho.egg-info/entry_points.txt +2 -0
- wndsn_tycho-0.1.0/src/wndsn_tycho.egg-info/top_level.txt +1 -0
- wndsn_tycho-0.1.0/tests/__init__.py +0 -0
- wndsn_tycho-0.1.0/tests/fake.py +68 -0
- wndsn_tycho-0.1.0/tests/fixtures/answers.json +349 -0
- wndsn_tycho-0.1.0/tests/test_calculators.py +273 -0
- wndsn_tycho-0.1.0/tests/test_client.py +324 -0
- wndsn_tycho-0.1.0/tests/test_live.py +52 -0
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
Versions follow [semantic versioning](https://semver.org). The version lives in
|
|
4
|
+
`src/wndsn_tycho/_version.py`; tag releases `vX.Y.Z`.
|
|
5
|
+
|
|
6
|
+
## 0.1.0 (2026-11-22)
|
|
7
|
+
|
|
8
|
+
- First version. Standard library only, Python 3.10+.
|
|
9
|
+
- `Tycho` with one typed method per calculator: `sun`, `star`, `sight`, `moon`, `scale`,
|
|
10
|
+
`range`, `height`, `dip`, `elevation`, `shadow`, `duv`. Arguments are checked before a
|
|
11
|
+
request; results are dataclasses with named fields, `input`, `notes`, `digits` and `raw`.
|
|
12
|
+
- `Client.get` for raw queries in JSON, XML or CSV.
|
|
13
|
+
- Optional cache (`cache=True` for the user cache directory, or a directory) with modes
|
|
14
|
+
`fill`, `offline`, `refresh`. Off by default.
|
|
15
|
+
- At most one request per second against tycho.wndsn.com, shared by all clients in a process;
|
|
16
|
+
retries on HTTP 429 and 5xx.
|
|
17
|
+
- Handles `height`'s flat answer, `range`'s size limit (65536), `sun` without a date, and
|
|
18
|
+
`shadow`'s `arccot` (now `complement`) in older cached answers.
|
|
19
|
+
- Command line: `wndsn-tycho <calculator> name=value ...`.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 the wndsn-tycho authors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: wndsn-tycho
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Python client for the Tycho calculators at tycho.wndsn.com (sun, star, sight, moon, range, shadow, ...)
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
Project-URL: Calculators, https://tycho.wndsn.com
|
|
7
|
+
Project-URL: Source, https://github.com/gqt0/wndsn-tycho
|
|
8
|
+
Project-URL: Documentation, https://github.com/gqt0/wndsn-tycho/blob/main/docs/api.md
|
|
9
|
+
Project-URL: Changelog, https://github.com/gqt0/wndsn-tycho/blob/main/CHANGELOG.md
|
|
10
|
+
Project-URL: Issues, https://github.com/gqt0/wndsn-tycho/issues
|
|
11
|
+
Keywords: astronomy,navigation,sun,moon,sight reduction,rangefinding,quadrant,tycho,wndsn
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Intended Audience :: Science/Research
|
|
14
|
+
Classifier: Operating System :: OS Independent
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
17
|
+
Classifier: Topic :: Scientific/Engineering :: Astronomy
|
|
18
|
+
Classifier: Typing :: Typed
|
|
19
|
+
Requires-Python: >=3.10
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
License-File: LICENSE
|
|
22
|
+
Dynamic: license-file
|
|
23
|
+
|
|
24
|
+
# wndsn-tycho
|
|
25
|
+
|
|
26
|
+
A Python client for the [Tycho calculators](https://tycho.wndsn.com): the Sun, stars, sight
|
|
27
|
+
reduction, the Moon, map scale, range and height from angular size, dip of the horizon,
|
|
28
|
+
elevation, the shadow square, and Duv.
|
|
29
|
+
|
|
30
|
+
- One typed method per calculator, with arguments checked before anything is sent and
|
|
31
|
+
results as dataclasses with named fields.
|
|
32
|
+
- Standard library only, Python 3.10+.
|
|
33
|
+
- Polite by default: at most one request per second, a User-Agent naming the package, retries
|
|
34
|
+
on HTTP 429/5xx.
|
|
35
|
+
- An optional on-disk cache, so tests and repeated runs need no network.
|
|
36
|
+
|
|
37
|
+
## Install
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
pip install wndsn-tycho
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Examples
|
|
44
|
+
|
|
45
|
+
```python
|
|
46
|
+
from wndsn_tycho import Tycho
|
|
47
|
+
|
|
48
|
+
tycho = Tycho()
|
|
49
|
+
|
|
50
|
+
# Sun at 52.5° N on the June solstice
|
|
51
|
+
sun = tycho.sun(52.5, longitude=13.3, tz=1, date="2026-06-21")
|
|
52
|
+
sun.diurnal.noon_altitude # 60.93...
|
|
53
|
+
sun.longitudinal.sunrise_time # "03:44" (clock times are text, here UTC+1)
|
|
54
|
+
sun.longitudinal.astronomical_dawn # None: no astronomical night in June at 52.5°
|
|
55
|
+
|
|
56
|
+
# Without a date, give the declination; notes say what needs a date
|
|
57
|
+
tycho.sun(52.5, declination=20).notes
|
|
58
|
+
|
|
59
|
+
# Range: any two of angle, size and distance give the third (d = s / tan α)
|
|
60
|
+
tycho.range(alpha=2, size=1.8).distance # 51.545256
|
|
61
|
+
tycho.range(alpha=35, size=1.8, angular_unit="mil").distance
|
|
62
|
+
|
|
63
|
+
# Height from a known distance, h = d · tan α
|
|
64
|
+
tycho.height(100, 10).height # 17.632698
|
|
65
|
+
|
|
66
|
+
# Shadow square: umbra recta 12, umbra versa 8
|
|
67
|
+
s = tycho.shadow(umbra_recta=12, umbra_versa=8)
|
|
68
|
+
s.tan, s.arctan, s.complement # 0.666667, 33.690068, 56.309932
|
|
69
|
+
|
|
70
|
+
# Sight reduction
|
|
71
|
+
tycho.sight(52.5, 20, lha=40).hc # 45.198923...
|
|
72
|
+
|
|
73
|
+
# The Moon
|
|
74
|
+
moon = tycho.moon(date="2026-11-15", lat=52.5, lon=13.3)
|
|
75
|
+
moon.phase_of_moon.phase, moon.moon_of_the_day.moonrise
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Module-level shortcuts use one shared default client:
|
|
79
|
+
|
|
80
|
+
```python
|
|
81
|
+
import wndsn_tycho
|
|
82
|
+
|
|
83
|
+
wndsn_tycho.range(alpha=2, size=1.8).distance
|
|
84
|
+
wndsn_tycho.configure(cache=True) # change the default client
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
### Calculators
|
|
88
|
+
|
|
89
|
+
| Method | Computes |
|
|
90
|
+
|---|---|
|
|
91
|
+
| `sun(latitude, *, date, declination, longitude, tz, dst, sun_altitude)` | noon altitude, sunrise/sunset azimuths and times, twilight, equation of time, unequal hours |
|
|
92
|
+
| `star(latitude, *, declination, star, altitude)` | rising/setting azimuths, culminations, azimuth and hour angle at an altitude |
|
|
93
|
+
| `sight(latitude, declination, *, lha, gha, longitude, ho)` | computed altitude Hc, azimuth Zn, intercept |
|
|
94
|
+
| `moon(*, date, time, clock, utc, lat, lon, age, illum, wax)` | phase, position, moonrise/transit/moonset, unequal hours |
|
|
95
|
+
| `scale(scale, *, map_distance, map_unit, ground_distance, ground_unit)` | map ⇄ ground distance in every unit |
|
|
96
|
+
| `range(*, alpha, size, distance, multiplier, angular_unit, unit, solve)` | distance, size or angle; the multiplier 1/tan α; MIL/NATO-MIL/MOA |
|
|
97
|
+
| `height(known_distance, alpha, *, angular_unit)` | height from distance and angle |
|
|
98
|
+
| `dip(h1, *, h2, h1_unit, h2_unit)` | distance to the horizon, and at which a light is seen |
|
|
99
|
+
| `elevation(*, gamma, beta, size, a, b, c, unit)` | height and distance from two angles and a baseline |
|
|
100
|
+
| `shadow(*, umbra_recta, umbra_versa, angle, tan, cot)` | tan, cot, angle and its complement |
|
|
101
|
+
| `duv(*, x, y, u, v)` | CCT and Duv of a chromaticity |
|
|
102
|
+
|
|
103
|
+
Each returns a result dataclass (`SunResult`, `RangeResult`, ...) from `wndsn_tycho.results`.
|
|
104
|
+
Every result also has `input` (what Tycho was given), `notes` (Tycho's notes, a tuple),
|
|
105
|
+
`digits`, `raw` (the whole answer) and `as_dict()`.
|
|
106
|
+
|
|
107
|
+
Bad arguments raise `ValueError` or `TypeError` without a request: an unknown keyword, a latitude
|
|
108
|
+
of 95°, a size over Tycho's limit of 65536, three of range's three values. Input that only Tycho
|
|
109
|
+
can judge raises `TychoInputError` (with `.notes`). `TychoHTTPError` means Tycho could not be
|
|
110
|
+
reached or answered with an error.
|
|
111
|
+
|
|
112
|
+
### Raw queries
|
|
113
|
+
|
|
114
|
+
`get` sends any parameters unchecked and returns Tycho's answer as it is: parsed JSON, or the
|
|
115
|
+
text for XML and CSV.
|
|
116
|
+
|
|
117
|
+
```python
|
|
118
|
+
tycho.get("sun", latitude=52.5, date="2026-06-21") # dict with input, output, digits
|
|
119
|
+
tycho.get("range", {"alpha": 2, "size": 1.8}, fmt="csv")
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### Cache
|
|
123
|
+
|
|
124
|
+
Off by default. Turn it on for repeated runs, or to run tests offline:
|
|
125
|
+
|
|
126
|
+
```python
|
|
127
|
+
Tycho(cache=True) # the user cache directory (see user_cache_dir())
|
|
128
|
+
Tycho(cache="tests/tycho-cache") # a directory of your choice, e.g. committed with tests
|
|
129
|
+
Tycho(cache="tests/tycho-cache", mode="offline") # cache only: a miss raises CacheMiss
|
|
130
|
+
Tycho(cache="tests/tycho-cache", mode="refresh") # fetch everything again
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
The default mode is `fill`: read the cache, fetch only what is missing. Each query is one JSON
|
|
134
|
+
file, `<cache>/<calculator>/<key>.json`, holding the query, its URL, when it was fetched, and the
|
|
135
|
+
answer. The key is a hash of the canonical query, so the order of parameters and `1` vs `1.0`
|
|
136
|
+
don't matter. Refresh a committed cache after a Tycho release and read the diff.
|
|
137
|
+
|
|
138
|
+
### Options
|
|
139
|
+
|
|
140
|
+
`Tycho(cache=None, mode="fill", base_url="https://tycho.wndsn.com", digits=6, min_interval=1.0,
|
|
141
|
+
timeout=20.0, retries=2, user_agent=...)`
|
|
142
|
+
|
|
143
|
+
- `digits`: precision Tycho rounds to, 0–9 (Tycho's own default is 2). `moon` takes at most 4.
|
|
144
|
+
- `min_interval`: seconds between live requests. Against tycho.wndsn.com it can't be below 1;
|
|
145
|
+
all clients in a process share one throttle. A local copy of the site (`base_url`) may go faster.
|
|
146
|
+
|
|
147
|
+
### Command line
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
wndsn-tycho sun latitude=52.5 date=2026-06-21
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
wndsn-tycho range alpha=2 size=1.8 --format csv
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
```bash
|
|
158
|
+
python -m wndsn_tycho height known_distance=100 alpha=10 --cache
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
## The API
|
|
162
|
+
|
|
163
|
+
[docs/api.md](https://github.com/gqt0/wndsn-tycho/blob/main/docs/api.md) describes the HTTP API: parameters, limits, output fields, and the
|
|
164
|
+
quirks the client handles (`height`'s flat answer, `range`'s size limit, `sun` without a date,
|
|
165
|
+
`moon`'s digits).
|
|
166
|
+
|
|
167
|
+
## Tests
|
|
168
|
+
|
|
169
|
+
```bash
|
|
170
|
+
python -m unittest discover -s tests -t .
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
The unit tests run against a fake Tycho that serves real recorded answers, with no network. The
|
|
174
|
+
live test sends one query per calculator to tycho.wndsn.com (about 15 s):
|
|
175
|
+
|
|
176
|
+
```bash
|
|
177
|
+
TYCHO_LIVE=1 python -m unittest tests.test_live -v
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
## Versioning
|
|
181
|
+
|
|
182
|
+
[Semantic versioning](https://semver.org); the version is in `src/wndsn_tycho/_version.py`,
|
|
183
|
+
changes in [CHANGELOG.md](https://github.com/gqt0/wndsn-tycho/blob/main/CHANGELOG.md), and releases are tagged `vX.Y.Z`.
|
|
184
|
+
|
|
185
|
+
## Licence
|
|
186
|
+
|
|
187
|
+
MIT, see [LICENSE](https://github.com/gqt0/wndsn-tycho/blob/main/LICENSE).
|
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
# wndsn-tycho
|
|
2
|
+
|
|
3
|
+
A Python client for the [Tycho calculators](https://tycho.wndsn.com): the Sun, stars, sight
|
|
4
|
+
reduction, the Moon, map scale, range and height from angular size, dip of the horizon,
|
|
5
|
+
elevation, the shadow square, and Duv.
|
|
6
|
+
|
|
7
|
+
- One typed method per calculator, with arguments checked before anything is sent and
|
|
8
|
+
results as dataclasses with named fields.
|
|
9
|
+
- Standard library only, Python 3.10+.
|
|
10
|
+
- Polite by default: at most one request per second, a User-Agent naming the package, retries
|
|
11
|
+
on HTTP 429/5xx.
|
|
12
|
+
- An optional on-disk cache, so tests and repeated runs need no network.
|
|
13
|
+
|
|
14
|
+
## Install
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
pip install wndsn-tycho
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
## Examples
|
|
21
|
+
|
|
22
|
+
```python
|
|
23
|
+
from wndsn_tycho import Tycho
|
|
24
|
+
|
|
25
|
+
tycho = Tycho()
|
|
26
|
+
|
|
27
|
+
# Sun at 52.5° N on the June solstice
|
|
28
|
+
sun = tycho.sun(52.5, longitude=13.3, tz=1, date="2026-06-21")
|
|
29
|
+
sun.diurnal.noon_altitude # 60.93...
|
|
30
|
+
sun.longitudinal.sunrise_time # "03:44" (clock times are text, here UTC+1)
|
|
31
|
+
sun.longitudinal.astronomical_dawn # None: no astronomical night in June at 52.5°
|
|
32
|
+
|
|
33
|
+
# Without a date, give the declination; notes say what needs a date
|
|
34
|
+
tycho.sun(52.5, declination=20).notes
|
|
35
|
+
|
|
36
|
+
# Range: any two of angle, size and distance give the third (d = s / tan α)
|
|
37
|
+
tycho.range(alpha=2, size=1.8).distance # 51.545256
|
|
38
|
+
tycho.range(alpha=35, size=1.8, angular_unit="mil").distance
|
|
39
|
+
|
|
40
|
+
# Height from a known distance, h = d · tan α
|
|
41
|
+
tycho.height(100, 10).height # 17.632698
|
|
42
|
+
|
|
43
|
+
# Shadow square: umbra recta 12, umbra versa 8
|
|
44
|
+
s = tycho.shadow(umbra_recta=12, umbra_versa=8)
|
|
45
|
+
s.tan, s.arctan, s.complement # 0.666667, 33.690068, 56.309932
|
|
46
|
+
|
|
47
|
+
# Sight reduction
|
|
48
|
+
tycho.sight(52.5, 20, lha=40).hc # 45.198923...
|
|
49
|
+
|
|
50
|
+
# The Moon
|
|
51
|
+
moon = tycho.moon(date="2026-11-15", lat=52.5, lon=13.3)
|
|
52
|
+
moon.phase_of_moon.phase, moon.moon_of_the_day.moonrise
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Module-level shortcuts use one shared default client:
|
|
56
|
+
|
|
57
|
+
```python
|
|
58
|
+
import wndsn_tycho
|
|
59
|
+
|
|
60
|
+
wndsn_tycho.range(alpha=2, size=1.8).distance
|
|
61
|
+
wndsn_tycho.configure(cache=True) # change the default client
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### Calculators
|
|
65
|
+
|
|
66
|
+
| Method | Computes |
|
|
67
|
+
|---|---|
|
|
68
|
+
| `sun(latitude, *, date, declination, longitude, tz, dst, sun_altitude)` | noon altitude, sunrise/sunset azimuths and times, twilight, equation of time, unequal hours |
|
|
69
|
+
| `star(latitude, *, declination, star, altitude)` | rising/setting azimuths, culminations, azimuth and hour angle at an altitude |
|
|
70
|
+
| `sight(latitude, declination, *, lha, gha, longitude, ho)` | computed altitude Hc, azimuth Zn, intercept |
|
|
71
|
+
| `moon(*, date, time, clock, utc, lat, lon, age, illum, wax)` | phase, position, moonrise/transit/moonset, unequal hours |
|
|
72
|
+
| `scale(scale, *, map_distance, map_unit, ground_distance, ground_unit)` | map ⇄ ground distance in every unit |
|
|
73
|
+
| `range(*, alpha, size, distance, multiplier, angular_unit, unit, solve)` | distance, size or angle; the multiplier 1/tan α; MIL/NATO-MIL/MOA |
|
|
74
|
+
| `height(known_distance, alpha, *, angular_unit)` | height from distance and angle |
|
|
75
|
+
| `dip(h1, *, h2, h1_unit, h2_unit)` | distance to the horizon, and at which a light is seen |
|
|
76
|
+
| `elevation(*, gamma, beta, size, a, b, c, unit)` | height and distance from two angles and a baseline |
|
|
77
|
+
| `shadow(*, umbra_recta, umbra_versa, angle, tan, cot)` | tan, cot, angle and its complement |
|
|
78
|
+
| `duv(*, x, y, u, v)` | CCT and Duv of a chromaticity |
|
|
79
|
+
|
|
80
|
+
Each returns a result dataclass (`SunResult`, `RangeResult`, ...) from `wndsn_tycho.results`.
|
|
81
|
+
Every result also has `input` (what Tycho was given), `notes` (Tycho's notes, a tuple),
|
|
82
|
+
`digits`, `raw` (the whole answer) and `as_dict()`.
|
|
83
|
+
|
|
84
|
+
Bad arguments raise `ValueError` or `TypeError` without a request: an unknown keyword, a latitude
|
|
85
|
+
of 95°, a size over Tycho's limit of 65536, three of range's three values. Input that only Tycho
|
|
86
|
+
can judge raises `TychoInputError` (with `.notes`). `TychoHTTPError` means Tycho could not be
|
|
87
|
+
reached or answered with an error.
|
|
88
|
+
|
|
89
|
+
### Raw queries
|
|
90
|
+
|
|
91
|
+
`get` sends any parameters unchecked and returns Tycho's answer as it is: parsed JSON, or the
|
|
92
|
+
text for XML and CSV.
|
|
93
|
+
|
|
94
|
+
```python
|
|
95
|
+
tycho.get("sun", latitude=52.5, date="2026-06-21") # dict with input, output, digits
|
|
96
|
+
tycho.get("range", {"alpha": 2, "size": 1.8}, fmt="csv")
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### Cache
|
|
100
|
+
|
|
101
|
+
Off by default. Turn it on for repeated runs, or to run tests offline:
|
|
102
|
+
|
|
103
|
+
```python
|
|
104
|
+
Tycho(cache=True) # the user cache directory (see user_cache_dir())
|
|
105
|
+
Tycho(cache="tests/tycho-cache") # a directory of your choice, e.g. committed with tests
|
|
106
|
+
Tycho(cache="tests/tycho-cache", mode="offline") # cache only: a miss raises CacheMiss
|
|
107
|
+
Tycho(cache="tests/tycho-cache", mode="refresh") # fetch everything again
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
The default mode is `fill`: read the cache, fetch only what is missing. Each query is one JSON
|
|
111
|
+
file, `<cache>/<calculator>/<key>.json`, holding the query, its URL, when it was fetched, and the
|
|
112
|
+
answer. The key is a hash of the canonical query, so the order of parameters and `1` vs `1.0`
|
|
113
|
+
don't matter. Refresh a committed cache after a Tycho release and read the diff.
|
|
114
|
+
|
|
115
|
+
### Options
|
|
116
|
+
|
|
117
|
+
`Tycho(cache=None, mode="fill", base_url="https://tycho.wndsn.com", digits=6, min_interval=1.0,
|
|
118
|
+
timeout=20.0, retries=2, user_agent=...)`
|
|
119
|
+
|
|
120
|
+
- `digits`: precision Tycho rounds to, 0–9 (Tycho's own default is 2). `moon` takes at most 4.
|
|
121
|
+
- `min_interval`: seconds between live requests. Against tycho.wndsn.com it can't be below 1;
|
|
122
|
+
all clients in a process share one throttle. A local copy of the site (`base_url`) may go faster.
|
|
123
|
+
|
|
124
|
+
### Command line
|
|
125
|
+
|
|
126
|
+
```bash
|
|
127
|
+
wndsn-tycho sun latitude=52.5 date=2026-06-21
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
wndsn-tycho range alpha=2 size=1.8 --format csv
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
python -m wndsn_tycho height known_distance=100 alpha=10 --cache
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
## The API
|
|
139
|
+
|
|
140
|
+
[docs/api.md](https://github.com/gqt0/wndsn-tycho/blob/main/docs/api.md) describes the HTTP API: parameters, limits, output fields, and the
|
|
141
|
+
quirks the client handles (`height`'s flat answer, `range`'s size limit, `sun` without a date,
|
|
142
|
+
`moon`'s digits).
|
|
143
|
+
|
|
144
|
+
## Tests
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
python -m unittest discover -s tests -t .
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
The unit tests run against a fake Tycho that serves real recorded answers, with no network. The
|
|
151
|
+
live test sends one query per calculator to tycho.wndsn.com (about 15 s):
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
TYCHO_LIVE=1 python -m unittest tests.test_live -v
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
## Versioning
|
|
158
|
+
|
|
159
|
+
[Semantic versioning](https://semver.org); the version is in `src/wndsn_tycho/_version.py`,
|
|
160
|
+
changes in [CHANGELOG.md](https://github.com/gqt0/wndsn-tycho/blob/main/CHANGELOG.md), and releases are tagged `vX.Y.Z`.
|
|
161
|
+
|
|
162
|
+
## Licence
|
|
163
|
+
|
|
164
|
+
MIT, see [LICENSE](https://github.com/gqt0/wndsn-tycho/blob/main/LICENSE).
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# The Tycho API
|
|
2
|
+
|
|
3
|
+
Reference for the calculators at https://tycho.wndsn.com, as this package uses them.
|
|
4
|
+
The Python names are in the [README](../README.md); this page is about the HTTP API underneath.
|
|
5
|
+
|
|
6
|
+
## Pattern
|
|
7
|
+
|
|
8
|
+
```
|
|
9
|
+
GET https://tycho.wndsn.com/<calculator>/?<params>&calc=yes&format=json
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
- `calc=yes` is required. Without it, the page shows sample values for today's date.
|
|
13
|
+
- `format` is `json`, `xml` or `csv`; JSON and XML carry the same data. In JSON, numbers come
|
|
14
|
+
back as numbers, yes/no as `true`/`false`, times as text (`"07:21"`, `"+16:02"`), and a value
|
|
15
|
+
that doesn't exist is `null` (for example, sunrise during polar day). CSV is one header row
|
|
16
|
+
and one data row.
|
|
17
|
+
- `digits` is the display precision, 0–9 (default 2; `moon` 0–4). Inputs are echoed as given,
|
|
18
|
+
outputs are rounded to `digits`. The package asks for 6, so values are not rounded twice.
|
|
19
|
+
- The answer has `input` (what was given, under the parameter names), `output` (the results;
|
|
20
|
+
grouped where there are many, as on `sun` and `moon`), `notes` when there are any, and
|
|
21
|
+
`digits`.
|
|
22
|
+
- Invalid input returns `notes` (and `digits`) instead of `output`. The package raises
|
|
23
|
+
`TychoInputError` and doesn't cache that answer. Some answers carry `notes` *and* a partial
|
|
24
|
+
`output`; those are results, and the notes stay on the result.
|
|
25
|
+
- No API key is needed. Automated use is welcome at **at most one request per second**; the
|
|
26
|
+
package waits ≥ 1 s between live requests and retries HTTP 429/5xx twice.
|
|
27
|
+
- Field names are stable; the latest Tycho version is canonical. After a Tycho release, refresh
|
|
28
|
+
a cache once (`mode="refresh"`); a changed value then shows up as a diff in the cache files.
|
|
29
|
+
- Parameters that only affect the drawing (`side`, `layer`, `view`, `zoom`) are dropped from the
|
|
30
|
+
query.
|
|
31
|
+
|
|
32
|
+
## Calculators and parameters
|
|
33
|
+
|
|
34
|
+
| Calculator | Parameters |
|
|
35
|
+
|---|---|
|
|
36
|
+
| `sun` | `latitude`, `longitude`, `tz`, `dst`, `date`, `declination`, `sun_altitude` |
|
|
37
|
+
| `star` | `latitude`, `star`, `declination`, `altitude` |
|
|
38
|
+
| `sight` | `latitude`, `longitude`, `declination`, `gha`, `lha`, `ho` |
|
|
39
|
+
| `moon` | `date`, `time`, `utc`, `lat`, `lon`, `age`, `illum`, `wax`, `clock` |
|
|
40
|
+
| `scale` | `scale`, `map_unit`, `map_distance`, `ground_unit`, `ground_distance` |
|
|
41
|
+
| `range` | `size`, `alpha`, `angular_unit` (`deg`, `mil`, `natomil`, `moa`), `distance`, `multiplier`, `solve`, `unit` |
|
|
42
|
+
| `height` | `known_distance`, `angular_unit`, `alpha` |
|
|
43
|
+
| `dip` | `h1_unit`, `h1`, `h2_unit`, `h2` |
|
|
44
|
+
| `elevation` | `size`, `gamma`, `beta`, `a`, `b`, `c`, `unit` |
|
|
45
|
+
| `shadow` | `umbra_recta`, `umbra_versa`, `angle`, `tan`, `cot` |
|
|
46
|
+
| `duv` | `x`, `y`, `u`, `v` |
|
|
47
|
+
|
|
48
|
+
Limits:
|
|
49
|
+
|
|
50
|
+
- Known size or distance (`range`, `height`, and the size on `elevation`): greater than 0 and
|
|
51
|
+
up to 65536.
|
|
52
|
+
- Angles on `range` and `height`: up to 180° in every unit, i.e. 3141.59 MIL, 3200 NATO-MIL,
|
|
53
|
+
10800 MOA.
|
|
54
|
+
- Units: `scale` map `cm`, `mm`, `in`; ground `cm`, `mm`, `m`, `km`, `in`, `ft`, `mi`, `nm`.
|
|
55
|
+
`dip` `m` or `ft`. `range`/`elevation` `unit` only labels the lengths (`any` when not given).
|
|
56
|
+
|
|
57
|
+
### `sun` in detail
|
|
58
|
+
|
|
59
|
+
| Parameter | Meaning |
|
|
60
|
+
|---|---|
|
|
61
|
+
| `latitude` | degrees, −90…90, north positive |
|
|
62
|
+
| `longitude` | degrees, −180…180, east positive; together with `tz` it gives clock times |
|
|
63
|
+
| `tz` | time zone, hours from UTC, −12…14 |
|
|
64
|
+
| `dst` | daylight saving time, `0` (default) or `1` |
|
|
65
|
+
| `date` | `YYYY-MM-DD` |
|
|
66
|
+
| `declination` | known declination, −23.44…23.44; overrides the declination from `date` |
|
|
67
|
+
| `sun_altitude` | Sun altitude for the instantaneous values, −90…90 |
|
|
68
|
+
|
|
69
|
+
The `output` has four groups:
|
|
70
|
+
|
|
71
|
+
- `latitudinal`: equinox noon altitude, max/min altitude, June/December sunrise and sunset azimuths
|
|
72
|
+
- `diurnal`: day number, declination, sunrise/sunset azimuth, sunrise hour angle, noon altitude,
|
|
73
|
+
equation of time, sun hours, length of an unequal hour
|
|
74
|
+
- `longitudinal`: astronomical/nautical/civil dawn and dusk, sunrise, solar noon, sunset (clock times)
|
|
75
|
+
- `instantaneous`: hour angle, time to/from noon, Sun azimuth, shadow length (for `sun_altitude`)
|
|
76
|
+
|
|
77
|
+
Formulas the page gives:
|
|
78
|
+
- H = (90° − φ) + δ
|
|
79
|
+
- cos αsr = sin δ / cos φ
|
|
80
|
+
- cos τsr = −tan φ · tan δ (geometric)
|
|
81
|
+
- cos τ = (sin h − sin δ sin φ) / (cos δ cos φ)
|
|
82
|
+
- tan αs = sin τ / (sin φ cos τ − cos φ tan δ), with the azimuth measured from south
|
|
83
|
+
|
|
84
|
+
True sunrise and sunset use the τ(h) formula with h = −0.833°.
|
|
85
|
+
|
|
86
|
+
## Output fields
|
|
87
|
+
|
|
88
|
+
| Calculator | `output` fields |
|
|
89
|
+
|---|---|
|
|
90
|
+
| `sun` | see above; the field names are those of `wndsn_tycho.results.Sun*` |
|
|
91
|
+
| `star` | `rise_az_from_north`, `set_az_from_north`, `upper_culmination_alt`, `lower_culmination_alt`, `az_from_alt`, `ha_from_alt`, `time_from_culmination` |
|
|
92
|
+
| `sight` | `meridian_angle`, `meridian_angle_side`, `hc`, `z`, `zn`, `colatitude`, `polar_distance`, `zenith_distance`, `parallactic_angle`, `intercept`, `direction`, `foot_latitude`, `foot_longitude` |
|
|
93
|
+
| `moon` | groups `phase_of_moon`, `hours`, `position`, `moon_of_the_day`, `season` |
|
|
94
|
+
| `scale` | `map_cm`, `map_mm`, `map_in`, `ground_cm`, `ground_mm`, `ground_m`, `ground_km`, `ground_in`, `ground_ft`, `ground_mi`, `ground_nm` |
|
|
95
|
+
| `range` | `distance` (or `size`, `alpha`, whichever was solved for), `multiplier` (1/tan α), `degrees`, `mil`, `natomil`, `moa` |
|
|
96
|
+
| `height` | `height`, `multiplier`, `degrees`, `mil`, `natomil`, `moa` (flat, see below) |
|
|
97
|
+
| `dip` | `m1`, `ft1`, `m2`, `ft2`, `distance_km`, `distance_nm`, `distance_mi`, `distance_horizon_km`, `distance_horizon_nm`, `distance_horizon_mi` |
|
|
98
|
+
| `elevation` | `a`, `b`, `c`, `alpha`, `theta` |
|
|
99
|
+
| `shadow` | `tan` = versa / recta, `cot`, `arctan`, `complement` (= 90° − arctan) |
|
|
100
|
+
| `duv` | `u`, `v`, `u_prime`, `v_prime`, `duv`, `cct`, `inside_locus` |
|
|
101
|
+
|
|
102
|
+
## Quirks
|
|
103
|
+
|
|
104
|
+
- `sun` with `latitude` and `declination` only (no date) answers the latitudinal and diurnal
|
|
105
|
+
groups; `notes` then say that the equation of time and clock times need a date and a
|
|
106
|
+
longitude. The noon altitude is `90 − |φ − δ|`.
|
|
107
|
+
- `range`: any two of α, size and distance give the third. **The size must be ≤ 65536**: a
|
|
108
|
+
larger one returns `notes` *with* a partial `output` (no `distance`). Send lengths in a larger
|
|
109
|
+
unit (km, not m) if needed. The package refuses such a size before sending.
|
|
110
|
+
- `height` answers **flat**: the fields (`height`, `multiplier`, ...) are at the top level
|
|
111
|
+
next to the inputs, with no `input` / `output` wrapper, and an invalid input gives `""` rather
|
|
112
|
+
than notes. The package reads it into the same shape as every other result.
|
|
113
|
+
- `shadow`: older answers call `complement` `arccot`; the package reads both.
|
|
114
|
+
- `moon` accepts `digits` 0–4 only and silently answers with 1 digit above that; the package asks
|
|
115
|
+
for at most 4.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "wndsn-tycho"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "Python client for the Tycho calculators at tycho.wndsn.com (sun, star, sight, moon, range, shadow, ...)"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
requires-python = ">=3.10"
|
|
13
|
+
dependencies = []
|
|
14
|
+
keywords = ["astronomy", "navigation", "sun", "moon", "sight reduction", "rangefinding", "quadrant", "tycho", "wndsn"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Development Status :: 3 - Alpha",
|
|
17
|
+
"Intended Audience :: Science/Research",
|
|
18
|
+
"Operating System :: OS Independent",
|
|
19
|
+
"Programming Language :: Python :: 3",
|
|
20
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
21
|
+
"Topic :: Scientific/Engineering :: Astronomy",
|
|
22
|
+
"Typing :: Typed",
|
|
23
|
+
]
|
|
24
|
+
|
|
25
|
+
[project.urls]
|
|
26
|
+
Calculators = "https://tycho.wndsn.com"
|
|
27
|
+
Source = "https://github.com/gqt0/wndsn-tycho"
|
|
28
|
+
Documentation = "https://github.com/gqt0/wndsn-tycho/blob/main/docs/api.md"
|
|
29
|
+
Changelog = "https://github.com/gqt0/wndsn-tycho/blob/main/CHANGELOG.md"
|
|
30
|
+
Issues = "https://github.com/gqt0/wndsn-tycho/issues"
|
|
31
|
+
|
|
32
|
+
[project.scripts]
|
|
33
|
+
wndsn-tycho = "wndsn_tycho.cli:main"
|
|
34
|
+
|
|
35
|
+
[tool.setuptools.dynamic]
|
|
36
|
+
version = { attr = "wndsn_tycho._version.__version__" }
|
|
37
|
+
|
|
38
|
+
[tool.setuptools.package-data]
|
|
39
|
+
wndsn_tycho = ["py.typed"]
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
"""Python client for the Tycho calculators at https://tycho.wndsn.com.
|
|
2
|
+
|
|
3
|
+
>>> from wndsn_tycho import Tycho
|
|
4
|
+
>>> tycho = Tycho()
|
|
5
|
+
>>> tycho.range(alpha=2, size=1.8).distance
|
|
6
|
+
51.545256
|
|
7
|
+
|
|
8
|
+
Module-level shortcuts use one shared default client (no cache, at most one request per
|
|
9
|
+
second): ``wndsn_tycho.sun(52.5, date="2026-06-21")``. Change it with :func:`configure`.
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from __future__ import annotations
|
|
13
|
+
|
|
14
|
+
import functools
|
|
15
|
+
import inspect
|
|
16
|
+
import threading
|
|
17
|
+
from typing import Any, Optional
|
|
18
|
+
|
|
19
|
+
from ._version import __version__
|
|
20
|
+
from .calculators import Tycho
|
|
21
|
+
from .client import (
|
|
22
|
+
BASE_URL, CALCULATORS, DEFAULT_DIGITS, FORMATS, MIN_INTERVAL, MODES, USER_AGENT,
|
|
23
|
+
CacheMiss, Client, TychoError, TychoHTTPError, TychoInputError,
|
|
24
|
+
cache_key, canonical_params, user_cache_dir,
|
|
25
|
+
)
|
|
26
|
+
from .results import RESULT_TYPES, Result, parse
|
|
27
|
+
|
|
28
|
+
__all__ = [
|
|
29
|
+
"__version__", "Tycho", "Client", "configure", "default_client",
|
|
30
|
+
"TychoError", "CacheMiss", "TychoInputError", "TychoHTTPError",
|
|
31
|
+
"Result", "RESULT_TYPES", "parse", "canonical_params", "cache_key", "user_cache_dir",
|
|
32
|
+
"BASE_URL", "CALCULATORS", "DEFAULT_DIGITS", "FORMATS", "MIN_INTERVAL", "MODES", "USER_AGENT",
|
|
33
|
+
"get",
|
|
34
|
+
]
|
|
35
|
+
|
|
36
|
+
_default: Optional[Tycho] = None
|
|
37
|
+
_default_lock = threading.Lock()
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def default_client() -> Tycho:
|
|
41
|
+
"""The client the module-level shortcuts use (created on first use)."""
|
|
42
|
+
global _default
|
|
43
|
+
with _default_lock:
|
|
44
|
+
if _default is None:
|
|
45
|
+
_default = Tycho()
|
|
46
|
+
return _default
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def configure(**kwargs: Any) -> Tycho:
|
|
50
|
+
"""Replace the default client, e.g. ``configure(cache=True)``. Takes Tycho's arguments."""
|
|
51
|
+
global _default
|
|
52
|
+
client = Tycho(**kwargs)
|
|
53
|
+
with _default_lock:
|
|
54
|
+
_default = client
|
|
55
|
+
return client
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def get(calculator: str, params: Any = None, fmt: str = "json", **kwargs: Any) -> Any:
|
|
59
|
+
"""Raw query with the default client; see :meth:`Client.get`."""
|
|
60
|
+
return default_client().get(calculator, params, fmt, **kwargs)
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def _shortcut(name: str):
|
|
64
|
+
method = getattr(Tycho, name)
|
|
65
|
+
|
|
66
|
+
@functools.wraps(method)
|
|
67
|
+
def call(*args: Any, **kwargs: Any) -> Any:
|
|
68
|
+
return getattr(default_client(), name)(*args, **kwargs)
|
|
69
|
+
|
|
70
|
+
sig = inspect.signature(method)
|
|
71
|
+
call.__signature__ = sig.replace(parameters=list(sig.parameters.values())[1:]) # type: ignore[attr-defined]
|
|
72
|
+
return call
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
# Not in __all__: `range` would shadow the builtin on `from wndsn_tycho import *`.
|
|
76
|
+
sun = _shortcut("sun")
|
|
77
|
+
star = _shortcut("star")
|
|
78
|
+
sight = _shortcut("sight")
|
|
79
|
+
moon = _shortcut("moon")
|
|
80
|
+
scale = _shortcut("scale")
|
|
81
|
+
range = _shortcut("range") # noqa: A001
|
|
82
|
+
height = _shortcut("height")
|
|
83
|
+
dip = _shortcut("dip")
|
|
84
|
+
elevation = _shortcut("elevation")
|
|
85
|
+
shadow = _shortcut("shadow")
|
|
86
|
+
duv = _shortcut("duv")
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
__version__ = "0.1.0"
|