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.
@@ -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,4 @@
1
+ include CHANGELOG.md
2
+ include tests/__init__.py tests/fake.py
3
+ recursive-include tests/fixtures *.json
4
+ recursive-include docs *.md
@@ -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,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -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,3 @@
1
+ from .cli import main
2
+
3
+ raise SystemExit(main())
@@ -0,0 +1 @@
1
+ __version__ = "0.1.0"