Metadata-Version: 2.4
Name: nexusclock
Version: 1.0.0
Summary: A powerful live clock library with timezone support and reverse time
Home-page: https://nexusclock.today
Author: Light Bulb Experiments
Author-email: lightbulb@example.com
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: rich>=10.0.0
Requires-Dist: python-dateutil>=2.8.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# NexusClock

A powerful live clock library with timezone support, custom dates, and reverse time functionality.

## How to install

```bash
python -m pip install nexusclock
```

## Quick Start

```python
from nexusclock import nexusclock

# Current time (12-hour format) - Just works!
nexusclock.nexusclock.today()

# Current time (24-hour format)
nexusclock.nexusclock.today()._24h()

# Time going backwards (reverse)
nexusclock.nexusclock.backwards()

# Reverse time in 24-hour format
nexusclock.nexusclock.backwards()._24h()

# Custom date/time
nexusclock.nexusclock.custom("2026-07-09 14:30:00")

# Custom with 24-hour format
nexusclock.nexusclock.custom("2026-07-09 14:30:00")._24h()

# Custom going backwards
nexusclock.nexusclock.custom("2026-07-09 14:30:00").backwards()

# Change timezone
nexusclock.nexusclock.changetz("America/New_York")

# Show help guide
nexusclock.nexusclock.help()
```

## Methods

| Method | Description | Example |
|--------|-------------|---------|
| `today()` | Current time (12-hour live) | `nexusclock.nexusclock.today()` |
| `today()._24h()` | Current time (24-hour live) | `nexusclock.nexusclock.today()._24h()` |
| `backwards()` | Time going backwards (12-hour) | `nexusclock.nexusclock.backwards()` |
| `backwards()._24h()` | Time going backwards (24-hour) | `nexusclock.nexusclock.backwards()._24h()` |
| `custom("YYYY-MM-DD HH:MM:SS")` | Custom date/time | `nexusclock.nexusclock.custom("2026-07-09 14:30:00")` |
| `custom()._24h()` | Custom in 24-hour format | `nexusclock.nexusclock.custom("2026-07-09 14:30:00")._24h()` |
| `custom().backwards()` | Custom going backwards | `nexusclock.nexusclock.custom("2026-07-09 14:30:00").backwards()` |
| `custom().backwards()._24h()` | Custom backwards in 24-hour | `nexusclock.nexusclock.custom("2026-07-09 14:30:00").backwards()._24h()` |
| `changetz("Timezone")` | Change timezone | `nexusclock.nexusclock.changetz("America/New_York")` |
| `changetz()._24h()` | Timezone with 24-hour format | `nexusclock.nexusclock.changetz("UTC")._24h()` |
| `changetz().backwards()` | Timezone going backwards | `nexusclock.nexusclock.changetz("Europe/London").backwards()` |
| `help()` | Show help guide | `nexusclock.nexusclock.help()` |

## Features

- ✅ **Live clock** with carriage return updates (no screen flicker)
- ✅ **12/24 hour formats** support
- ✅ **Reverse time** mode (time goes backwards)
- ✅ **Custom date/time** with validation
- ✅ **Timezone switching** with automatic offset
- ✅ **Automatic location detection** via IP geolocation
- ✅ **Ordinal suffixes** (st, nd, rd, th) for day numbers
- ✅ **Keyboard interrupt & EOF error handling** - no crashes!
- ✅ **Rich panel help guide** with beautiful formatting
- ✅ **Supports both class and instance methods**

## Example Output

```
The 9th of July, 2026, 4:52:38 PM, GMT+6 (Paltan, Bangladesh)
```

## Requirements

- Python 3.7+
- rich >= 10.0.0
- python-dateutil >= 2.8.0

## License

Copyright (c) 2026 Light Bulb Experiments

MIT License - see [LICENSE.txt](LICENSE.txt)

## Links

- **Homepage**: https://nexusclock.today
- **Target**: `nexusclock.nexusclock.today()`
- **Class**: `nexusclock`
- **Author**: Light Bulb Experiments

## Why NexusClock?

- 🚀 **Zero configuration** - Just import and use
- 🌍 **Location aware** - Automatically detects your timezone
- 🎯 **Simple API** - Chain methods for different formats
- ⚡ **Real-time updates** - Live clock with smooth updates
- 🛡️ **No crashes** - Handles all errors gracefully
- 📦 **Lightweight** - Minimal dependencies

## Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

## Support

For issues and feature requests, please open an issue on our GitHub repository.

---

**Made with ❤️ by Light Bulb Experiments**
