timefyi 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.
Files changed (18) hide show
  1. timefyi-0.1.0/.github/workflows/ci.yml +47 -0
  2. timefyi-0.1.0/.gitignore +14 -0
  3. timefyi-0.1.0/LICENSE +21 -0
  4. timefyi-0.1.0/PKG-INFO +257 -0
  5. timefyi-0.1.0/README.md +213 -0
  6. timefyi-0.1.0/pyproject.toml +92 -0
  7. timefyi-0.1.0/skills/time-tools/SKILL.md +53 -0
  8. timefyi-0.1.0/src/timefyi/__init__.py +54 -0
  9. timefyi-0.1.0/src/timefyi/api.py +84 -0
  10. timefyi-0.1.0/src/timefyi/cli.py +153 -0
  11. timefyi-0.1.0/src/timefyi/engine.py +287 -0
  12. timefyi-0.1.0/src/timefyi/mcp_server.py +158 -0
  13. timefyi-0.1.0/src/timefyi/py.typed +0 -0
  14. timefyi-0.1.0/tests/test_api.py +23 -0
  15. timefyi-0.1.0/tests/test_cli.py +47 -0
  16. timefyi-0.1.0/tests/test_engine.py +235 -0
  17. timefyi-0.1.0/tests/test_mcp.py +56 -0
  18. timefyi-0.1.0/uv.lock +1165 -0
