logkeeper-py 1.0.3
Simple file logger that works out of the box with automatic timestamping and session management
Requires Python: >=3.9

# LogKeeper

A simple, plug-and-play file logger for Python with automatic timestamping and session management.

## Features

✨ **Zero Configuration** - Works out of the box, no setup required
📁 **Automatic File Management** - Creates timestamped log files for each session
⏰ **Built-in Timestamps** - Every log entry includes automatic timestamping
🎯 **Simple API** - Clean, intuitive methods for different log levels
💾 **Persistent Logging** - All logs are saved to disk automatically

## Getting Started

### Installation

Run:

```bash
pip install logkeeper-py
```

### Basic Usage
**Note:** Your IDE may show `logkeeper_py` in the autocomplete suggestions when importing, but this is just an IDE quirk with native extension modules. Simply ignore it and import `LogKeeper` directly.

```python
from logkeeper_py import LogKeeper

def main():
  # Log different levels of messages
  LogKeeper.info('Application started')
  LogKeeper.warning('Low memory detected')
  LogKeeper.error('Connection failed')
  LogKeeper.critical('System failure')

  # Save and close log file when done
  LogKeeper.save_logs()
```

That's it! LogKeeper will automatically create a `logs/` directory and save all your logs.

## Log Levels

LogKeeper supports four log levels:

| Method | Use Case | Example |
|--------|----------|---------|
| `info()` | General information | `LogKeeper.info('User logged in')` |
| `warning()` | Potentially harmful situations | `LogKeeper.warning('Disk space low')` |
| `error()` | Error events | `LogKeeper.error('Network timeout')` |
| `critical()` | Severe errors | `LogKeeper.critical('Database corrupted')` |

## Log File Format

Log files are created in the `logs/` directory with the format:

```
logs/
└── 2025-10-18_14-30-45.log
```

Each log entry follows this format:

```
[14:30:45] INFO: Application started
[14:30:46] WARNING: Low memory detected
[14:30:47] ERROR: Connection failed
```

## Complete Example

```python
from logkeeper_py import LogKeeper

def main():
    LogKeeper.info('Starting application...')

    try:
        # Your application logic
        connect_to_database()
        LogKeeper.info('Database connection established')

        load_user_data()
        LogKeeper.info('User data loaded successfully')

    except Exception as e:
        LogKeeper.error(f'Failed to initialize: {e}')
    finally:
        LogKeeper.info('Shutting down application')
        LogKeeper.save_logs()

def connect_to_database():
    # Database connection logic
    pass

def load_user_data():
    # Load user data logic
    pass
```

## Best Practices

### Always Save Logs

Remember to call `save_logs()` before your application exits to ensure all logs are written to disk:

```python
def main():
  LogKeeper.info('App started')
# ... your code ...
  LogKeeper.save_logs()
```

### Use Appropriate Log Levels

Choose the right log level for each situation:

- **INFO**: Normal operations, state changes, milestones
- **WARNING**: Unusual situations that don't prevent functionality
- **ERROR**: Errors that affect functionality but allow recovery
- **CRITICAL**: Severe errors requiring immediate attention

### Be Descriptive

Write clear, actionable log messages:

```dart
# ❌ Bad
LogKeeper.error('Error')

# ✅ Good
LogKeeper.error('Failed to connect to database: connection timeout after 30s')
```

## FAQ

### Where are log files stored?

Log files are stored in a `logs/` directory relative to your application's working directory.

### Can I change the log directory?

Currently, LogKeeper uses a fixed `logs/` directory. Custom directory support may be added in a future version.

### How are log files named?

Log files use the format `yyyy-MM-dd_HH-mm-ss.log` based on when the logger is initialized.

### What happens if I don't call `save_logs()`?

Some log entries may not be written to disk as they remain in the buffer. Always call `save_logs()` before exiting.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

If you encounter any issues or have questions, please [open an issue](https://github.com/RaulCatalinas/Logkeeper-Python/issues) on GitHub.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for a list of changes in each version.