analytics-toolkit 1.3.10.15

Shared Python utilities for SQL, Excel, and date helpers.

analytics_toolkit

Python toolkit for AB-test analysis, SQL workflows, Excel reports, and date helpers.

Quick Start Guide

Documentation Overview

Version: 1.3.10.15
Depends: Python (>=3.8,<3.15)
Imports: clickhouse-connect (>=0.5.14,<1), fsspec (>=2024.2), lz4 (>=4.3.2,<5), numpy (>=1.24.2,<2), openpyxl (>=3.1.1,<4), orjson (>=3.8.7,<4), pandas (>=1.4.4,<3), psycopg2-binary (>=2.9.5,<3), pyarrow (>=14,<23), python-dateutil (>=2.8.2,<3), pytz (>=2022.7), requests (>=2.28.2,<3), s3fs (>=2024.2), scipy (>=1.10.1,<2), sqlglot (>=20,<31), sqlparse (>=0.4.3,<1), tqdm (>=4.65.0,<5), trino (>=0.320,<1), zstandard (>=0.20.0,<1)
Suggests: apache-airflow (>=2.4,<3; optional extra airflow)
Install: pip install analytics-toolkit
PyPI: pypi.org/project/analytics-toolkit
License: MIT
Source: github.com/Karapsin/analytics_toolkit
Issues: GitHub Issues

Installation

From PyPI:

pip install analytics-toolkit

From GitHub:

pip install git+https://github.com/Karapsin/analytics_toolkit.git

Areas

• analytics_toolkit.ab_utils: AB-test metric comparison helpers.
• analytics_toolkit.sql: SQL read, execute, load, and transfer helpers.
• analytics_toolkit.sql_format: SQL formatting, CTE rewrite, and Greenplum temp-table rewrite helpers.
• analytics_toolkit.excel: Excel report helpers for long-format dataframes.
• analytics_toolkit.dates: date and period helpers.
• analytics_toolkit.datetime: timestamp helpers that preserve time components.
• analytics_toolkit.general: shared logging and file path helpers.

SQL Workflows

All SQL functions

SQL module guide

sql.transfer streams query results between configured SQL backends, with batching, retries, and table creation or replacement handled by one call.

from analytics_toolkit import sql

rows = sql.transfer(
    from_db="trino",
    to_db="gp",
    from_sql="select user_id, order_id, amount from iceberg.analytics.orders",
    to_table="sandbox.orders_copy",
    write_mode="replace",
    batch_size=50_000,
    progress=True,
)

Aliases can point to the same backend type, so Greenplum-to-Greenplum transfers work the same way.

rows = sql.transfer(
    from_db="gp_sales",
    to_db="gp_finance",
    from_sql="select user_id, order_id, amount from mart.sales_orders",
    to_table="finance.sales_orders_copy",
    write_mode="replace",
    batch_size=50_000,
)

• sql.read: run a query and return a dataframe.
• sql.execute: run DDL or DML without returning a dataframe.
• sql.execute_read: run setup SQL and return the final result as a dataframe.
• sql.load_df: load a pandas dataframe into a configured backend table.
• sql.transfer: move rows from a source query to a target table across backends.

SQL Formatting

SQL formatting guide

sql_format.format_sql, sql_format.rewrite_with_ctes, and sql_format.gp_rewrite_to_temp_tables transform SQL text locally without opening database connections. GROUP BY and ORDER BY clauses use SELECT-list ordinals by default, with expression-based formatting available through group_by_format="expressions" and order_by_format="expressions".

from analytics_toolkit import sql_format

formatted = sql_format.format_sql(
    "select user_id, amount from orders where amount > 100",
    dialect="postgres",
)

AB Metrics

All AB functions

AB utilities guide

compute_test_metrics compares experiment groups across mean and ratio metrics, with optional CUPED statistics and bootstrap multiple-comparison adjustment.

from analytics_toolkit.ab_utils import compute_test_metrics

result = compute_test_metrics(
    experiment_df,
    group="group_name",
    control="control",
    user_id="user_id",
    ratio_metrics=[
        {"name": "ctr", "numerator": "clicks", "denominator": "views"},
    ],
    pre_exp_metrics_df=pre_experiment_df,
    multiple_comparisons_adjustment=True,
    multiple_comparisons_adjustment_resamples=1000,
)

Example output with CUPED and bootstrap columns enabled:

metric_type	group_1	group_2	metric_name	n0	n1	outliers_cutoff	outliers_n_control	outliers_n_test	metric_control	metric_test	variance_control	variance_test	delta_abs	delta_relative	mde_abs	mde_relative	s.e.	p-value	s.e. CUPED	p-value CUPED	mde_abs CUPED	mde_relative CUPED	s.e. bootstrap	bootstrap_adj_p
mean	test	control	revenue	10000	10050	250.0	3	4	12.40	13.10	45.20	47.80	0.70	0.056	0.42	0.034	0.15	0.003	0.11	0.001	0.31	0.025	0.14	0.012
ratio	test	control	ctr	10000	10050	1.0	0	0	0.082	0.087	0.0009	0.0010	0.005	0.061	0.003	0.037	0.001	0.008	0.001	0.006	0.002	0.024	0.001	0.019

Date Helpers

All date functions

Date helpers guide

Date helpers cover reporting ranges, period boundaries, offsets, and stable string formatting for SQL and filenames.

from analytics_toolkit.dates import add_days, first_day, gen_dates_list, last_day

report_days = gen_dates_list("2026-06-01", "2026-06-07")
# ["2026-06-01", "2026-06-02", "2026-06-03", "2026-06-04", "2026-06-05", "2026-06-06", "2026-06-07"]

month_start = first_day("2026-06-08", "month")
# "2026-06-01"

month_end = last_day("2026-06-08", "month")
# "2026-06-30"

next_run = add_days("2026-06-08", 1)
# "2026-06-09"

• gen_dates_list: build daily, weekly, monthly, or quarterly sequences.
• first_day / last_day: get week, month, or quarter boundaries.
• add_days, add_weeks, add_months, add_quarters: shift dates.
• sanitize_date: convert a date to compact YYYYMMDD text.

Datetime Helpers

All datetime functions

Datetime helpers guide

Datetime helpers preserve timestamp components for second-level reporting, windowing, and scheduling workflows. Use them when calendar date truncation from analytics_toolkit.dates is not desired.

from analytics_toolkit import datetime as dttm

next_run = dttm.add_days("2026-01-01 12:13:15", 1)
# "2026-01-02 12:13:15"

hour_window = dttm.datetime_bounds("2026-01-01 12:13:15", period="hour")
# ("2026-01-01 12:00:00", "2026-01-01 12:59:59")

• add_seconds, add_minutes, add_hours, add_days, add_weeks, add_months, add_quarters: shift timestamps.
• datetime_bounds: get minute, hour, day, week, month, or quarter timestamp boundaries.
• gen_datetimes_list: build timestamp sequences.
• format_datetime / sanitize_datetime: format timestamps for display, SQL, or filenames.

Documentation

• Documentation Overview
• Quick Start
• Airflow SQL Manual
• Module documentation
• Changelog