Skip to content

Examples Gallery

Complete, copy-paste examples for common StreamForge use cases.

Quick Navigation

By Use Case

I want to...

...get started quickly

→ Basic Streaming →

...save data to CSV

→ CSV Example →

...save data to PostgreSQL

→ PostgreSQL Example →

...stream to Kafka

→ Database Output →

...rename database columns

→ Data Transformation →

...aggregate 1m to 5m, 15m, 1h

→ Advanced Patterns →

...load historical data

→ Advanced Patterns →

...compare prices across exchanges

→ Advanced Patterns →

By Complexity

Beginner ⭐

Start here if you're new to StreamForge:

  1. Hello World - Simplest possible example
  2. CSV Output - Save to file
  3. Multiple Symbols - Track multiple assets

Intermediate ⭐⭐

Once you understand the basics:

  1. PostgreSQL - Database integration
  2. Upsert Patterns - Handle duplicates
  3. Transformers - Modify data
  4. Aggregation - Multiple timeframes

Advanced ⭐⭐⭐

For complex use cases:

  1. Backfilling - Historical data
  2. Multi-Exchange - Merge exchanges
  3. Custom Emitters - Build your own

Source Code

All examples are available in the GitHub repository:

View on GitHub →

Example Categories

Basic Streaming

Simple examples to get you started:

  • Hello World
  • CSV Output
  • Multiple Symbols
  • Different Timeframes
  • Different Exchanges

View Examples →

Database Output

Save data to databases and streaming platforms:

  • PostgreSQL Basic
  • PostgreSQL with Upsert
  • Kafka Streaming
  • Multiple Outputs

View Examples →

Data Transformation

Modify and enrich your data:

  • Rename Fields
  • Add Computed Fields
  • Filter Data
  • Custom Transformers

View Examples →

Advanced Patterns

Complex real-world patterns:

  • Multi-Timeframe Aggregation
  • Historical Backfilling
  • Multi-Exchange Merging
  • Arbitrage Detection
  • Production Patterns

View Examples →

Running Examples

Prerequisites

Install StreamForge:

pip install streamforge

For database examples, you'll also need:

# PostgreSQL
pip install streamforge  # Already includes asyncpg

# For examples with additional dependencies
pip install -r examples/requirements.txt

Running an Example

# 1. Copy the example code
# 2. Save to a Python file
python my_example.py

# Or download from GitHub
git clone https://github.com/paulobueno90/streamforge.git
cd streamforge/examples
python 01_basic/hello_world.py

Example Template

Use this template for your own scripts:

"""
My StreamForge Script
=====================

Description: What this script does

Prerequisites:
- streamforge installed
- (any other requirements)

Run:
    python my_script.py
"""

import asyncio
import streamforge as sf

async def main():
    """Main function"""

    # 1. Configure stream
    stream = sf.DataInput(
        type="kline",
        symbols=["BTCUSDT"],
        timeframe="1m"
    )

    # 2. Create runner
    runner = sf.BinanceRunner(stream_input=stream)

    # 3. Add emitter(s)
    runner.register_emitter(sf.Logger(prefix="StreamForge"))

    # 4. Run!
    await runner.run()

if __name__ == "__main__":
    asyncio.run(main())

Tips & Tricks

Start with Logger

Always test with Logger first:

runner.register_emitter(sf.Logger(prefix="Test"))

Test with Short Periods

Use timeouts for testing:

import asyncio

async def main():
    runner = sf.BinanceRunner(stream_input=stream)
    runner.register_emitter(sf.Logger())

    # Run for 30 seconds only
    try:
        await asyncio.wait_for(runner.run(), timeout=30)
    except asyncio.TimeoutError:
        print("Test complete!")

asyncio.run(main())

Getting Help

If you need help with examples:

  1. Check the User Guide
  2. Read Core Concepts
  3. See API Reference
  4. Ask on GitHub Discussions
  5. Report issues on GitHub Issues

Next Steps

Ready to dive in?

  1. Basic Streaming → - Start here
  2. Database Output → - Save your data
  3. Data Transformation → - Customize output
  4. Advanced Patterns → - Complex use cases