137 lines
3.6 KiB
Markdown
137 lines
3.6 KiB
Markdown
---
|
|
name: timezone-tools
|
|
description: Get current time in any timezone and convert times between timezones. Use when working with time, dates, timezones, scheduling across regions, or when user mentions specific cities/regions for time queries. Supports IANA timezone names.
|
|
---
|
|
|
|
# Timezone Tools
|
|
|
|
Get current time in any timezone and convert times between different timezones using IANA timezone database.
|
|
|
|
## Quick Start
|
|
|
|
### Get current time in a timezone
|
|
|
|
```bash
|
|
python scripts/get_time.py "America/New_York"
|
|
```
|
|
|
|
### Convert time between timezones
|
|
|
|
```bash
|
|
python scripts/convert_time.py "America/New_York" "14:30" "Australia/Perth"
|
|
```
|
|
|
|
### Search for timezone names
|
|
|
|
```bash
|
|
python scripts/list_timezones.py "perth"
|
|
```
|
|
|
|
## Instructions
|
|
|
|
When the user asks about time or timezones:
|
|
|
|
1. **For current time queries** (e.g., "What time is it in Tokyo?"):
|
|
- Use `get_time.py` with IANA timezone name
|
|
- If unsure of timezone name, search first with `list_timezones.py`
|
|
- Script outputs: timezone, datetime, day of week, DST status
|
|
|
|
2. **For time conversions** (e.g., "What's 2pm EST in Perth time?"):
|
|
- Use `convert_time.py` with source timezone, time (HH:MM 24-hour), target timezone
|
|
- Script shows source time, target time, and time difference
|
|
- Automatically handles DST changes
|
|
|
|
3. **For timezone searches**:
|
|
- Use `list_timezones.py` with city/country name
|
|
- Returns matching IANA timezone names
|
|
|
|
## Common Timezones Reference
|
|
|
|
For quick reference, see [data/common_timezones.json](data/common_timezones.json) which includes major cities worldwide, with Perth prominently featured.
|
|
|
|
**User's local timezone**: The scripts automatically detect your local timezone using `tzlocal`.
|
|
|
|
## Examples
|
|
|
|
### Example 1: Current time query
|
|
|
|
User: "What time is it in Perth?"
|
|
|
|
```bash
|
|
python scripts/list_timezones.py "perth"
|
|
# Output: Australia/Perth
|
|
|
|
python scripts/get_time.py "Australia/Perth"
|
|
# Output:
|
|
# Timezone: Australia/Perth
|
|
# Current time: 2025-11-07T15:30:45
|
|
# Day: Thursday
|
|
# DST: No
|
|
```
|
|
|
|
### Example 2: Time conversion
|
|
|
|
User: "I have a meeting at 2pm New York time, what time is that in Perth?"
|
|
|
|
```bash
|
|
python scripts/convert_time.py "America/New_York" "14:00" "Australia/Perth"
|
|
# Output:
|
|
# Source: America/New_York - 2025-11-07T14:00:00 (Thursday, DST: No)
|
|
# Target: Australia/Perth - 2025-11-08T03:00:00 (Friday, DST: No)
|
|
# Time difference: +13.0h
|
|
```
|
|
|
|
### Example 3: Multiple timezone search
|
|
|
|
User: "What are the timezone codes for London, Tokyo, and Sydney?"
|
|
|
|
```bash
|
|
python scripts/list_timezones.py "london"
|
|
python scripts/list_timezones.py "tokyo"
|
|
python scripts/list_timezones.py "sydney"
|
|
# Outputs:
|
|
# Europe/London
|
|
# Asia/Tokyo
|
|
# Australia/Sydney
|
|
```
|
|
|
|
## Time Format
|
|
|
|
- All times use **24-hour format** (HH:MM): `14:30` not `2:30 PM`
|
|
- ISO 8601 datetime format for output: `2025-11-07T14:30:45`
|
|
- IANA timezone names (e.g., `America/New_York`, not `EST`)
|
|
|
|
## Troubleshooting
|
|
|
|
### "Invalid timezone" error
|
|
|
|
- Use IANA timezone names: `America/New_York` not `EST` or `Eastern`
|
|
- Search with `list_timezones.py` if unsure
|
|
- Check [data/common_timezones.json](data/common_timezones.json) for reference
|
|
|
|
### "Invalid time format" error
|
|
|
|
- Use 24-hour format: `14:30` not `2:30 PM`
|
|
- Format must be `HH:MM` with colon separator
|
|
|
|
### Missing dependencies
|
|
|
|
Install required Python packages:
|
|
|
|
```bash
|
|
pip install tzlocal
|
|
```
|
|
|
|
## Dependencies
|
|
|
|
- Python 3.9+
|
|
- `tzlocal>=5.0` - for local timezone detection
|
|
- `zoneinfo` - built-in Python 3.9+ (IANA timezone database)
|
|
|
|
## Notes
|
|
|
|
- Scripts automatically handle Daylight Saving Time (DST)
|
|
- Local timezone is auto-detected from system
|
|
- All timezone data uses IANA Time Zone Database
|
|
- Perth, Australia timezone: `Australia/Perth` (UTC+8, no DST)
|