Quick Start

This guide will walk you through a minimal example of using bitmapist to track and query user activity.

1. Setup

First, ensure you have bitmapist installed and a Redis server running. See the Installation guide for details.

Create a new Python file and add the following imports and Redis connection setup:

from datetime import datetime, timezone
from bitmapist import setup_redis, mark_event, DayEvents, delete_all_events

# Configure the connection to your Redis server
# This uses the name "default" for the connection
setup_redis("default", "localhost", 6379)

print("Connected to Redis and ready to track events.")

2. Mark Events

Let's mark a few users as having performed an "active" event today. The mark_event function takes an event name and a unique user ID (which must be an integer).

# Let's clean up previous data for this example
delete_all_events()

# Mark user IDs 100, 250, and 999 as active
mark_event('active', 100)
mark_event('active', 250)
mark_event('active', 999)

print("Marked 3 users as active.")

3. Query Events

Now, let's ask some questions about the data we just recorded. We can use the DayEvents class to query events that happened today.

# Get events for 'active' for the current day
# By default, it uses the current UTC date
users_active_today = DayEvents('active')

# How many users were active today?
active_count = len(users_active_today)
print(f"Total active users today: {active_count}")

# Was user 100 active today?
if 100 in users_active_today:
    print("User 100 was active today.")

# Was user 500 active today?
if 500 not in users_active_today:
    print("User 500 was not active today.")

# Who were the active users?
active_user_ids = list(users_active_today)
print(f"The following users were active today: {active_user_ids}")

4. Full Example Script

Here is the complete script. Save it as quick_start.py and run it.

from datetime import datetime, timezone
from bitmapist import setup_redis, mark_event, DayEvents, delete_all_events

# 1. Setup Redis connection
setup_redis("default", "localhost", 6379)
print("Connected to Redis and ready to track events.")

# Clean up any previous data for a clean run
delete_all_events()

# 2. Mark some events
print("\n--- Marking events ---")
mark_event('active', 100)
mark_event('active', 250)
mark_event('active', 999)
print("Marked users 100, 250, and 999 as active.")

# 3. Query the events
print("\n--- Querying events ---")
users_active_today = DayEvents('active')

# Get total count
active_count = len(users_active_today)
print(f"Total active users today: {active_count}")

# Check for membership
print(f"Was user 100 active? {100 in users_active_today}")
print(f"Was user 500 active? {500 in users_active_today}")

# Get all user IDs
active_user_ids = list(users_active_today)
print(f"All active user IDs today: {active_user_ids}")

# Clean up at the end
delete_all_events()

Expected Output

Connected to Redis and ready to track events.

--- Marking events ---
Marked users 100, 250, and 999 as active.

--- Querying events ---
Total active users today: 3
Was user 100 active? True
Was user 500 active? False
All active user IDs today: [100, 250, 999]

This basic example demonstrates the core workflow of bitmapist. To explore more powerful features, check out the Usage Guide.