Metadata-Version: 2.4
Name: speedups
Version: 2.0.1
Summary: C/Cython extensions for fast STL I/O (used by numpy-stl) and PostgreSQL-to-NumPy conversion.
Author-email: Rick van Hattem <Wolph@Wol.ph>, Joren Hammudoglu <jhammudoglu@gmail.com>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/WoLpH/speedups/
Project-URL: Repository, https://github.com/WoLpH/speedups/
Keywords: Cython,C,C++,speedups,Numpy,PostgreSQL,PsycoPG
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Cython
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.23.5
Provides-Extra: postgres
Requires-Dist: psycopg>=3.0.8; extra == "postgres"
Provides-Extra: test
Requires-Dist: psycopg[binary]>=3.0.8; extra == "test"
Requires-Dist: pytest>=8.0.1; extra == "test"
Requires-Dist: pytest-postgresql>=5.1.0; extra == "test"
Requires-Dist: pytest-cov>=7.0; extra == "test"
Requires-Dist: coverage>=7.0; extra == "test"
Provides-Extra: lint
Requires-Dist: ruff>=0.9; extra == "lint"
Requires-Dist: codespell>=2.2; extra == "lint"
Provides-Extra: typecheck
Requires-Dist: pyright>=1.1; extra == "typecheck"
Requires-Dist: mypy>=1.13; extra == "typecheck"
Provides-Extra: dev
Requires-Dist: speedups[lint,test,typecheck]; extra == "dev"
Requires-Dist: questionary>=2.1; extra == "dev"
Requires-Dist: rich>=13.0; extra == "dev"
Requires-Dist: tox>=4.0; extra == "dev"
Requires-Dist: tox-uv>=1.28; extra == "dev"
Requires-Dist: tox-gh>=1.7; extra == "dev"
Provides-Extra: benchmark
Requires-Dist: matplotlib>=3.7; extra == "benchmark"
Requires-Dist: psycopg[binary]>=3.0.8; extra == "benchmark"

# Speedups

[![CI](https://github.com/wolph/speedups/actions/workflows/ci.yml/badge.svg)](https://github.com/wolph/speedups/actions/workflows/ci.yml)
[![Build Wheels](https://github.com/wolph/speedups/actions/workflows/build_wheels.yml/badge.svg)](https://github.com/wolph/speedups/actions/workflows/build_wheels.yml)
[![PyPI](https://img.shields.io/pypi/v/speedups.svg)](https://pypi.org/project/speedups/)
[![Python](https://img.shields.io/pypi/pyversions/speedups.svg)](https://pypi.org/project/speedups/)
[![License](https://img.shields.io/pypi/l/speedups.svg)](https://github.com/WoLpH/speedups/blob/master/LICENSE)

C and Cython extensions for fast STL I/O and PostgreSQL-to-NumPy conversion.

## Performance

Cython extensions run **~3x faster** than pure Python, consistent
across data sizes.

<p align="center">
  <img src="https://raw.githubusercontent.com/wolph/speedups/develop/benchmarks/results/stl_performance.svg" alt="STL I/O Performance" width="700">
</p>

<div align="center">

| Operation | Facets | Pure Python | speedups | Speedup |
|:----------|-------:|------------:|---------:|--------:|
| Write | 10,000 | 28.5 ms | 9.9 ms | **2.9x** |
| Read | 10,000 | 21.6 ms | 7.0 ms | **3.1x** |
| Write | 100,000 | 283.4 ms | 89.3 ms | **3.2x** |
| Read | 100,000 | 218.7 ms | 71.0 ms | **3.1x** |
| Write | 1,000,000 | 2.81 s | 897.5 ms | **3.1x** |
| Read | 1,000,000 | 2.19 s | 711.5 ms | **3.1x** |
| Write | 10,000,000 | 28.62 s | 9.22 s | **3.1x** |
| Read | 10,000,000 | 22.03 s | 7.32 s | **3.0x** |

</div>

<p align="center">
  <img src="https://raw.githubusercontent.com/wolph/speedups/develop/benchmarks/results/pg_array_performance.svg" alt="PostgreSQL COPY to NumPy Performance" width="700">
</p>

<div align="center">

| Type | Elements | Pure Python | speedups | Speedup |
|:-----|:---------|------------:|---------:|--------:|
| int32 | 100K | 7.3 ms | 2.6 ms | **2.8x** |
| int32 | 1M | 73.8 ms | 24.8 ms | **3.0x** |
| int32 | 10M | 747.5 ms | 216.1 ms | **3.5x** |
| int32 | 50M | 3.75 s | 1.05 s | **3.6x** |
| float64 | 100K | 8.0 ms | 3.3 ms | **2.4x** |
| float64 | 1M | 78.3 ms | 32.1 ms | **2.4x** |
| float64 | 10M | 786.5 ms | 268.5 ms | **2.9x** |
| float64 | 50M | 4.01 s | 1.31 s | **3.1x** |

<sub>Benchmarked on Apple M2 Pro, Python 3.14, macOS 15.4. PG data pre-populated in tables to isolate COPY+conversion time. Array dimensionality (1D/2D/3D) has no significant effect on performance.</sub>

</div>

## Install

```bash
pip install speedups
```

With PostgreSQL support:

```bash
pip install speedups[postgres]
```

## PostgreSQL Array → NumPy

Convert PostgreSQL arrays directly to NumPy ndarrays using psycopg's
binary `COPY` protocol. Bypasses Python object creation for a significant
speedup over the default loader.

Supports `float4`, `float8`, `smallint`, `integer`, and `bigint` arrays,
from 1D to N-D.

```python
import psycopg
from speedups.psycopg_loaders import NumpyLoader

with psycopg.connect("dbname=mydb") as conn:
    cursor = conn.cursor(binary=True)
    NumpyLoader.install(cursor)

    query = """
    COPY (
        SELECT array_agg(x)
        FROM generate_series(1, 100000) x
    ) TO STDOUT WITH BINARY
    """

    with cursor.copy(query) as copy:
        copy.set_types(["integer[]"])

        for row in copy.rows():
            print(row)  # numpy.ndarray
```

## ASCII STL I/O

Read and write ASCII STL files at C speed. This module is used internally
by [numpy-stl](https://github.com/WoLpH/numpy-stl) — if you want to read
or write STL files, use numpy-stl for a full-featured API. The Cython
implementation uses direct `sscanf`/`fprintf` calls, avoiding Python string
overhead entirely.

```python
from speedups._stl import ascii_read, ascii_write

# Read
with open("model.stl", "rb") as f:
    buf = f.read(8192)
    name, mesh = ascii_read(f, buf)

# Write
with open("output.stl", "wb") as f:
    ascii_write(f, b"my_model", mesh)
```

## Supported Types

| PostgreSQL | NumPy | Dimensions |
|-----------|-------|------------|
| `float4` | `float32` | 1D – ND |
| `float8` | `float64` | 1D – ND |
| `smallint` | `int16` | 1D – ND |
| `integer` | `int32` | 1D – ND |
| `bigint` | `int64` | 1D – ND |

## Compatibility

- Python 3.10, 3.11, 3.12, 3.13, 3.14
- NumPy 1.x and 2.x

## License

BSD-3-Clause
