nexusclock 1.0.0__tar.gz

nexusclock-1.0.0/LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Light Bulb Experiments
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nexusclock-1.0.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include LICENSE.txt
+include pyproject.toml
+recursive-include nexusclock *.py

nexusclock-1.0.0/PKG-INFO

@@ -0,0 +1,146 @@
+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**

nexusclock-1.0.0/README.md

@@ -0,0 +1,118 @@
+# 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**

nexusclock-1.0.0/nexusclock/__init__.py

@@ -0,0 +1,8 @@
+"""
+NexusClock - Live clock library with timezone support
+"""
+
+from .nexusclock import nexusclock
+
+__all__ = ["nexusclock"]
+__version__ = "1.0.0"

nexusclock-1.0.0/nexusclock/nexusclock.py

@@ -0,0 +1,455 @@
+#!/usr/bin/env python3
+"""
+NexusClock Core Module
+"""
+
+import sys
+import time
+import os
+import json
+import urllib.request
+from datetime import datetime, timedelta
+from dateutil import tz
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich import print as rprint
+
+console = Console()
+
+
+class nexusclock:
+    """Main NexusClock class - supports both instance and class methods"""
+    
+    # Class-level shared instance
+    _instance = None
+    
+    def __new__(cls):
+        """Singleton pattern to reuse the same instance"""
+        if cls._instance is None:
+            cls._instance = super(nexusclock, cls).__new__(cls)
+        return cls._instance
+    
+    def __init__(self):
+        # Only initialize once
+        if hasattr(self, '_initialized'):
+            return
+        
+        self._initialized = True
+        self.running = True
+        self.reverse_mode = False
+        self.custom_time = None
+        self.use_24h = False
+        self.clock_thread = None
+        self._start_time = datetime.now()
+        self._custom_dt = None
+        self._first_run = True  # Track first run for clean output
+        
+        # Detect timezone from location
+        self.timezone = self._detect_timezone_from_location()
+        self.tz_offset = self._get_tz_offset()
+        self.location = self._get_location()
+    
+    @classmethod
+    def today(cls):
+        """Class method - can be called as nexusclock.nexusclock.today()"""
+        instance = cls()
+        return instance._today()
+    
+    @classmethod
+    def backwards(cls):
+        """Class method - can be called as nexusclock.nexusclock.backwards()"""
+        instance = cls()
+        return instance._backwards()
+    
+    @classmethod
+    def _24h(cls):
+        """Class method - can be called as nexusclock.nexusclock._24h()"""
+        instance = cls()
+        return instance.__24h()
+    
+    @classmethod
+    def custom(cls, datetime_str):
+        """Class method - can be called as nexusclock.nexusclock.custom()"""
+        instance = cls()
+        return instance._custom(datetime_str)
+    
+    @classmethod
+    def changetz(cls, new_tz="UTC"):
+        """Class method - can be called as nexusclock.nexusclock.changetz()"""
+        instance = cls()
+        return instance._changetz(new_tz)
+    
+    @classmethod
+    def help(cls):
+        """Class method - can be called as nexusclock.nexusclock.help()"""
+        instance = cls()
+        return instance._help()
+    
+    def _get_location(self):
+        """Get location from IP geolocation"""
+        try:
+            # Use free IP geolocation API
+            with urllib.request.urlopen('http://ip-api.com/json/', timeout=2) as response:
+                data = json.loads(response.read().decode())
+                if data['status'] == 'success':
+                    return {
+                        'city': data.get('city', 'Unknown'),
+                        'country': data.get('country', 'Unknown'),
+                        'timezone': data.get('timezone', 'UTC')
+                    }
+        except:
+            pass
+        return {'city': 'Unknown', 'country': 'Unknown', 'timezone': 'UTC'}
+    
+    def _detect_timezone_from_location(self):
+        """Detect timezone based on IP geolocation"""
+        try:
+            # Try IP-based geolocation first
+            with urllib.request.urlopen('http://ip-api.com/json/', timeout=2) as response:
+                data = json.loads(response.read().decode())
+                if data['status'] == 'success':
+                    tz_str = data.get('timezone', '')
+                    if tz_str:
+                        detected_tz = tz.gettz(tz_str)
+                        if detected_tz:
+                            return detected_tz
+        except:
+            pass
+        
+        # Try environment variable
+        tz_env = os.environ.get('TZ')
+        if tz_env:
+            try:
+                return tz.gettz(tz_env)
+            except:
+                pass
+        
+        # Try system local timezone
+        try:
+            local_tz = tz.tzlocal()
+            if local_tz and local_tz.utcoffset(datetime.now()):
+                return local_tz
+        except:
+            pass
+        
+        # Try common timezones based on system
+        common_tz = self._guess_timezone_from_system()
+        if common_tz:
+            return common_tz
+        
+        # Ultimate fallback to UTC
+        return tz.UTC
+    
+    def _guess_timezone_from_system(self):
+        """Guess timezone from system settings"""
+        try:
+            # Try to read /etc/timezone
+            with open('/etc/timezone', 'r') as f:
+                tz_str = f.read().strip()
+                if tz_str:
+                    return tz.gettz(tz_str)
+        except:
+            pass
+        
+        try:
+            # Try to read /etc/localtime
+            import subprocess
+            result = subprocess.run(['ls', '-l', '/etc/localtime'], capture_output=True, text=True)
+            if result.stdout:
+                parts = result.stdout.split('/')
+                if len(parts) > 2:
+                    tz_str = '/'.join(parts[-2:]).strip()
+                    return tz.gettz(tz_str)
+        except:
+            pass
+        
+        return None
+    
+    def _get_tz_offset(self):
+        """Get current timezone offset"""
+        try:
+            now = datetime.now(self.timezone)
+            offset = now.utcoffset()
+            if offset:
+                hours = int(offset.total_seconds() / 3600)
+                minutes = abs(int((offset.total_seconds() % 3600) / 60))
+                if minutes > 0:
+                    return f"GMT{'+' if hours >= 0 else ''}{hours}:{minutes:02d}"
+                return f"GMT{'+' if hours >= 0 else ''}{hours}"
+        except:
+            pass
+        return "GMT+0"
+    
+    def _get_ordinal(self, n):
+        """Get ordinal suffix for day numbers"""
+        if 4 <= n <= 20 or 24 <= n <= 30:
+            return "th"
+        else:
+            return {1: "st", 2: "nd", 3: "rd"}.get(n % 10, "th")
+    
+    def _format_output(self, dt, use_24h=False):
+        """Format the time output with proper ordinal and timezone"""
+        day = dt.day
+        ordinal = self._get_ordinal(day)
+        month = dt.strftime("%B")
+        year = dt.year
+        
+        if use_24h:
+            time_str = dt.strftime("%H:%M:%S")
+        else:
+            time_str = dt.strftime("%I:%M:%S %p").lstrip("0")
+        
+        # Get live timezone with location
+        tz_str = self._get_tz_offset()
+        location_str = ""
+        if hasattr(self, 'location') and self.location:
+            loc = self.location
+            if loc['city'] != 'Unknown':
+                location_str = f" ({loc['city']}, {loc['country']})"
+        
+        return f"The {day}{ordinal} of {month}, {year}, {time_str}, {tz_str}{location_str}"
+    
+    def _live_clock(self, custom_dt=None, use_24h=False, reverse=False):
+        """Live clock display with carriage returns - CLEAN OUTPUT"""
+        try:
+            # Clear any previous output and start fresh
+            sys.stdout.write('\r' + ' ' * 120 + '\r')
+            sys.stdout.flush()
+            
+            while self.running:
+                try:
+                    if custom_dt:
+                        # Use custom date/time as base
+                        if reverse:
+                            elapsed = (datetime.now() - self._start_time).total_seconds()
+                            current_time = custom_dt - timedelta(seconds=elapsed)
+                        else:
+                            elapsed = (datetime.now() - self._start_time).total_seconds()
+                            current_time = custom_dt + timedelta(seconds=elapsed)
+                    else:
+                        if reverse:
+                            elapsed = (datetime.now() - self._start_time).total_seconds()
+                            current_time = datetime.now(self.timezone) - timedelta(seconds=elapsed)
+                        else:
+                            current_time = datetime.now(self.timezone)
+                    
+                    # Format output
+                    output = self._format_output(current_time, use_24h)
+                    
+                    # Single clean line with carriage return - NO extra newlines
+                    sys.stdout.write('\r' + output)
+                    sys.stdout.flush()
+                    
+                    time.sleep(1)
+                    
+                except KeyboardInterrupt:
+                    self.running = False
+                    # Print newline after interrupt for clean prompt
+                    print()
+                    break
+                except EOFError:
+                    self.running = False
+                    print()
+                    break
+                except Exception:
+                    # Silent error handling - no crashes
+                    pass
+                    
+        except KeyboardInterrupt:
+            self.running = False
+            print()
+        except EOFError:
+            self.running = False
+            print()
+    
+    def _today(self):
+        """Instance method for today()"""
+        self.use_24h = False
+        self.reverse_mode = False
+        self._start_time = datetime.now()
+        self.running = True
+        
+        try:
+            self._live_clock(use_24h=False, reverse=False)
+        except KeyboardInterrupt:
+            self.running = False
+            # Already handled in _live_clock
+        except EOFError:
+            self.running = False
+            # Already handled in _live_clock
+        
+        return self
+    
+    def __24h(self):
+        """Instance method for 24h format"""
+        self.use_24h = True
+        return self
+    
+    def _backwards(self):
+        """Instance method for backwards()"""
+        self.reverse_mode = True
+        self._start_time = datetime.now()
+        self.running = True
+        
+        try:
+            self._live_clock(use_24h=self.use_24h, reverse=True)
+        except KeyboardInterrupt:
+            self.running = False
+        except EOFError:
+            self.running = False
+        
+        return self
+    
+    def _custom(self, datetime_str):
+        """Instance method for custom()"""
+        try:
+            # Parse custom datetime
+            custom_dt = datetime.strptime(datetime_str, "%Y-%m-%d %H:%M:%S")
+            self._custom_dt = custom_dt
+            self._start_time = datetime.now()
+            self.running = True
+            
+            # Apply timezone
+            custom_dt = custom_dt.replace(tzinfo=self.timezone)
+            
+            try:
+                self._live_clock(custom_dt=custom_dt, use_24h=self.use_24h, reverse=self.reverse_mode)
+            except KeyboardInterrupt:
+                self.running = False
+            except EOFError:
+                self.running = False
+                
+        except ValueError as e:
+            print(f"❌ Invalid datetime format. Use YYYY-MM-DD HH:MM:SS")
+            print(f"Error: {e}")
+        
+        return self
+    
+    def _changetz(self, new_tz="UTC"):
+        """Instance method for changetz()"""
+        try:
+            if new_tz == "UTC":
+                self.timezone = tz.UTC
+            else:
+                self.timezone = tz.gettz(new_tz)
+            
+            if not self.timezone:
+                self.timezone = tz.tzlocal()
+                print(f"⚠️  Invalid timezone, using local timezone")
+            
+            self.tz_offset = self._get_tz_offset()
+            print(f"✅ Timezone changed to: {new_tz}")
+            
+            # Restart clock with new timezone
+            self._start_time = datetime.now()
+            self.running = True
+            
+            try:
+                self._live_clock(use_24h=self.use_24h, reverse=self.reverse_mode)
+            except KeyboardInterrupt:
+                self.running = False
+            except EOFError:
+                self.running = False
+                
+        except Exception as e:
+            print(f"❌ Error changing timezone: {e}")
+            self.timezone = tz.tzlocal()
+        
+        return self
+    
+    def _help(self):
+        """Instance method for help()"""
+        console = Console()
+        
+        # Show detected location and timezone
+        if hasattr(self, 'location') and self.location:
+            loc = self.location
+            if loc['city'] != 'Unknown':
+                console.print(Panel(
+                    f"[bold green]📍 Location:[/bold green] {loc['city']}, {loc['country']}\n"
+                    f"[bold cyan]🕐 Timezone:[/bold cyan] {self._get_tz_offset()}",
+                    title="🌍 Detected Location",
+                    border_style="blue"
+                ))
+        
+        # Create help table
+        table = Table(show_header=True, header_style="bold cyan")
+        table.add_column("Method", style="bold green")
+        table.add_column("Description", style="white")
+        table.add_column("Example", style="yellow")
+        
+        table.add_row(
+            "today()", 
+            "Current time in 12-hour format (live)", 
+            "nexusclock.nexusclock.today()"
+        )
+        table.add_row(
+            "today()._24h()", 
+            "Current time in 24-hour format", 
+            "nexusclock.nexusclock.today()._24h()"
+        )
+        table.add_row(
+            "backwards()", 
+            "Time going backwards (12-hour)", 
+            "nexusclock.nexusclock.backwards()"
+        )
+        table.add_row(
+            "backwards()._24h()", 
+            "Time going backwards (24-hour)", 
+            "nexusclock.nexusclock.backwards()._24h()"
+        )
+        table.add_row(
+            'custom("YYYY-MM-DD HH:MM:SS")', 
+            "Custom date/time", 
+            'nexusclock.nexusclock.custom("2026-07-09 14:30:00")'
+        )
+        table.add_row(
+            'custom()._24h()', 
+            "Custom date/time in 24-hour", 
+            'nexusclock.nexusclock.custom("2026-07-09 14:30:00")._24h()'
+        )
+        table.add_row(
+            'custom().backwards()', 
+            "Custom date/time going backwards", 
+            'nexusclock.nexusclock.custom("2026-07-09 14:30:00").backwards()'
+        )
+        table.add_row(
+            'changetz("Timezone")', 
+            "Change timezone", 
+            'nexusclock.nexusclock.changetz("America/New_York")'
+        )
+        table.add_row(
+            "help()", 
+            "Show this help guide", 
+            "nexusclock.nexusclock.help()"
+        )
+        
+        # Display help panels
+        console.print(Panel.fit(
+            "[bold cyan]NexusClock Help Guide[/bold cyan]",
+            border_style="cyan"
+        ))
+        
+        console.print(Panel(
+            "[bold yellow]Features:[/bold yellow]\n"
+            "• Live clock with carriage return updates\n"
+            "• 12/24 hour formats\n"
+            "• Reverse time mode\n"
+            "• Custom date/time support\n"
+            "• Timezone switching\n"
+            "• Ordinal suffixes (st, nd, rd, th)\n"
+            "• Keyboard interrupt & EOF error handling\n"
+            "• No crashes guaranteed",
+            title="✨ Features",
+            border_style="green"
+        ))
+        
+        console.print(table)
+        
+        console.print(Panel(
+            "[bold green]Press Ctrl+C to stop any running clock[/bold green]",
+            border_style="yellow"
+        ))
+        
+        return self

