lightwave-core 0.3.3

Shared Django utilities for LightWave Media projects

lightwave-core

Shared Django utilities for LightWave Media projects.

Installation

# Local development (from workspace root)
uv pip install -e packages/lightwave-core

# With billing support (Stripe)
uv pip install -e "packages/lightwave-core[billing]"

# In a project's requirements.txt
-e file:../../packages/lightwave-core

Modules

Storage (lightwave.storage)

CDN and S3 storage backends for static files and media.

from lightwave.storage import StaticStorage, PublicMediaStorage, PrivateMediaStorage

# In settings.py
STORAGES = {
    "staticfiles": {"BACKEND": "lightwave.storage.StaticStorage"},
    "default": {"BACKEND": "lightwave.storage.PublicMediaStorage"},
}

# Configure static file prefix per project
LIGHTWAVE_STATIC_PREFIX = "static/my-project"

Utils (lightwave.utils)

Common utilities including BaseModel, timezone helpers, slug generation.

from lightwave.utils import BaseModel, get_common_timezones, get_next_unique_slug

class MyModel(BaseModel):
    # Automatically has created_at and updated_at fields
    name = models.CharField(max_length=100)

Auth (lightwave.auth)

Base user model and authentication helpers.

from lightwave.auth import BaseCustomUser, validate_profile_picture

class CustomUser(BaseCustomUser):
    # Inherits avatar, language, timezone, gravatar support
    # Add project-specific fields
    stripe_customer = models.ForeignKey(...)

Chat (lightwave.chat)

Base models for AI chat sessions.

from lightwave.chat import BaseChatSession, BaseChatMessage, ChatTypes, MessageTypes

class Chat(BaseChatSession):
    agent_type = models.CharField(...)

class ChatMessage(BaseChatMessage):
    chat = models.ForeignKey(Chat, on_delete=models.CASCADE, related_name="messages")

Islands (lightwave.islands)

Context processors and utilities for React island components.

# In settings.py TEMPLATES context_processors
"lightwave.islands.context_processors.lightwave_navigation",

# Processors are split into focused modules:
from lightwave.islands.processors import (
    get_brand_theme,      # Brand/theme utilities
    get_auth_state,       # User auth state
    get_cart_state,       # E-commerce cart
    get_team_state,       # Multi-tenant teams
    get_subscription_state,  # SaaS subscriptions
)

Context (lightwave.context)

Session context models for Claude Code integration.

from lightwave.context import SessionContext, build_session_context

# Build context for current working directory
context = build_session_context()

# Export to markdown for Claude consumption
markdown = context.to_markdown()

Schema (lightwave.schema)

Single Source of Truth (SST) for the LightWave ecosystem.

from lightwave.schema import get_field_values, LayoutSchema

# Get valid field values from YAML definitions
page_statuses = get_field_values("page_statuses")  # ['draft', 'published', 'archived']

# Load typed schemas
layouts = LayoutSchema.get_all_from_sst()

See lightwave/schema/CLAUDE.md for full SST documentation.

Development

Setup

1. Install dependencies:

   uv pip install -e ".[dev]"
   

2. Install pre-commit hooks:

   pre-commit install
   

   This ensures code is automatically formatted and checked before each commit.

Running Tests

uv run pytest

Optional Dependencies

• billing: Stripe utilities via dj-stripe (uv pip install lightwave-core[billing])
• dev: Testing utilities (uv pip install lightwave-core[dev])