superstore

High-performance synthetic data generation library for testing and development.

Overview

superstore is a Rust-powered Python library for generating realistic synthetic datasets. It provides:

Data Generators

Generator	Description	Use Cases
Retail	Sales transactions, employees	BI dashboards, forecasting
Time Series	Financial-style series with regimes, jumps	Quant research, backtesting
Weather	Sensor data with seasonal/diurnal patterns	IoT analytics, anomaly detection
Logs	Web server & application logs	Observability, alerting
Finance	Stock prices, OHLCV, options chains	Trading systems, risk analysis
Telemetry	Machine metrics, anomalies, failures	DevOps dashboards, ML training

Statistical Tools

Tool	Description	Use Cases
Distributions	Sample from statistical distributions	Simulation, Monte Carlo
Copulas	Correlated multivariate data	Risk modeling, portfolio analysis
Temporal Models	AR, Markov chains, random walks	Time series simulation

Key Features

• Rust-powered: High-performance generation, 10-100x faster than pure Python
• Flexible output: pandas DataFrame, polars DataFrame, or Python dicts
• Configurable: Pydantic config classes for validated, structured configuration
• Reproducible: Seed support for deterministic generation
• Scalable: Streaming and parallel generation for large datasets

Installation

pip install superstore

For development with polars support:

pip install superstore[develop]

Quick Start

from superstore import superstore, employees, timeseries, weather

# Generate 1000 retail records as a pandas DataFrame
df = superstore(count=1000)

# Generate as polars DataFrame
df_polars = superstore(count=1000, output="polars")

# Generate as list of dicts
records = superstore(count=1000, output="dict")

Reproducibility with Seeds

All data generators support an optional seed parameter for reproducible random data generation:

from superstore import superstore, employees, getTimeSeries, machines

# Same seed produces identical data
df1 = superstore(count=100, seed=42)
df2 = superstore(count=100, seed=42)
assert df1.equals(df2)  # True

# Works with all generators
employees_df = employees(count=50, seed=123)
timeseries_df = timeseries(nper=30, seed=456)
weather_df = weather(count=100, seed=789)
machine_list = machines(count=10, seed=321)

# No seed means random data each time
df3 = superstore(count=100)  # Different each call

Development

Setup

# Clone the repository
git clone https://github.com/1kbgz/superstore.git
cd superstore

# Install development dependencies
make develop

Building

# Build Python wheel
make build

Testing

# Run all tests
make test

Linting

# Run linters
make lint

# Fix formatting
make fix

Architecture

superstore uses a hybrid Rust/Python architecture:

• rust/: Core Rust library with all data generation logic
• src/: PyO3 bindings exposing Rust functions to Python
• superstore/: Python package with native module

The core data generation is implemented in Rust for performance, with PyO3 providing seamless Python integration. Output format conversion (pandas/polars/dict) happens in the Rust bindings layer.

License

This library is released under the Apache 2.0 license

Note

This library was generated using copier from the Base Python Project Template repository.