Metadata-Version: 2.4
Name: hellonexus
Version: 1.0.0
Summary: A simple greeting library with repeat functionality
Author: Nexus Team
License: MIT
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Dynamic: license-file
Dynamic: requires-python

# HelloNexus

A simple yet powerful greeting library with repeat functionality.

## Installation

```bash
python -m pip install hellonexus
```

## Quick Start

```python
from hellonexus import hellonexus as hn

# Print "Hello, World!" once
hn.say()

# Print "Hello, World!" 5 times
hn.say(5)

# Print with custom message
from hellonexus.hellonexus import HelloNexus

nexus = HelloNexus("Welcome to Nexus!")
nexus.say(3)
```

## Features

- ✅ **Repeat functionality** - Print greetings 1-indexed times
- ✅ **Flexible input** - Accepts integers or strings as repeat count
- ✅ **Keyboard Interrupt handling** - Graceful Ctrl+C handling
- ✅ **EOF handling** - Graceful EOF (Ctrl+D) handling
- ✅ **Call counter** - Track how many times you've greeted
- ✅ **Custom messages** - Personalize your greetings
- ✅ **Module-level functions** - Quick and easy usage
- ✅ **Class-based design** - Object-oriented approach
- ✅ **Type hints** - Better IDE support and code quality
- ✅ **Unit tested** - Comprehensive test coverage

## Why choose HelloNexus?

| Feature | HelloNexus | Other HelloWorld programs |
|---------|------------|---------------------------|
| Repeat functionality | ✅ | ❌ |
| 1-indexed counting | ✅ | ❌ |
| Keyboard interrupt handling | ✅ | ⚠️ |
| EOF handling | ✅ | ❌ |
| Call counter | ✅ | ❌ |
| Custom messages | ✅ | ✅ |
| Type hints | ✅ | ⚠️ |
| Unit tests | ✅ | ❌ |
| Module-level functions | ✅ | ❌ |
| Object-oriented design | ✅ | ⚠️ |
| String repeat support | ✅ | ❌ |
| Graceful error handling | ✅ | ❌ |

## Usage Examples

### Basic Usage

```python
from hellonexus import hellonexus as hn

# Single greeting
hn.say()  # Output: 1: Hello, World!

# Multiple greetings
hn.say(3)  # Output: 1: Hello, World!
           #         2: Hello, World!
           #         3: Hello, World!
```

### Using Strings as Input

```python
hn.say("4")  # Works with string numbers too!
```

### Custom Messages

```python
from hellonexus.hellonexus import HelloNexus

nexus = HelloNexus("Welcome to the Nexus!")
nexus.say(2)
# Output:
# 1: Welcome to the Nexus!
# 2: Welcome to the Nexus!
```

### Tracking Calls

```python
nexus = HelloNexus()
nexus.say(3)
print(nexus.get_call_count())  # Output: 3

nexus.reset()  # Reset counter to 0
print(nexus.get_call_count())  # Output: 0
```

### Graceful Interrupt Handling

```python
nexus = HelloNexus("Press Ctrl+C to stop")
nexus.say(100)  # Press Ctrl+C to interrupt gracefully
# Output: [Interrupted] Goodbye from HelloNexus!
```

## API Reference

### HelloNexus Class

#### `__init__(default_message: str = "Hello, World!")`
Create a new HelloNexus instance with optional custom message.

#### `say(repeat: Optional[Union[int, str]] = None) -> None`
Print the greeting message, optionally repeated.

- `repeat=None`: Prints once
- `repeat=int`: Prints that many times
- `repeat=str`: Converts to int and prints that many times
- Raises `ValueError` for invalid values

#### `get_call_count() -> int`
Returns the total number of successful `say()` calls.

#### `reset() -> None`
Resets the call counter to 0.

### Module-Level Function

#### `say(repeat: Optional[Union[int, str]] = None) -> None`
Convenience function that uses a global HelloNexus instance.

## Error Handling

HelloNexus handles errors gracefully:

```python
# Invalid repeat values raise ValueError
hn.say("invalid")  # ValueError: Invalid repeat value: 'invalid'. Must be a number.
hn.say(0)          # ValueError: Repeat must be positive, got 0
hn.say(-5)         # ValueError: Repeat must be positive, got -5
hn.say([1,2,3])    # TypeError: Repeat must be int, str, or None, got list
```

## Development

### Run Tests

```bash
python -m pytest tests/
```

### Run Examples

```bash
python examples/basic_usage.py
```

## License

MIT License - Copyright (c) 2026 Light Bulb Experiments

