django-event-journal 1.0.1
A Django library for logging events to PostgreSQL database
License: MIT
Requires Python: >=3.8
Keywords: django, logging, events, postgresql, supabase, database, audit

# Django Event Logger

[![PyPI version](https://badge.fury.io/py/django-event-journal.svg)](https://badge.fury.io/py/django-event-journal)
[![Python Support](https://img.shields.io/pypi/pyversions/django-event-journal.svg)](https://pypi.org/project/django-event-journal/)
[![Django Support](https://img.shields.io/badge/Django-3.2%2B-blue.svg)](https://www.djangoproject.com/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Django library for logging events to PostgreSQL database with a simple and clean API. Perfect for audit trails, user activity tracking, and system event logging.

## 🚀 Features

- **Zero Configuration** - Pre-configured database connection
- **Simple API** - Just import and log events
- **No Migrations** - Assumes table already exists
- **Django Admin** - Built-in admin interface for viewing logs
- **Utility Functions** - Extract IP addresses and user agents
- **Production Ready** - Optimized for performance and reliability

## Installation

```bash
pip install django-event-journal
```

Or install from source:

```bash
git clone https://github.com/yourusername/django-event-journal.git
cd django-event-journal
pip install -e .
```

## Database Configuration

The library comes with **pre-configured database settings** for immediate use. No additional configuration is required - the library will automatically connect to the database.

## Setup

### For Standalone Usage (Recommended)

**No setup required!** Just install and use:

```bash
pip install django-event-journal
```

```python
from django_event_journal import log_event
log_event('your_event_type', event_info={...})
```

### For Django Projects

1. Add `django_event_journal` to your `INSTALLED_APPS` in settings.py:

```python
INSTALLED_APPS = [
    # ... other apps
    'django_event_journal',
]
```

2. Ensure the EventJournal table exists in your database.

3. Test the connection:

```bash
python quick_start.py
```

## Usage

### Standalone Usage (Recommended)

The library comes with pre-configured database settings, so you can use it in any Python script without any setup:

```python
from django_event_journal import log_event

# Just log events - assumes EventJournal table already exists!
log_event(
    event_type='user_login',
    user_id=123,
    event_info={
        'login_method': 'email',
        'success': True
    },
    ip_address='192.168.1.1',
    user_agent='Mozilla/5.0...'
)
```

**Prerequisites:** The EventJournal table must already exist in your database.

### Django Project Usage

If you're using it in a Django project:

```python
from django_event_journal import EventJournal

# Log an event
EventJournal.log_event(
    event_type='user_login',
    user_id=request.user.id,
    event_info={
        'login_method': 'email',
        'success': True
    },
    ip_address=get_client_ip(request),
    user_agent=get_user_agent(request)
)
```

### Advanced Usage

```python
# Log duplicate upload attempt event
EventJournal.log_event(
    event_type='duplicate_upload_attempt',
    user_id=user.id,
    event_info={
        'file_id': existing_file.id,
        'filename': existing_file.original_filename,
        'file_type': existing_file.file_type,
        'size': existing_file.size,
        'checksum': existing_file.checksum,
        'is_new_file': False,
        'is_deduplication': False,
        'reference_count': existing_file.reference_count,
        'user_relationship_type': 'owner' if file_user.is_owner else 'reference'
    },
    ip_address=get_client_ip(request),
    user_agent=get_user_agent(request)
)
```

### Utility Functions

The library provides utility functions for extracting client information:

```python
from django_event_journal.utils import get_client_ip, get_user_agent

# Get client IP address
ip_address = get_client_ip(request)

# Get user agent
user_agent = get_user_agent(request)
```

## API Reference

### EventJournal.log_event()

Log an event to the database.

**Parameters:**
- `event_type` (str): Type of event being logged
- `user_id` (int, optional): ID of the user associated with this event
- `event_info` (dict, optional): Additional event information
- `ip_address` (str, optional): Client IP address
- `user_agent` (str, optional): Client user agent string
- `timestamp` (datetime, optional): Event timestamp (defaults to now)

**Returns:**
- `EventJournal`: The created EventJournal instance

## Database Schema

The library creates an `EventJournal` model with the following fields:

- `id`: Primary key
- `event_type`: Type of event (CharField, max_length=100)
- `user_id`: User ID (IntegerField, nullable)
- `event_info`: JSON field containing event data
- `ip_address`: Client IP address (CharField, max_length=45)
- `user_agent`: Client user agent (TextField)
- `timestamp`: Event timestamp (DateTimeField)
- `created_at`: Record creation timestamp (DateTimeField)

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🔗 Links

- **Repository**: [https://github.com/amolsr/django_event_journal](https://github.com/amolsr/django_event_journal)
- **PyPI Package**: [https://pypi.org/project/django-event-journal/](https://pypi.org/project/django-event-journal/)
- **Issues**: [https://github.com/amolsr/django_event_journal/issues](https://github.com/amolsr/django_event_journal/issues)

## 📊 Stats

![GitHub stars](https://img.shields.io/github/stars/amolsr/django_event_journal?style=social)
![GitHub forks](https://img.shields.io/github/forks/amolsr/django_event_journal?style=social)
![GitHub issues](https://img.shields.io/github/issues/amolsr/django_event_journal)
![GitHub pull requests](https://img.shields.io/github/issues-pr/amolsr/django_event_journal)