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.
- fishin-0.2.1/.gitignore +34 -0
- fishin-0.2.1/LICENSE +21 -0
- fishin-0.2.1/PKG-INFO +160 -0
- fishin-0.2.1/README.md +131 -0
- fishin-0.2.1/fishin/__init__.py +3 -0
- fishin-0.2.1/fishin/__main__.py +3 -0
- fishin-0.2.1/fishin/astro.py +283 -0
- fishin-0.2.1/fishin/cache.py +37 -0
- fishin-0.2.1/fishin/cli.py +274 -0
- fishin-0.2.1/fishin/config.py +46 -0
- fishin-0.2.1/fishin/geocode.py +87 -0
- fishin-0.2.1/fishin/render.py +395 -0
- fishin-0.2.1/fishin/stations.py +76 -0
- fishin-0.2.1/fishin/tides.py +198 -0
- fishin-0.2.1/fishin/weather.py +191 -0
- fishin-0.2.1/pyproject.toml +47 -0
fishin-0.2.1/.gitignore
ADDED
|
@@ -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,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
|