timefyi-0.1.0/.github/workflows/ci.yml ADDED
@@ -0,0 +1,47 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ branches: [main]
8
+
9
+ jobs:
10
+ ci:
11
+ runs-on: ubuntu-latest
12
+ strategy:
13
+ matrix:
14
+ python-version: ["3.10", "3.12", "3.14"]
15
+ steps:
16
+ - uses: actions/checkout@v4
17
+ - uses: astral-sh/setup-uv@v5
18
+ with:
19
+ version: "latest"
20
+ - name: Set up Python ${{ matrix.python-version }}
21
+ run: uv python install ${{ matrix.python-version }}
22
+ - name: Install dependencies
23
+ run: uv sync --dev
24
+ - name: Lint
25
+ run: uv run ruff check src/ tests/
26
+ - name: Format check
27
+ run: uv run ruff format --check src/ tests/
28
+ - name: Type check
29
+ run: uv run mypy src/
30
+ - name: Test
31
+ run: uv run pytest
32
+
33
+ publish:
34
+ if: startsWith(github.ref, 'refs/tags/v')
35
+ needs: ci
36
+ runs-on: ubuntu-latest
37
+ permissions:
38
+ id-token: write
39
+ steps:
40
+ - uses: actions/checkout@v4
41
+ - uses: astral-sh/setup-uv@v5
42
+ with:
43
+ version: "latest"
44
+ - name: Build
45
+ run: uv build
46
+ - name: Publish to PyPI
47
+ uses: pypa/gh-action-pypi-publish@release/v1
timefyi-0.1.0/.gitignore ADDED
@@ -0,0 +1,14 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ *$py.class
4
+ *.egg-info/
5
+ dist/
6
+ build/
7
+ .eggs/
8
+ *.egg
9
+ .venv/
10
+ .mypy_cache/
11
+ .pytest_cache/
12
+ .ruff_cache/
13
+ *.so
14
+ .DS_Store
timefyi-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 FYIPedia
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.
timefyi-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,257 @@
1
+ Metadata-Version: 2.4
2
+ Name: timefyi
3
+ Version: 0.1.0
4
+ Summary: Pure Python timezone engine — current time, time differences, business hours overlap, sunrise/sunset. Zero dependencies core.
5
+ Project-URL: Homepage, https://timefyi.com
6
+ Project-URL: World Clock, https://timefyi.com/worldclock/
7
+ Project-URL: Documentation, https://timefyi.com/developers/
8
+ Project-URL: Repository, https://github.com/fyipedia/timefyi
9
+ Project-URL: Issues, https://github.com/fyipedia/timefyi/issues
10
+ Project-URL: Changelog, https://github.com/fyipedia/timefyi/releases
11
+ Author: FYIPedia
12
+ License-Expression: MIT
13
+ License-File: LICENSE
14
+ Keywords: business-hours,dst,sunrise,sunset,time,time-conversion,time-difference,timezone,utc,world-clock,zoneinfo
15
+ Classifier: Development Status :: 4 - Beta
16
+ Classifier: Environment :: Console
17
+ Classifier: Intended Audience :: Developers
18
+ Classifier: License :: OSI Approved :: MIT License
19
+ Classifier: Programming Language :: Python :: 3
20
+ Classifier: Programming Language :: Python :: 3.10
21
+ Classifier: Programming Language :: Python :: 3.11
22
+ Classifier: Programming Language :: Python :: 3.12
23
+ Classifier: Programming Language :: Python :: 3.13
24
+ Classifier: Programming Language :: Python :: 3.14
25
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
26
+ Classifier: Typing :: Typed
27
+ Requires-Python: >=3.10
28
+ Provides-Extra: all
29
+ Requires-Dist: astral>=3.2; extra == 'all'
30
+ Requires-Dist: httpx>=0.27; extra == 'all'
31
+ Requires-Dist: mcp>=1.0; extra == 'all'
32
+ Requires-Dist: rich>=13.0; extra == 'all'
33
+ Requires-Dist: typer>=0.15; extra == 'all'
34
+ Provides-Extra: api
35
+ Requires-Dist: httpx>=0.27; extra == 'api'
36
+ Provides-Extra: cli
37
+ Requires-Dist: rich>=13.0; extra == 'cli'
38
+ Requires-Dist: typer>=0.15; extra == 'cli'
39
+ Provides-Extra: mcp
40
+ Requires-Dist: mcp>=1.0; extra == 'mcp'
41
+ Provides-Extra: sun
42
+ Requires-Dist: astral>=3.2; extra == 'sun'
43
+ Description-Content-Type: text/markdown
44
+
45
+ # timefyi
46
+
47
+ [![PyPI](https://img.shields.io/pypi/v/timefyi)](https://pypi.org/project/timefyi/)
48
+ [![Python](https://img.shields.io/pypi/pyversions/timefyi)](https://pypi.org/project/timefyi/)
49
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
50
+
51
+ Pure Python timezone engine for developers. Look up current times in any [IANA timezone](https://timefyi.com/worldclock/), compute time differences, find [business hours overlap](https://timefyi.com/) across international teams, convert datetimes, and calculate sunrise/sunset -- all built on stdlib `zoneinfo` with zero core dependencies.
52
+
53
+ > **Check current times worldwide at [timefyi.com](https://timefyi.com/)** -- [world clock](https://timefyi.com/worldclock/), timezone comparisons, and business hours planning.
54
+
55
+ ## Install
56
+
57
+ ```bash
58
+ pip install timefyi # Core engine (zero deps, uses stdlib zoneinfo)
59
+ pip install "timefyi[sun]" # + Sunrise/sunset (astral)
60
+ pip install "timefyi[cli]" # + Command-line interface
61
+ pip install "timefyi[mcp]" # + MCP server for AI assistants
62
+ pip install "timefyi[api]" # + HTTP client for timefyi.com API
63
+ pip install "timefyi[all]" # Everything
64
+ ```
65
+
66
+ ## Quick Start
67
+
68
+ ```python
69
+ from timefyi import get_current_time, get_time_difference, convert_time
70
+
71
+ # Current time in Seoul
72
+ info = get_current_time("Asia/Seoul")
73
+ info.utc_offset # '+09:00'
74
+ info.current_time # datetime with KST
75
+ info.is_dst # False
76
+
77
+ # Time difference
78
+ diff = get_time_difference("America/New_York", "Asia/Seoul")
79
+ diff.difference_hours # 14.0 (or 13.0 during DST)
80
+ diff.difference_str # '+14h'
81
+
82
+ # Convert time across timezones
83
+ from datetime import datetime
84
+ converted = convert_time(datetime(2026, 3, 4, 14, 30), "America/New_York", "Asia/Seoul")
85
+ ```
86
+
87
+ ## Understanding Timezones
88
+
89
+ Timezones are governed by the [IANA Time Zone Database](https://www.iana.org/time-zones) (also called `tzdata` or the Olson database), maintained by a volunteer community and released several times per year. Each timezone is identified by a region/city string like `"Asia/Seoul"` or `"America/New_York"` rather than abbreviations like "KST" or "EST" -- because abbreviations are ambiguous ("CST" could mean Central Standard Time, China Standard Time, or Cuba Standard Time).
90
+
91
+ ```python
92
+ from timefyi import get_current_time
93
+
94
+ # Always use IANA identifiers, not abbreviations
95
+ seoul = get_current_time("Asia/Seoul") # UTC+9, no DST
96
+ new_york = get_current_time("America/New_York") # UTC-5 (EST) or UTC-4 (EDT)
97
+ london = get_current_time("Europe/London") # UTC+0 (GMT) or UTC+1 (BST)
98
+
99
+ # DST transitions change the offset
100
+ # New York is UTC-5 in winter, UTC-4 in summer
101
+ # The "America/New_York" identifier handles this automatically
102
+ ```
103
+
104
+ A UTC offset is the number of hours (and sometimes minutes) added to or subtracted from Coordinated Universal Time. Offsets range from UTC-12:00 to UTC+14:00, with several zones at 30- or 45-minute intervals (e.g., India at UTC+5:30, Nepal at UTC+5:45, Chatham Islands at UTC+12:45).
105
+
106
+ Daylight Saving Time (DST) shifts the local clock forward by one hour during summer months. Not all countries observe DST -- most of Africa, Asia, and South America do not. When DST transitions occur, they happen at different dates in different countries, making timezone arithmetic non-trivial.
107
+
108
+ ## Business Hours Across Timezones
109
+
110
+ Finding overlapping work hours is one of the most common timezone challenges for distributed teams. A team spanning New York, London, and Seoul has only a narrow window where all three are in standard business hours (9:00-17:00 local).
111
+
112
+ ```python
113
+ from timefyi import get_business_hours_overlap, get_hourly_comparison
114
+
115
+ # Find UTC hours where all timezones are in business hours (9-17 local)
116
+ overlap = get_business_hours_overlap(["America/New_York", "Europe/London", "Asia/Seoul"])
117
+ # Returns list of overlapping UTC hours
118
+
119
+ # Side-by-side hour mapping
120
+ comparison = get_hourly_comparison("America/New_York", "Asia/Seoul")
121
+ # Shows what each hour in New York corresponds to in Seoul
122
+ ```
123
+
124
+ ## Sunrise & Sunset
125
+
126
+ ```python
127
+ # Requires: pip install "timefyi[sun]"
128
+ from timefyi import get_sun_info
129
+
130
+ sun = get_sun_info(37.5665, 126.978, "Asia/Seoul")
131
+ sun.sunrise # datetime — sunrise time
132
+ sun.sunset # datetime — sunset time
133
+ ```
134
+
135
+ ## Command-Line Interface
136
+
137
+ ```bash
138
+ pip install "timefyi[cli]"
139
+
140
+ timefyi now America/New_York
141
+ timefyi diff America/New_York Asia/Seoul
142
+ timefyi convert "2026-03-04 14:30" America/New_York Asia/Seoul
143
+ timefyi overlap America/New_York Asia/Seoul Europe/London
144
+ timefyi sun --lat 37.5665 --lon 126.978 --tz Asia/Seoul
145
+ ```
146
+
147
+ ## MCP Server (Claude, Cursor, Windsurf)
148
+
149
+ Add timezone tools to any AI assistant that supports [Model Context Protocol](https://modelcontextprotocol.io/).
150
+
151
+ ```bash
152
+ pip install "timefyi[mcp]"
153
+ ```
154
+
155
+ Add to your `claude_desktop_config.json`:
156
+
157
+ ```json
158
+ {
159
+ "mcpServers": {
160
+ "timefyi": {
161
+ "command": "python",
162
+ "args": ["-m", "timefyi.mcp_server"]
163
+ }
164
+ }
165
+ }
166
+ ```
167
+
168
+ **Available tools**: `current_time`, `time_difference`, `convert_time`, `business_hours_overlap`, `sun_info`
169
+
170
+ ## REST API Client
171
+
172
+ ```python
173
+ pip install "timefyi[api]"
174
+ ```
175
+
176
+ ```python
177
+ from timefyi.api import TimeFYI
178
+
179
+ with TimeFYI() as client:
180
+ result = client.time("seoul")
181
+ diff = client.difference("new-york", "seoul")
182
+ ```
183
+
184
+ Full [API documentation](https://timefyi.com/developers/) at timefyi.com.
185
+
186
+ ## API Reference
187
+
188
+ ### Current Time & Conversion
189
+
190
+ | Function | Description |
191
+ |----------|-------------|
192
+ | `get_current_time(timezone) -> CityTimeInfo` | Current time with UTC offset, abbreviation, DST status |
193
+ | `convert_time(dt, from_tz, to_tz) -> datetime` | Convert datetime between timezones |
194
+ | `get_time_difference(tz1, tz2) -> TimeDifferenceInfo` | Hours difference between two timezones |
195
+
196
+ ### Business Hours & Comparison
197
+
198
+ | Function | Description |
199
+ |----------|-------------|
200
+ | `get_business_hours_overlap(timezones) -> list` | UTC hours where all timezones are in business hours |
201
+ | `get_hourly_comparison(tz1, tz2) -> list` | Side-by-side hour mapping between two timezones |
202
+
203
+ ### Sunrise & Sunset
204
+
205
+ | Function | Description |
206
+ |----------|-------------|
207
+ | `get_sun_info(lat, lon, timezone) -> SunInfo` | Dawn, sunrise, sunset, dusk, day length (requires `[sun]`) |
208
+
209
+ ### Formatting
210
+
211
+ | Function | Description |
212
+ |----------|-------------|
213
+ | `format_offset(hours) -> str` | Format UTC offset (e.g., "+09:00") |
214
+ | `format_difference(hours) -> str` | Format time difference (e.g., "+14h") |
215
+
216
+ ## Features
217
+
218
+ - **Current time** -- timezone lookup with UTC offset, abbreviation, DST status
219
+ - **Time difference** -- hours between any two IANA timezones
220
+ - **Time conversion** -- convert datetime across timezones
221
+ - **Business hours overlap** -- find UTC hours where multiple timezones overlap
222
+ - **Hourly comparison** -- side-by-side hour mapping between timezones
223
+ - **Sunrise/sunset** -- dawn, sunrise, sunset, dusk, day length (optional astral)
224
+ - **Formatting** -- UTC offset and difference strings
225
+ - **CLI** -- Rich terminal output with timezone tables
226
+ - **MCP server** -- 5 tools for AI assistants (Claude, Cursor, Windsurf)
227
+ - **REST API client** -- httpx-based client for [timefyi.com API](https://timefyi.com/developers/)
228
+ - **Zero dependencies** -- core engine uses only stdlib `zoneinfo` and `datetime`
229
+ - **Type-safe** -- full type annotations, `py.typed` marker (PEP 561)
230
+
231
+ ## FYIPedia Developer Tools
232
+
233
+ Part of the [FYIPedia](https://github.com/fyipedia) open-source developer tools ecosystem:
234
+
235
+ | Package | Description |
236
+ |---------|-------------|
237
+ | [colorfyi](https://pypi.org/project/colorfyi/) | Color conversion, [WCAG contrast](https://colorfyi.com/tools/contrast-checker/), harmonies, shades -- [colorfyi.com](https://colorfyi.com/) |
238
+ | [emojifyi](https://pypi.org/project/emojifyi/) | Emoji lookup, search, encoding -- [emojifyi.com](https://emojifyi.com/) |
239
+ | [symbolfyi](https://pypi.org/project/symbolfyi/) | Symbol encoding, Unicode properties -- [symbolfyi.com](https://symbolfyi.com/) |
240
+ | [unicodefyi](https://pypi.org/project/unicodefyi/) | Unicode character info, 17 encodings -- [unicodefyi.com](https://unicodefyi.com/) |
241
+ | [fontfyi](https://pypi.org/project/fontfyi/) | Google Fonts metadata, CSS, pairings -- [fontfyi.com](https://fontfyi.com/) |
242
+ | [distancefyi](https://pypi.org/project/distancefyi/) | Haversine distance, bearing, travel times -- [distancefyi.com](https://distancefyi.com/) |
243
+ | **[timefyi](https://pypi.org/project/timefyi/)** | **Timezone ops, time differences, business hours -- [timefyi.com](https://timefyi.com/)** |
244
+ | [namefyi](https://pypi.org/project/namefyi/) | Korean romanization, Five Elements -- [namefyi.com](https://namefyi.com/) |
245
+ | [unitfyi](https://pypi.org/project/unitfyi/) | Unit conversion, 200 units, 20 categories -- [unitfyi.com](https://unitfyi.com/) |
246
+ | [holidayfyi](https://pypi.org/project/holidayfyi/) | Holiday dates, Easter calculation -- [holidayfyi.com](https://holidayfyi.com/) |
247
+
248
+ ## Links
249
+
250
+ - [World Clock](https://timefyi.com/worldclock/) -- Current times in cities worldwide
251
+ - [REST API Documentation](https://timefyi.com/developers/) -- Free API
252
+ - [npm Package](https://www.npmjs.com/package/timefyi) -- TypeScript version
253
+ - [Source Code](https://github.com/fyipedia/timefyi) -- MIT licensed
254
+
255
+ ## License
256
+
257
+ MIT
timefyi-0.1.0/README.md ADDED
@@ -0,0 +1,213 @@
1
+ # timefyi
2
+
3
+ [![PyPI](https://img.shields.io/pypi/v/timefyi)](https://pypi.org/project/timefyi/)
4
+ [![Python](https://img.shields.io/pypi/pyversions/timefyi)](https://pypi.org/project/timefyi/)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
6
+
7
+ Pure Python timezone engine for developers. Look up current times in any [IANA timezone](https://timefyi.com/worldclock/), compute time differences, find [business hours overlap](https://timefyi.com/) across international teams, convert datetimes, and calculate sunrise/sunset -- all built on stdlib `zoneinfo` with zero core dependencies.
8
+
9
+ > **Check current times worldwide at [timefyi.com](https://timefyi.com/)** -- [world clock](https://timefyi.com/worldclock/), timezone comparisons, and business hours planning.
10
+
11
+ ## Install
12
+
13
+ ```bash
14
+ pip install timefyi # Core engine (zero deps, uses stdlib zoneinfo)
15
+ pip install "timefyi[sun]" # + Sunrise/sunset (astral)
16
+ pip install "timefyi[cli]" # + Command-line interface
17
+ pip install "timefyi[mcp]" # + MCP server for AI assistants
18
+ pip install "timefyi[api]" # + HTTP client for timefyi.com API
19
+ pip install "timefyi[all]" # Everything
20
+ ```
21
+
22
+ ## Quick Start
23
+
24
+ ```python
25
+ from timefyi import get_current_time, get_time_difference, convert_time
26
+
27
+ # Current time in Seoul
28
+ info = get_current_time("Asia/Seoul")
29
+ info.utc_offset # '+09:00'
30
+ info.current_time # datetime with KST
31
+ info.is_dst # False
32
+
33
+ # Time difference
34
+ diff = get_time_difference("America/New_York", "Asia/Seoul")
35
+ diff.difference_hours # 14.0 (or 13.0 during DST)
36
+ diff.difference_str # '+14h'
37
+
38
+ # Convert time across timezones
39
+ from datetime import datetime
40
+ converted = convert_time(datetime(2026, 3, 4, 14, 30), "America/New_York", "Asia/Seoul")
41
+ ```
42
+
43
+ ## Understanding Timezones
44
+
45
+ Timezones are governed by the [IANA Time Zone Database](https://www.iana.org/time-zones) (also called `tzdata` or the Olson database), maintained by a volunteer community and released several times per year. Each timezone is identified by a region/city string like `"Asia/Seoul"` or `"America/New_York"` rather than abbreviations like "KST" or "EST" -- because abbreviations are ambiguous ("CST" could mean Central Standard Time, China Standard Time, or Cuba Standard Time).
46
+
47
+ ```python
48
+ from timefyi import get_current_time
49
+
50
+ # Always use IANA identifiers, not abbreviations
51
+ seoul = get_current_time("Asia/Seoul") # UTC+9, no DST
52
+ new_york = get_current_time("America/New_York") # UTC-5 (EST) or UTC-4 (EDT)
53
+ london = get_current_time("Europe/London") # UTC+0 (GMT) or UTC+1 (BST)
54
+
55
+ # DST transitions change the offset
56
+ # New York is UTC-5 in winter, UTC-4 in summer
57
+ # The "America/New_York" identifier handles this automatically
58
+ ```
59
+
60
+ A UTC offset is the number of hours (and sometimes minutes) added to or subtracted from Coordinated Universal Time. Offsets range from UTC-12:00 to UTC+14:00, with several zones at 30- or 45-minute intervals (e.g., India at UTC+5:30, Nepal at UTC+5:45, Chatham Islands at UTC+12:45).
61
+
62
+ Daylight Saving Time (DST) shifts the local clock forward by one hour during summer months. Not all countries observe DST -- most of Africa, Asia, and South America do not. When DST transitions occur, they happen at different dates in different countries, making timezone arithmetic non-trivial.
63
+
64
+ ## Business Hours Across Timezones
65
+
66
+ Finding overlapping work hours is one of the most common timezone challenges for distributed teams. A team spanning New York, London, and Seoul has only a narrow window where all three are in standard business hours (9:00-17:00 local).
67
+
68
+ ```python
69
+ from timefyi import get_business_hours_overlap, get_hourly_comparison
70
+
71
+ # Find UTC hours where all timezones are in business hours (9-17 local)
72
+ overlap = get_business_hours_overlap(["America/New_York", "Europe/London", "Asia/Seoul"])
73
+ # Returns list of overlapping UTC hours
74
+
75
+ # Side-by-side hour mapping
76
+ comparison = get_hourly_comparison("America/New_York", "Asia/Seoul")
77
+ # Shows what each hour in New York corresponds to in Seoul
78
+ ```
79
+
80
+ ## Sunrise & Sunset
81
+
82
+ ```python
83
+ # Requires: pip install "timefyi[sun]"
84
+ from timefyi import get_sun_info
85
+
86
+ sun = get_sun_info(37.5665, 126.978, "Asia/Seoul")
87
+ sun.sunrise # datetime — sunrise time
88
+ sun.sunset # datetime — sunset time
89
+ ```
90
+
91
+ ## Command-Line Interface
92
+
93
+ ```bash
94
+ pip install "timefyi[cli]"
95
+
96
+ timefyi now America/New_York
97
+ timefyi diff America/New_York Asia/Seoul
98
+ timefyi convert "2026-03-04 14:30" America/New_York Asia/Seoul
99
+ timefyi overlap America/New_York Asia/Seoul Europe/London
100
+ timefyi sun --lat 37.5665 --lon 126.978 --tz Asia/Seoul
101
+ ```
102
+
103
+ ## MCP Server (Claude, Cursor, Windsurf)
104
+
105
+ Add timezone tools to any AI assistant that supports [Model Context Protocol](https://modelcontextprotocol.io/).
106
+
107
+ ```bash
108
+ pip install "timefyi[mcp]"
109
+ ```
110
+
111
+ Add to your `claude_desktop_config.json`:
112
+
113
+ ```json
114
+ {
115
+ "mcpServers": {
116
+ "timefyi": {
117
+ "command": "python",
118
+ "args": ["-m", "timefyi.mcp_server"]
119
+ }
120
+ }
121
+ }
122
+ ```
123
+
124
+ **Available tools**: `current_time`, `time_difference`, `convert_time`, `business_hours_overlap`, `sun_info`
125
+
126
+ ## REST API Client
127
+
128
+ ```python
129
+ pip install "timefyi[api]"
130
+ ```
131
+
132
+ ```python
133
+ from timefyi.api import TimeFYI
134
+
135
+ with TimeFYI() as client:
136
+ result = client.time("seoul")
137
+ diff = client.difference("new-york", "seoul")
138
+ ```
139
+
140
+ Full [API documentation](https://timefyi.com/developers/) at timefyi.com.
141
+
142
+ ## API Reference
143
+
144
+ ### Current Time & Conversion
145
+
146
+ | Function | Description |
147
+ |----------|-------------|
148
+ | `get_current_time(timezone) -> CityTimeInfo` | Current time with UTC offset, abbreviation, DST status |
149
+ | `convert_time(dt, from_tz, to_tz) -> datetime` | Convert datetime between timezones |
150
+ | `get_time_difference(tz1, tz2) -> TimeDifferenceInfo` | Hours difference between two timezones |
151
+
152
+ ### Business Hours & Comparison
153
+
154
+ | Function | Description |
155
+ |----------|-------------|
156
+ | `get_business_hours_overlap(timezones) -> list` | UTC hours where all timezones are in business hours |
157
+ | `get_hourly_comparison(tz1, tz2) -> list` | Side-by-side hour mapping between two timezones |
158
+
159
+ ### Sunrise & Sunset
160
+
161
+ | Function | Description |
162
+ |----------|-------------|
163
+ | `get_sun_info(lat, lon, timezone) -> SunInfo` | Dawn, sunrise, sunset, dusk, day length (requires `[sun]`) |
164
+
165
+ ### Formatting
166
+
167
+ | Function | Description |
168
+ |----------|-------------|
169
+ | `format_offset(hours) -> str` | Format UTC offset (e.g., "+09:00") |
170
+ | `format_difference(hours) -> str` | Format time difference (e.g., "+14h") |
171
+
172
+ ## Features
173
+
174
+ - **Current time** -- timezone lookup with UTC offset, abbreviation, DST status
175
+ - **Time difference** -- hours between any two IANA timezones
176
+ - **Time conversion** -- convert datetime across timezones
177
+ - **Business hours overlap** -- find UTC hours where multiple timezones overlap
178
+ - **Hourly comparison** -- side-by-side hour mapping between timezones
179
+ - **Sunrise/sunset** -- dawn, sunrise, sunset, dusk, day length (optional astral)
180
+ - **Formatting** -- UTC offset and difference strings
181
+ - **CLI** -- Rich terminal output with timezone tables
182
+ - **MCP server** -- 5 tools for AI assistants (Claude, Cursor, Windsurf)
183
+ - **REST API client** -- httpx-based client for [timefyi.com API](https://timefyi.com/developers/)
184
+ - **Zero dependencies** -- core engine uses only stdlib `zoneinfo` and `datetime`
185
+ - **Type-safe** -- full type annotations, `py.typed` marker (PEP 561)
186
+
187
+ ## FYIPedia Developer Tools
188
+
189
+ Part of the [FYIPedia](https://github.com/fyipedia) open-source developer tools ecosystem:
190
+
191
+ | Package | Description |
192
+ |---------|-------------|
193
+ | [colorfyi](https://pypi.org/project/colorfyi/) | Color conversion, [WCAG contrast](https://colorfyi.com/tools/contrast-checker/), harmonies, shades -- [colorfyi.com](https://colorfyi.com/) |
194
+ | [emojifyi](https://pypi.org/project/emojifyi/) | Emoji lookup, search, encoding -- [emojifyi.com](https://emojifyi.com/) |
195
+ | [symbolfyi](https://pypi.org/project/symbolfyi/) | Symbol encoding, Unicode properties -- [symbolfyi.com](https://symbolfyi.com/) |
196
+ | [unicodefyi](https://pypi.org/project/unicodefyi/) | Unicode character info, 17 encodings -- [unicodefyi.com](https://unicodefyi.com/) |
197
+ | [fontfyi](https://pypi.org/project/fontfyi/) | Google Fonts metadata, CSS, pairings -- [fontfyi.com](https://fontfyi.com/) |
198
+ | [distancefyi](https://pypi.org/project/distancefyi/) | Haversine distance, bearing, travel times -- [distancefyi.com](https://distancefyi.com/) |
199
+ | **[timefyi](https://pypi.org/project/timefyi/)** | **Timezone ops, time differences, business hours -- [timefyi.com](https://timefyi.com/)** |
200
+ | [namefyi](https://pypi.org/project/namefyi/) | Korean romanization, Five Elements -- [namefyi.com](https://namefyi.com/) |
201
+ | [unitfyi](https://pypi.org/project/unitfyi/) | Unit conversion, 200 units, 20 categories -- [unitfyi.com](https://unitfyi.com/) |
202
+ | [holidayfyi](https://pypi.org/project/holidayfyi/) | Holiday dates, Easter calculation -- [holidayfyi.com](https://holidayfyi.com/) |
203
+
204
+ ## Links
205
+
206
+ - [World Clock](https://timefyi.com/worldclock/) -- Current times in cities worldwide
207
+ - [REST API Documentation](https://timefyi.com/developers/) -- Free API
208
+ - [npm Package](https://www.npmjs.com/package/timefyi) -- TypeScript version
209
+ - [Source Code](https://github.com/fyipedia/timefyi) -- MIT licensed
210
+
211
+ ## License
212
+
213
+ MIT
timefyi-0.1.0/pyproject.toml ADDED
@@ -0,0 +1,92 @@
1
+ [project]
2
+ name = "timefyi"
3
+ version = "0.1.0"
4
+ description = "Pure Python timezone engine — current time, time differences, business hours overlap, sunrise/sunset. Zero dependencies core."
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ requires-python = ">=3.10"
8
+ authors = [{ name = "FYIPedia" }]
9
+ keywords = [
10
+ "timezone",
11
+ "time",
12
+ "utc",
13
+ "dst",
14
+ "sunrise",
15
+ "sunset",
16
+ "business-hours",
17
+ "time-difference",
18
+ "time-conversion",
19
+ "world-clock",
20
+ "zoneinfo",
21
+ ]
22
+ classifiers = [
23
+ "Development Status :: 4 - Beta",
24
+ "Intended Audience :: Developers",
25
+ "License :: OSI Approved :: MIT License",
26
+ "Programming Language :: Python :: 3",
27
+ "Programming Language :: Python :: 3.10",
28
+ "Programming Language :: Python :: 3.11",
29
+ "Programming Language :: Python :: 3.12",
30
+ "Programming Language :: Python :: 3.13",
31
+ "Programming Language :: Python :: 3.14",
32
+ "Topic :: Software Development :: Libraries :: Python Modules",
33
+ "Typing :: Typed",
34
+ "Environment :: Console",
35
+ ]
36
+ dependencies = []
37
+
38
+ [project.optional-dependencies]
39
+ sun = ["astral>=3.2"]
40
+ api = ["httpx>=0.27"]
41
+ cli = ["typer>=0.15", "rich>=13.0"]
42
+ mcp = ["mcp>=1.0"]
43
+ all = ["timefyi[sun,api,cli,mcp]"]
44
+
45
+ [project.scripts]
46
+ timefyi = "timefyi.cli:app"
47
+
48
+ [project.entry-points."mcp.servers"]
49
+ timefyi = "timefyi.mcp_server:mcp"
50
+
51
+ [project.urls]
52
+ Homepage = "https://timefyi.com"
53
+ "World Clock" = "https://timefyi.com/worldclock/"
54
+ Documentation = "https://timefyi.com/developers/"
55
+ Repository = "https://github.com/fyipedia/timefyi"
56
+ Issues = "https://github.com/fyipedia/timefyi/issues"
57
+ Changelog = "https://github.com/fyipedia/timefyi/releases"
58
+
59
+ [build-system]
60
+ requires = ["hatchling"]
61
+ build-backend = "hatchling.build"
62
+
63
+ [tool.hatch.build.targets.wheel]
64
+ packages = ["src/timefyi"]
65
+
66
+ [tool.pytest.ini_options]
67
+ testpaths = ["tests"]
68
+ addopts = "-v --tb=short"
69
+
70
+ [tool.ruff]
71
+ target-version = "py310"
72
+ line-length = 100
73
+
74
+ [tool.ruff.lint]
75
+ select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
76
+ ignore = ["RUF022"] # __all__ grouped by category
77
+
78
+ [tool.mypy]
79
+ python_version = "3.10"
80
+ strict = true
81
+
82
+ [dependency-groups]
83
+ dev = [
84
+ "astral>=3.2",
85
+ "httpx>=0.27",
86
+ "mcp>=1.0",
87
+ "mypy>=1.19.1",
88
+ "pytest>=9.0.2",
89
+ "rich>=13.0",
90
+ "ruff>=0.15.4",
91
+ "typer>=0.15",
92
+ ]