nexusclock-1.0.0/nexusclock.egg-info/PKG-INFO

@@ -0,0 +1,146 @@
+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**

nexusclock-1.0.0/nexusclock.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE.txt
+MANIFEST.in
+README.md
+setup.py
+nexusclock/__init__.py
+nexusclock/nexusclock.py
+nexusclock.egg-info/PKG-INFO
+nexusclock.egg-info/SOURCES.txt
+nexusclock.egg-info/dependency_links.txt
+nexusclock.egg-info/requires.txt
+nexusclock.egg-info/top_level.txt

nexusclock-1.0.0/nexusclock.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nexusclock-1.0.0/nexusclock.egg-info/requires.txt

@@ -0,0 +1,2 @@
+rich>=10.0.0
+python-dateutil>=2.8.0

nexusclock-1.0.0/nexusclock.egg-info/top_level.txt

@@ -0,0 +1 @@
+nexusclock

nexusclock-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nexusclock-1.0.0/setup.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+from setuptools import setup, find_packages
+
+setup(
+    name="nexusclock",
+    version="1.0.0",
+    author="Light Bulb Experiments",
+    author_email="lightbulb@example.com",
+    description="A powerful live clock library with timezone support and reverse time",
+    long_description=open("README.md").read(),
+    long_description_content_type="text/markdown",
+    url="https://nexusclock.today",
+    license="MIT",
+    packages=find_packages(),
+    python_requires=">=3.7",
+    install_requires=[
+        "rich>=10.0.0",
+        "python-dateutil>=2.8.0",
+    ],
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+    ],
+)