Engine & Connection

The Engine holds your connection configuration and manages authentication. Create an engine using create_engine() with a connection string, then pass it to a Session to interact with your project.

Creating an Engine

from ragnerock import create_engine

engine = create_engine("ragnerock://user@example.com:pass@api.ragnerock.com/my_project")

Connection String Format

The connection string format is:

ragnerock://email:password@host/project_name

Component	Description
email	Your Ragnerock account email
password	Your account password
host	The API host (e.g., api.ragnerock.com)
project_name	The name of your project

Examples

# Production with standard host
engine = create_engine("ragnerock://analyst@firm.com:mypass@api.ragnerock.com/sec_filings")

# Custom host with port
engine = create_engine("ragnerock://user@company.com:pass@custom.ragnerock.io:8443/research")

# Local development
engine = create_engine("ragnerock://dev@test.com:devpass@localhost:8080/test_project")

URL Encoding

If your email or password contains special characters, they must be URL-encoded:

from urllib.parse import quote

email = quote("user+test@example.com", safe="")
password = quote("p@ss/word!", safe="")
engine = create_engine(f"ragnerock://{email}:{password}@api.ragnerock.com/project")

HTTP vs HTTPS

The SDK automatically selects the protocol based on the host:

• localhost or 127.0.0.1: Uses http://
• All other hosts: Uses https://

# Uses https://api.ragnerock.com
engine = create_engine("ragnerock://...@api.ragnerock.com/project")

# Uses http://localhost:8080
engine = create_engine("ragnerock://...@localhost:8080/project")

Lazy Authentication

The engine doesn’t authenticate immediately. Authentication and project resolution happen when you first use a Session:

from ragnerock import create_engine, Session, Document

# No network calls yet
engine = create_engine("ragnerock://user@example.com:pass@api.ragnerock.com/project")

# Authentication happens here (when entering the session)
with Session(engine) as session:
    docs = session.list(Document).all()

This means connection errors (invalid credentials, unknown project) are raised when opening the session, not when creating the engine.

Engine Properties

Once connected (after entering a session), the engine exposes:

Property	Type	Description
host	str	The API host URL
project_name	str	The project name from the connection string
project_id	UUID	The resolved project UUID (after authentication)

engine = create_engine("ragnerock://...@api.ragnerock.com/my_project")

with Session(engine) as session:
    print(engine.host)         # "https://api.ragnerock.com"
    print(engine.project_name) # "my_project"
    print(engine.project_id)   # UUID("...")

Error Handling

Connection errors raise appropriate exceptions:

from ragnerock import create_engine, Session, AuthenticationError, NotFoundError

try:
    engine = create_engine("ragnerock://bad@email.com:wrong@api.ragnerock.com/project")
    with Session(engine) as session:
        pass
except AuthenticationError as e:
    print(f"Invalid credentials: {e.message}")

try:
    engine = create_engine("ragnerock://user@example.com:pass@api.ragnerock.com/nonexistent")
    with Session(engine) as session:
        pass
except NotFoundError as e:
    print(f"Project not found: {e.message}")

Reusing Engines

An engine can be reused across multiple sessions:

engine = create_engine("ragnerock://...")

# First session
with Session(engine) as session:
    docs = session.list(Document).all()

# Second session (reuses authentication)
with Session(engine) as session:
    operators = session.list(Operator).all()

Environment Variables

For security, avoid hardcoding credentials. Use environment variables:

import os
from ragnerock import create_engine

email = os.environ["RAGNEROCK_EMAIL"]
password = os.environ["RAGNEROCK_PASSWORD"]
host = os.environ.get("RAGNEROCK_HOST", "api.ragnerock.com")
project = os.environ["RAGNEROCK_PROJECT"]

engine = create_engine(f"ragnerock://{email}:{password}@{host}/{project}")

Or build the connection string from a config file:

import tomllib
from ragnerock import create_engine

with open("config.toml", "rb") as f:
    config = tomllib.load(f)

engine = create_engine(
    f"ragnerock://{config['email']}:{config['password']}@{config['host']}/{config['project']}"
)

Next Steps

• Session — Use the session to interact with resources
• Resources — Learn about Documents, Annotations, and more
• Error Handling — Handle connection and API errors