fishin 0.2.1__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,34 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+ *.egg-info/
6
+ .eggs/
7
+ build/
8
+ dist/
9
+ .pytest_cache/
10
+
11
+ # Virtual environments
12
+ .venv/
13
+ .venv-*/
14
+ venv/
15
+ env/
16
+
17
+ # Skyfield / JPL ephemeris — downloaded at runtime, never commit
18
+ *.bsp
19
+
20
+ # Local response/data caches
21
+ .cache/
22
+
23
+ # Editor / OS noise
24
+ .DS_Store
25
+ .vscode/
26
+ .idea/
27
+ *.swp
28
+ *.swo
29
+
30
+ # Project-local reference material — not part of the public repo
31
+ concept/
32
+
33
+ # Claude Code working dir
34
+ .claude/
fishin-0.2.1/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Steve Wasko
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.
fishin-0.2.1/PKG-INFO ADDED
@@ -0,0 +1,160 @@
1
+ Metadata-Version: 2.4
2
+ Name: fishin
3
+ Version: 0.2.1
4
+ Summary: Terminal solunar, tide, and weather forecast for the fishing / hunting day-planner crowd
5
+ Author: Steve Wasko
6
+ License-Expression: MIT
7
+ License-File: LICENSE
8
+ Keywords: cli,fishing,solunar,terminal,tide,weather
9
+ Classifier: Development Status :: 4 - Beta
10
+ Classifier: Environment :: Console
11
+ Classifier: Intended Audience :: End Users/Desktop
12
+ Classifier: Operating System :: MacOS
13
+ Classifier: Operating System :: POSIX
14
+ Classifier: Operating System :: POSIX :: Linux
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3 :: Only
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Programming Language :: Python :: 3.14
21
+ Classifier: Topic :: Utilities
22
+ Requires-Python: >=3.11
23
+ Requires-Dist: diskcache>=5
24
+ Requires-Dist: rich>=13
25
+ Requires-Dist: skyfield>=1.45
26
+ Requires-Dist: timezonefinder>=6
27
+ Requires-Dist: tzdata>=2024.1
28
+ Description-Content-Type: text/markdown
29
+
30
+ # fishin
31
+
32
+ Terminal solunar, tide, and weather forecast — one command, full picture, btop-dense layout.
33
+
34
+ `fishin` rolls a solunar app, a tide app (xtides-style), and `wttr.in` into a single
35
+ terminal panel. Solunar major/minor periods, sun/moon ephemera, NOAA tide
36
+ predictions, open-meteo weather, and a per-day "best fishing window" cross-correlation
37
+ all rendered in ~12 terminal lines per day.
38
+
39
+ ## Install
40
+
41
+ From PyPI (once published):
42
+
43
+ ```bash
44
+ pipx install fishin
45
+ ```
46
+
47
+ From a git checkout or this repo directly:
48
+
49
+ ```bash
50
+ pipx install git+https://github.com/sjwasko/fishin.git
51
+ ```
52
+
53
+ First run downloads the JPL DE421 ephemeris (~17 MB) into `~/.cache/fishin/ephemeris/`.
54
+ NOAA + open-meteo + Nominatim responses are cached at `~/.cache/fishin/responses/`.
55
+
56
+ Requires Python ≥ 3.11.
57
+
58
+ ## Quick start
59
+
60
+ ```bash
61
+ fishin # full panel for today, default location
62
+ fishin --city "sarasota fl" # geocode and resolve nearest tide station
63
+ fishin --city "..." --save # write resolved location to ~/.config/fishin/config.toml
64
+ fishin 7 # compact 7-day list view
65
+ fishin month # 30-day calendar grid with star ratings
66
+ fishin best 14 # next 14 days ranked, top 5 highlighted
67
+ ```
68
+
69
+ ## Modes
70
+
71
+ | Command | Output |
72
+ |---|---|
73
+ | `fishin` | One full panel for today |
74
+ | `fishin N` | N-day list view, one row per day |
75
+ | `fishin month` | Calendar grid for the month of `--date` |
76
+ | `fishin best N` | Next N days sorted by score, top 5 highlighted |
77
+ | `fishin --days N` | Legacy: render N full panels back-to-back |
78
+
79
+ Skip network fetches with `--no-tides` / `--no-weather` (e.g. offline or for quick recompute).
80
+
81
+ ## Configuration
82
+
83
+ `~/.config/fishin/config.toml`:
84
+
85
+ ```toml
86
+ location = "Sarasota, FL"
87
+ lat = 27.3366
88
+ lon = -82.5313
89
+ tz = "America/New_York"
90
+ station = "8726083"
91
+ ```
92
+
93
+ Resolution order: explicit flags > `--city` > config file > built-in Sarasota default.
94
+
95
+ Inland queries (>100 km from the nearest NOAA tide station) automatically
96
+ drop the tide section — there are no ocean tides in Austin.
97
+
98
+ ## How the "Best" ranking works
99
+
100
+ Every major/minor period is scored:
101
+
102
+ | Factor | Weight |
103
+ |---|---|
104
+ | Major period base | +4 |
105
+ | Minor period base | +2 |
106
+ | Sunrise overlap (±1 hr) | +3 |
107
+ | Sunset overlap (±1 hr) | +3 |
108
+ | Each H/L tide overlap (±30 min) | +2 |
109
+ | Calm wind (≤6 mph) | +1 |
110
+ | Strong wind (≥18 mph) | −1 |
111
+ | Rain ≥60% | −2 |
112
+
113
+ Top two windows are shown — first in bright amber, second dimmed.
114
+
115
+ ## Credits & data sources
116
+
117
+ `fishin` would not exist without the following free / open projects and public-data
118
+ services. Please respect each provider's terms when running this tool at scale.
119
+
120
+ ### Runtime APIs
121
+
122
+ | Source | Data | License / TOS |
123
+ |---|---|---|
124
+ | [NOAA CO-OPS](https://api.tidesandcurrents.noaa.gov/) | Tide predictions | US Government public domain |
125
+ | [open-meteo](https://open-meteo.com/) | Weather forecasts | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) |
126
+ | [OpenStreetMap Nominatim](https://nominatim.openstreetmap.org/) | Geocoding | [ODbL](https://opendatacommons.org/licenses/odbl/) · [usage policy](https://operations.osmfoundation.org/policies/nominatim/) |
127
+ | [NASA JPL DE421](https://ssd.jpl.nasa.gov/planets/eph_export.html) | Planetary ephemeris | Public domain |
128
+
129
+ The OSM Nominatim usage policy specifically asks clients to send a meaningful
130
+ User-Agent and cache responses; both are honored — geocode results are cached
131
+ on disk for 30 days.
132
+
133
+ ### Python dependencies
134
+
135
+ | Package | Role | License |
136
+ |---|---|---|
137
+ | [skyfield](https://rhodesmill.org/skyfield/) | Astronomy / ephemeris | MIT |
138
+ | [rich](https://github.com/Textualize/rich) | Terminal rendering | MIT |
139
+ | [diskcache](https://github.com/grantjenks/python-diskcache) | Response cache | Apache 2.0 |
140
+ | [timezonefinder](https://github.com/jannikmi/timezonefinder) | Lat/lon → IANA timezone | MIT |
141
+
142
+ ### Design inspiration
143
+
144
+ The visual language and information density of `fishin` borrow shamelessly from:
145
+
146
+ - [wttr.in](https://github.com/chubin/wttr.in) — terminal weather, the gold standard for "feels native to the shell"
147
+ - [btop](https://github.com/aristocratos/btop) — pack-every-pixel monitoring panels
148
+ - [xtides](https://flaterco.com/xtides/) — tide curve visualization and harmonic predictions
149
+ - [F&H Solunar Time](https://fhstime.com/) — daily forecast layout, day-rating ring, calendar grid
150
+
151
+ None of these projects are affiliated with `fishin`; we just learned from them.
152
+
153
+ ## License
154
+
155
+ [MIT](LICENSE). Fork, improve, redistribute — just keep the copyright notice.
156
+
157
+ ## Architecture
158
+
159
+ See [ARCHITECTURE.md](ARCHITECTURE.md) for the module layout, data flow, and
160
+ extension points if you'd like to contribute.
fishin-0.2.1/README.md ADDED
@@ -0,0 +1,131 @@
1
+ # fishin
2
+
3
+ Terminal solunar, tide, and weather forecast — one command, full picture, btop-dense layout.
4
+
5
+ `fishin` rolls a solunar app, a tide app (xtides-style), and `wttr.in` into a single
6
+ terminal panel. Solunar major/minor periods, sun/moon ephemera, NOAA tide
7
+ predictions, open-meteo weather, and a per-day "best fishing window" cross-correlation
8
+ all rendered in ~12 terminal lines per day.
9
+
10
+ ## Install
11
+
12
+ From PyPI (once published):
13
+
14
+ ```bash
15
+ pipx install fishin
16
+ ```
17
+
18
+ From a git checkout or this repo directly:
19
+
20
+ ```bash
21
+ pipx install git+https://github.com/sjwasko/fishin.git
22
+ ```
23
+
24
+ First run downloads the JPL DE421 ephemeris (~17 MB) into `~/.cache/fishin/ephemeris/`.
25
+ NOAA + open-meteo + Nominatim responses are cached at `~/.cache/fishin/responses/`.
26
+
27
+ Requires Python ≥ 3.11.
28
+
29
+ ## Quick start
30
+
31
+ ```bash
32
+ fishin # full panel for today, default location
33
+ fishin --city "sarasota fl" # geocode and resolve nearest tide station
34
+ fishin --city "..." --save # write resolved location to ~/.config/fishin/config.toml
35
+ fishin 7 # compact 7-day list view
36
+ fishin month # 30-day calendar grid with star ratings
37
+ fishin best 14 # next 14 days ranked, top 5 highlighted
38
+ ```
39
+
40
+ ## Modes
41
+
42
+ | Command | Output |
43
+ |---|---|
44
+ | `fishin` | One full panel for today |
45
+ | `fishin N` | N-day list view, one row per day |
46
+ | `fishin month` | Calendar grid for the month of `--date` |
47
+ | `fishin best N` | Next N days sorted by score, top 5 highlighted |
48
+ | `fishin --days N` | Legacy: render N full panels back-to-back |
49
+
50
+ Skip network fetches with `--no-tides` / `--no-weather` (e.g. offline or for quick recompute).
51
+
52
+ ## Configuration
53
+
54
+ `~/.config/fishin/config.toml`:
55
+
56
+ ```toml
57
+ location = "Sarasota, FL"
58
+ lat = 27.3366
59
+ lon = -82.5313
60
+ tz = "America/New_York"
61
+ station = "8726083"
62
+ ```
63
+
64
+ Resolution order: explicit flags > `--city` > config file > built-in Sarasota default.
65
+
66
+ Inland queries (>100 km from the nearest NOAA tide station) automatically
67
+ drop the tide section — there are no ocean tides in Austin.
68
+
69
+ ## How the "Best" ranking works
70
+
71
+ Every major/minor period is scored:
72
+
73
+ | Factor | Weight |
74
+ |---|---|
75
+ | Major period base | +4 |
76
+ | Minor period base | +2 |
77
+ | Sunrise overlap (±1 hr) | +3 |
78
+ | Sunset overlap (±1 hr) | +3 |
79
+ | Each H/L tide overlap (±30 min) | +2 |
80
+ | Calm wind (≤6 mph) | +1 |
81
+ | Strong wind (≥18 mph) | −1 |
82
+ | Rain ≥60% | −2 |
83
+
84
+ Top two windows are shown — first in bright amber, second dimmed.
85
+
86
+ ## Credits & data sources
87
+
88
+ `fishin` would not exist without the following free / open projects and public-data
89
+ services. Please respect each provider's terms when running this tool at scale.
90
+
91
+ ### Runtime APIs
92
+
93
+ | Source | Data | License / TOS |
94
+ |---|---|---|
95
+ | [NOAA CO-OPS](https://api.tidesandcurrents.noaa.gov/) | Tide predictions | US Government public domain |
96
+ | [open-meteo](https://open-meteo.com/) | Weather forecasts | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) |
97
+ | [OpenStreetMap Nominatim](https://nominatim.openstreetmap.org/) | Geocoding | [ODbL](https://opendatacommons.org/licenses/odbl/) · [usage policy](https://operations.osmfoundation.org/policies/nominatim/) |
98
+ | [NASA JPL DE421](https://ssd.jpl.nasa.gov/planets/eph_export.html) | Planetary ephemeris | Public domain |
99
+
100
+ The OSM Nominatim usage policy specifically asks clients to send a meaningful
101
+ User-Agent and cache responses; both are honored — geocode results are cached
102
+ on disk for 30 days.
103
+
104
+ ### Python dependencies
105
+
106
+ | Package | Role | License |
107
+ |---|---|---|
108
+ | [skyfield](https://rhodesmill.org/skyfield/) | Astronomy / ephemeris | MIT |
109
+ | [rich](https://github.com/Textualize/rich) | Terminal rendering | MIT |
110
+ | [diskcache](https://github.com/grantjenks/python-diskcache) | Response cache | Apache 2.0 |
111
+ | [timezonefinder](https://github.com/jannikmi/timezonefinder) | Lat/lon → IANA timezone | MIT |
112
+
113
+ ### Design inspiration
114
+
115
+ The visual language and information density of `fishin` borrow shamelessly from:
116
+
117
+ - [wttr.in](https://github.com/chubin/wttr.in) — terminal weather, the gold standard for "feels native to the shell"
118
+ - [btop](https://github.com/aristocratos/btop) — pack-every-pixel monitoring panels
119
+ - [xtides](https://flaterco.com/xtides/) — tide curve visualization and harmonic predictions
120
+ - [F&H Solunar Time](https://fhstime.com/) — daily forecast layout, day-rating ring, calendar grid
121
+
122
+ None of these projects are affiliated with `fishin`; we just learned from them.
123
+
124
+ ## License
125
+
126
+ [MIT](LICENSE). Fork, improve, redistribute — just keep the copyright notice.
127
+
128
+ ## Architecture
129
+
130
+ See [ARCHITECTURE.md](ARCHITECTURE.md) for the module layout, data flow, and
131
+ extension points if you'd like to contribute.
@@ -0,0 +1,3 @@
1
+ """fishin — terminal solunar, tide & weather forecast."""
2
+
3
+ __version__ = "0.2.1"
@@ -0,0 +1,3 @@
1
+ from .cli import main
2
+
3
+ raise SystemExit(main())
@@ -0,0 +1,283 @@
1
+ """Astronomy and day-building.
2
+
3
+ Pure computation — no terminal output, no argparse. Given a date, lat/lon, and
4
+ timezone, returns a dict describing the day's solunar events, periods, and
5
+ rating. The skyfield ephemeris is loaded lazily and cached at module scope so
6
+ multi-day runs don't repay the cost.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import math
12
+ import os
13
+ from datetime import datetime, timedelta, date
14
+ from pathlib import Path
15
+ from zoneinfo import ZoneInfo
16
+
17
+ from skyfield.api import Loader, wgs84
18
+ from skyfield import almanac
19
+
20
+
21
+ MAJOR_HOURS = 3.0 # 1.5hr each side of moon transit / antitransit
22
+ MINOR_HOURS = 2.0 # 1hr each side of moonrise / moonset
23
+
24
+ _ts = None
25
+ _eph = None
26
+
27
+
28
+ def _ephemeris_dir() -> Path:
29
+ base = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache"))
30
+ return base / "fishin" / "ephemeris"
31
+
32
+
33
+ def _load_skyfield():
34
+ """Lazy-load skyfield's timescale and the DE421 ephemeris.
35
+
36
+ The ~17MB ephemeris is parked under `~/.cache/fishin/ephemeris/` so it
37
+ doesn't litter whatever directory the user happens to run `fishin` from,
38
+ and so it survives across invocations.
39
+ """
40
+ global _ts, _eph
41
+ if _ts is None:
42
+ path = _ephemeris_dir()
43
+ path.mkdir(parents=True, exist_ok=True)
44
+ loader = Loader(str(path))
45
+ _ts = loader.timescale()
46
+ _eph = loader("de421.bsp")
47
+ return _ts, _eph
48
+
49
+
50
+ # ---------------------------------------------------------------- moon phase
51
+
52
+ def phase_name(deg: float) -> tuple[str, str]:
53
+ """Return (name, symbol). Named phases (New, Quarters, Full) get tight ±5°
54
+ windows; crescent / gibbous fill the gaps."""
55
+ a = deg % 360
56
+ if a < 5 or a >= 355:
57
+ return "New Moon", "🌑"
58
+ if a < 85:
59
+ return "Waxing Crescent", "🌒"
60
+ if a < 95:
61
+ return "First Quarter", "🌓"
62
+ if a < 175:
63
+ return "Waxing Gibbous", "🌔"
64
+ if a < 185:
65
+ return "Full Moon", "🌕"
66
+ if a < 265:
67
+ return "Waning Gibbous", "🌖"
68
+ if a < 275:
69
+ return "Last Quarter", "🌗"
70
+ return "Waning Crescent", "🌘"
71
+
72
+
73
+ def phase_score(deg: float) -> float:
74
+ # 1.0 at new and full, 0.0 at quarters
75
+ return abs(math.cos(math.radians(deg)))
76
+
77
+
78
+ # ---------------------------------------------------------------- events
79
+
80
+ def find_events(target_date: date, lat: float, lon: float, tz: ZoneInfo) -> dict:
81
+ ts, eph = _load_skyfield()
82
+ location = wgs84.latlon(lat, lon)
83
+
84
+ start_local = datetime(target_date.year, target_date.month, target_date.day,
85
+ tzinfo=tz)
86
+ end_local = start_local + timedelta(days=1)
87
+ pad = timedelta(hours=4)
88
+
89
+ t0 = ts.from_datetime(start_local - pad)
90
+ t1 = ts.from_datetime(end_local + pad)
91
+
92
+ def in_day(t):
93
+ local = t.utc_datetime().astimezone(tz)
94
+ return start_local <= local < end_local
95
+
96
+ # Sunrise / sunset
97
+ f_sun = almanac.sunrise_sunset(eph, location)
98
+ sun_times, sun_events = almanac.find_discrete(t0, t1, f_sun)
99
+ sunrise = next((t for t, e in zip(sun_times, sun_events) if e == 1 and in_day(t)), None)
100
+ sunset = next((t for t, e in zip(sun_times, sun_events) if e == 0 and in_day(t)), None)
101
+
102
+ # Moonrise / moonset
103
+ f_moon = almanac.risings_and_settings(eph, eph["moon"], location)
104
+ moon_times, moon_events = almanac.find_discrete(t0, t1, f_moon)
105
+ moonrise = next((t for t, e in zip(moon_times, moon_events) if e == 1 and in_day(t)), None)
106
+ moonset = next((t for t, e in zip(moon_times, moon_events) if e == 0 and in_day(t)), None)
107
+
108
+ # Sun meridian transit (solar noon)
109
+ f_sun_mt = almanac.meridian_transits(eph, eph["sun"], location)
110
+ smt, sme = almanac.find_discrete(t0, t1, f_sun_mt)
111
+ solar_noon = next((t for t, e in zip(smt, sme) if e == 1 and in_day(t)), None)
112
+
113
+ # Moon meridian transits: upper (overhead) and lower (antitransit, underfoot)
114
+ f_moon_mt = almanac.meridian_transits(eph, eph["moon"], location)
115
+ mmt, mme = almanac.find_discrete(t0, t1, f_moon_mt)
116
+ transits = [t for t, e in zip(mmt, mme) if e == 1 and in_day(t)]
117
+ antitransits = [t for t, e in zip(mmt, mme) if e == 0 and in_day(t)]
118
+
119
+ # Moon phase at local noon
120
+ noon = start_local + timedelta(hours=12)
121
+ phase_deg = almanac.moon_phase(eph, ts.from_datetime(noon)).degrees
122
+
123
+ def tolocal(t):
124
+ if t is None:
125
+ return None
126
+ return t.utc_datetime().astimezone(tz)
127
+
128
+ return {
129
+ "date": target_date,
130
+ "sunrise": tolocal(sunrise),
131
+ "solar_noon": tolocal(solar_noon),
132
+ "sunset": tolocal(sunset),
133
+ "moonrise": tolocal(moonrise),
134
+ "moonset": tolocal(moonset),
135
+ "transits": [tolocal(t) for t in transits],
136
+ "antitransits": [tolocal(t) for t in antitransits],
137
+ "phase_deg": phase_deg,
138
+ }
139
+
140
+
141
+ # ---------------------------------------------------------------- periods
142
+
143
+ def period_around(center: datetime, hours: float) -> tuple[datetime, datetime]:
144
+ half = timedelta(hours=hours / 2)
145
+ return (center - half, center + half)
146
+
147
+
148
+ def overlaps(a_start, a_end, b_start, b_end) -> bool:
149
+ return a_start < b_end and b_start < a_end
150
+
151
+
152
+ def build_day(target_date: date, lat: float, lon: float, tz_name: str) -> dict:
153
+ tz = ZoneInfo(tz_name)
154
+ ev = find_events(target_date, lat, lon, tz)
155
+
156
+ majors = []
157
+ for t in ev["transits"]:
158
+ majors.append(period_around(t, MAJOR_HOURS))
159
+ for t in ev["antitransits"]:
160
+ majors.append(period_around(t, MAJOR_HOURS))
161
+ majors.sort()
162
+
163
+ minors = []
164
+ if ev["moonrise"]:
165
+ minors.append(period_around(ev["moonrise"], MINOR_HOURS))
166
+ if ev["moonset"]:
167
+ minors.append(period_around(ev["moonset"], MINOR_HOURS))
168
+ minors.sort()
169
+
170
+ phase_pct = phase_score(ev["phase_deg"])
171
+ coincidence = 0.0
172
+ if ev["sunrise"] and ev["sunset"]:
173
+ win = timedelta(hours=1)
174
+ for p_start, p_end in majors + minors:
175
+ if overlaps(p_start, p_end, ev["sunrise"] - win, ev["sunrise"] + win):
176
+ coincidence += 0.15
177
+ if overlaps(p_start, p_end, ev["sunset"] - win, ev["sunset"] + win):
178
+ coincidence += 0.15
179
+ coincidence = min(coincidence, 0.4)
180
+
181
+ # Base 15% + phase up to 60% + coincidence up to 25%
182
+ score = min(1.0, 0.15 + 0.60 * phase_pct + 0.625 * coincidence)
183
+
184
+ if score >= 0.85:
185
+ rating = "Excellent"
186
+ elif score >= 0.65:
187
+ rating = "Good"
188
+ elif score >= 0.45:
189
+ rating = "Average"
190
+ else:
191
+ rating = "Poor"
192
+
193
+ pname, psymbol = phase_name(ev["phase_deg"])
194
+ return {**ev, "majors": majors, "minors": minors, "score": score,
195
+ "rating": rating, "phase_name": pname, "phase_symbol": psymbol}
196
+
197
+
198
+ # --------------------------------------------------------------- windows
199
+
200
+ # Window scoring: major/minor base + weighted overlap factors. Tuned so that
201
+ # a minor with two strong factors (e.g. sunrise + low tide) can outrank a lone
202
+ # major — which matches actual fishing wisdom.
203
+ _BASE_MAJOR = 4
204
+ _BASE_MINOR = 2
205
+ _W_SUN = 3 # sunrise or sunset within 1hr of the period
206
+ _W_TIDE = 2 # each H/L within 30min of the period
207
+ _W_CALM = 1
208
+ _W_WIND = -1
209
+ _W_RAIN = -2
210
+
211
+ _SUN_WIN = timedelta(hours=1)
212
+ _TIDE_WIN = timedelta(minutes=30)
213
+
214
+
215
+ def _weather_factor(day: dict, start: datetime, end: datetime) -> dict | None:
216
+ """Pick a single weather note for the window from the closest sample."""
217
+ wx = day.get("weather")
218
+ if not wx:
219
+ return None
220
+ midpoint = start + (end - start) / 2
221
+ samples = [p[1] for p in wx.get("periods", []) if p[1]]
222
+ if not samples:
223
+ return None
224
+ closest = min(samples, key=lambda s: abs(s["time"] - midpoint))
225
+
226
+ if closest["precip_prob"] >= 60:
227
+ return {"type": "weather", "subtype": "rain",
228
+ "value": closest["precip_prob"], "bonus": _W_RAIN}
229
+ if closest["wind_mph"] >= 18:
230
+ return {"type": "weather", "subtype": "wind",
231
+ "value": closest["wind_mph"], "bonus": _W_WIND}
232
+ if closest["wind_mph"] <= 6:
233
+ return {"type": "weather", "subtype": "calm",
234
+ "value": closest["wind_mph"], "bonus": _W_CALM}
235
+ return None
236
+
237
+
238
+ def _score_window(label: str, period: tuple, day: dict, base: int) -> dict:
239
+ s, e = period
240
+ score = base
241
+ factors: list[dict] = []
242
+
243
+ if day.get("sunrise") and overlaps(s, e,
244
+ day["sunrise"] - _SUN_WIN,
245
+ day["sunrise"] + _SUN_WIN):
246
+ factors.append({"type": "sunrise"})
247
+ score += _W_SUN
248
+ if day.get("sunset") and overlaps(s, e,
249
+ day["sunset"] - _SUN_WIN,
250
+ day["sunset"] + _SUN_WIN):
251
+ factors.append({"type": "sunset"})
252
+ score += _W_SUN
253
+
254
+ tide_events = (day.get("tides") or {}).get("events") or []
255
+ for ev in tide_events:
256
+ if overlaps(s, e, ev["time"] - _TIDE_WIN, ev["time"] + _TIDE_WIN):
257
+ factors.append({"type": "tide", "kind": ev["kind"],
258
+ "time": ev["time"], "height": ev["height"]})
259
+ score += _W_TIDE
260
+
261
+ wf = _weather_factor(day, s, e)
262
+ if wf:
263
+ factors.append(wf)
264
+ score += wf["bonus"]
265
+
266
+ return {"label": label, "period": period, "factors": factors, "score": score}
267
+
268
+
269
+ def evaluate_windows(day: dict) -> list[dict]:
270
+ """Score and rank every major/minor period for the day.
271
+
272
+ Returns a list of window dicts sorted by score descending (with earlier
273
+ starts breaking ties). Each window's `factors` list captures every overlap
274
+ (sunrise/sunset/tide/weather) that contributed to its score, so the
275
+ renderer can spell them out for the angler.
276
+ """
277
+ windows: list[dict] = []
278
+ for p in day.get("majors", []):
279
+ windows.append(_score_window("Major", p, day, _BASE_MAJOR))
280
+ for p in day.get("minors", []):
281
+ windows.append(_score_window("Minor", p, day, _BASE_MINOR))
282
+ windows.sort(key=lambda w: (-w["score"], w["period"][0]))
283
+ return windows
@@ -0,0 +1,37 @@
1
+ """Disk-backed response cache for tide & weather fetches.
2
+
3
+ `diskcache` gives us a pickle-backed shelf with per-entry TTLs and zero ceremony.
4
+ Tide predictions are deterministic and cached for a year; weather forecasts get
5
+ 1h for today/future and a long TTL for past dates (forecasts no longer update).
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import os
11
+ from datetime import date
12
+ from functools import lru_cache
13
+ from pathlib import Path
14
+
15
+ import diskcache
16
+
17
+
18
+ YEAR_SECONDS = 365 * 24 * 3600
19
+ HOUR_SECONDS = 3600
20
+
21
+
22
+ def _cache_dir() -> Path:
23
+ base = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache"))
24
+ return base / "fishin" / "responses"
25
+
26
+
27
+ @lru_cache(maxsize=1)
28
+ def get_cache() -> diskcache.Cache:
29
+ path = _cache_dir()
30
+ path.mkdir(parents=True, exist_ok=True)
31
+ return diskcache.Cache(str(path))
32
+
33
+
34
+ def weather_ttl(target_date: date) -> int:
35
+ """Past dates: forecast no longer updates, cache effectively forever.
36
+ Today/future: hourly model run, so 1h TTL keeps things fresh."""
37
+ return YEAR_SECONDS if target_date < date.today() else HOUR_SECONDS