Metadata-Version: 2.4
Name: copium
Version: 0.1.0a1.dev77
Summary: Fast drop-in replacement for copy.deepcopy()
Author-email: "Arseny Boykov (Bobronium)" <hi@bobronium.me>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Bobronium/copium
Project-URL: Source, https://github.com/Bobronium/copium
Project-URL: Issues, https://github.com/Bobronium/copium/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: copium[lint]; extra == "dev"
Requires-Dist: copium[typecheck]; extra == "dev"
Requires-Dist: copium[test]; extra == "dev"
Requires-Dist: copium[docs]; extra == "dev"
Provides-Extra: lint
Requires-Dist: ruff>=0.5; extra == "lint"
Provides-Extra: typecheck
Requires-Dist: mypy>=1.10; extra == "typecheck"
Requires-Dist: pyright>=1.1.400; extra == "typecheck"
Requires-Dist: zuban>=0.2.0; extra == "typecheck"
Requires-Dist: pytest; extra == "typecheck"
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: pytest-assert-type>=0.1.5; extra == "test"
Requires-Dist: indifference>=0.1.0; extra == "test"
Requires-Dist: typing-extensions; python_version < "3.12" and extra == "test"
Requires-Dist: datamodelzoo; extra == "test"
Requires-Dist: pytest-codspeed>=4.2.0; extra == "test"
Requires-Dist: pytest-test-groups>=1.2.1; extra == "test"
Requires-Dist: psutil>=5.9.0; extra == "test"
Requires-Dist: pytest-random-order>=1.2.0; extra == "test"
Provides-Extra: docs
Requires-Dist: mkdocs-material; extra == "docs"
Requires-Dist: mkdocstrings[python]; extra == "docs"
Requires-Dist: mkdocs-autorefs; extra == "docs"
Requires-Dist: mkdocs-section-index; extra == "docs"
Provides-Extra: benchmark
Requires-Dist: tyro>=0.9.33; extra == "benchmark"
Requires-Dist: pyperf>=2.9.0; extra == "benchmark"
Requires-Dist: ipython>=8.37.0; extra == "benchmark"
Requires-Dist: datamodelzoo; extra == "benchmark"
Provides-Extra: build
Requires-Dist: build>=1.3.0; extra == "build"
Requires-Dist: cibuildwheel>=2.23.3; extra == "build"
Requires-Dist: pip>=25.3; extra == "build"
Requires-Dist: setuptools>=80.9.0; extra == "build"
Requires-Dist: setuptools-scm>=9.2.2; extra == "build"
Requires-Dist: wheel>=0.45.1; extra == "build"
Dynamic: license-file

<h1>
copium
<a href="https://pypi.python.org/pypi/copium">
  <img src="https://img.shields.io/pypi/v/copium.svg" alt="PyPI Version Badge">
</a>
<a href="https://pypi.python.org/pypi/copium">
  <img src="https://img.shields.io/pypi/l/copium.svg" alt="PyPI License Badge">
</a>
<a href="https://pypi.python.org/pypi/copium">
  <img src="https://img.shields.io/pypi/pyversions/copium.svg" alt="PyPI Python Versions Badge">
</a>
<a href="https://github.com/Bobronium/copium/actions">
  <img src="https://github.com/Bobronium/copium/actions/workflows/cd.yaml/badge.svg" alt="CD Status Badge">
</a>
<a href="https://codspeed.io/Bobronium/copium">
<img src="https://img.shields.io/badge/Codspeed-copium-8A2BE2?style=flat&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0MCA0MCIgcHJlc2VydmVBc3BlY3RSYXRpbz0ieE1pZFlNaWQgbWVldCI%2BCiAgICA8ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSgtMTAwLDEwKSB0cmFuc2xhdGUoMTIwLDEyKSBzY2FsZSgxLjMpIHRyYW5zbGF0ZSgtMTIwLC0xMikiPiI%2BCiAgICAgICAgPHBhdGggZmlsbD0iI0VENkUzRCIgZmlsbC1ydWxlPSJldmVub2RkIgogICAgICAgICAgICAgIGQ9Ik0xMTAuMTIxIDE3LjExN2MuNzY2LjE3IDEuMzA4LjA1IDEuMzkyLjA2NGwuMDA0LjAwMWMxLjI3NS42OTEgMi4yMDIgMS4yNzkgMy4wOTcgMS42NTVsLS4xMDcuMDFxLTEuMDkyLjE3Mi0xLjU3Mi4yNWMtMy4yNzYuNTMzLTQuODg0LS4zOTgtNC41MzItMS44My4xNDItLjU3OC45MzgtLjMyNCAxLjcxOC0uMTVtMTEuMDA0LTEzLjkxYzIuMDc0IDEuNTM0IDIuNjcgMi4zMzEgMy43NzQgMy41NTUgMi43MDggMCA0LjIyIDIuMDI2IDMuNzM1IDUuMDQ2LS4zMDggMS45MjEtNC4xNSAxLjI0Ni01LjA2IDBxLS45MTIuODI2LTQuNDgzIDMuNjYzbC0uMDk3LjA3NmMtLjY5NS41NTMtMy4zNzcuMzc2LTMuNjM0LjE4N3EuODA2LTEuMzI1IDEuMTYxLTIuMDcyYy4zNTYtLjc0NS42MDUtMS40OTMuNjA1LTIuNzMyIDAtMS4yMzgtLjY5NS0yLjI5LTIuMTY2LTIuMjYzYS4yOC4yOCAwIDAgMC0uMjc0LjI5NWMwIC4xOTUuMTQ1LjI5Ni4yNzQuMjk2Ljc3OSAwIDEuMzI1Ljk2OCAxLjMyNSAxLjY3My4wMDEuNzA0LS4xMTEgMS4yNzUtLjQ0NCAyLjEzNC0uMjg3Ljc0MS0xLjQ0NCAyLjU4My0xLjc0NSAyLjc2N2EuMjc4LjI3OCAwIDAgMCAuMDQyLjQ4NnEuMDMxLjAxNS4wNzkuMDMuMS4wMzIuMjUzLjA3MWMuMjYyLjA2NC41ODEuMTIxLjk0LjE2My45ODcuMTEzIDIuMDk0LjA5IDMuMjc0LS4xMmwuMDQ1LS4wMDljLjM1Mi0uMDY0Ljg2NS0uMDY5IDEuMzcyLS4wMDMuNTkzLjA3OCAxLjEzMy4yNDQgMS41NDMuNDkzLjM2LjIxOC42MDguNDkuNzM1LjgybC4wMTIuMDM2cS4wOC4yNjMuMDguNTY2YzAgMS4wODMtMi4zMDguNDM0LTQuOTc2LjMxOGE5IDkgMCAwIDAtLjYxLS4wMDJjLTEuMDg5LS4wNTUtMS45ODUtLjM3NC0zLjE4Ni0uOTc0bC4wMjEtLjAwNHMtLjA5Mi0uMDM4LS4yMzgtLjEwNmMtLjM1Ni0uMTgyLS43NC0uMzg3LTEuMTYyLS42MTZoLS4wMDNjLS4zOTgtLjI0OC0uNzQ5LS41MjctLjgzOC0uNzc2LS4yMzMtLjY1MS0uMTE4LS42NTEuNzE1LTEuNjEzLTEuNDIyLjE3NS0xLjQ1Ny4yNzYtMy4wNzguMjc2cy00LjI5Mi0uMDgzLTQuMjkyLTEuNjdxMC0xLjU5IDIuMTYxLTEuMjM2LS41MjctMi44OSAxLjgwNy01LjJjNC4wNzYtNC4wMzUgOS41NzggMS41MjUgMTMuMzUgMS41MjUgMS43MTYgMC0zLjAyNS0yLjY5My00Ljk5NS0zLjQ1NnMxLjEzMS0zLjcyOSAzLjk3OC0xLjYyNG00Ljc0OCA1LjU1MmMtLjMxIDAtLjU2MS4yNy0uNTYxLjYwNXMuMjUxLjYwNC41NjEuNjA0LjU2MS0uMjcuNTYxLS42MDQtLjI1MS0uNjA1LS41NjEtLjYwNSIKICAgICAgICAgICAgICBjbGlwLXJ1bGU9ImV2ZW5vZGQiLz4KICAgIDwvZz4KPC9zdmc%2B&logoSize=auto&labelColor=1B2330&color=ED6E3D&link=https%3A%2F%2Fcodspeed.io%2FBobronium%2Fcopium" alt="Codspeed Badge">
</a>
</h1>


Fast drop-in replacement for `copy.deepcopy()`.

<picture>
    <source srcset="https://raw.githubusercontent.com/Bobronium/copium/4ca9135187020f75fa4b3373d2272f2efd060b2c/assets/copium_logo_512.png" media="(prefers-color-scheme: dark)">
    <source srcset="https://raw.githubusercontent.com/Bobronium/copium/4ca9135187020f75fa4b3373d2272f2efd060b2c/assets/copium_logo_light_512.png" media="(prefers-color-scheme: light)">
    <img src="https://raw.githubusercontent.com/Bobronium/copium/4ca9135187020f75fa4b3373d2272f2efd060b2c/assets/copium_logo_512.png" alt="Copium Logo" width="200" align="left">
</picture>

<div align="center">
  <picture>
    <source srcset="https://raw.githubusercontent.com/Bobronium/copium/042576240477a960ee00477ce60c09e92d1b306c/assets/chart_dark.svg" media="(prefers-color-scheme: dark)">
    <source srcset="https://raw.githubusercontent.com/Bobronium/copium/042576240477a960ee00477ce60c09e92d1b306c/assets/chart_light.svg" media="(prefers-color-scheme: light)">
    <img src="https://raw.githubusercontent.com/Bobronium/copium/042576240477a960ee00477ce60c09e92d1b306c/assets/chart_light.svg" alt="Benchmark results bar chart" width="600">
  </picture>
</div>
<div align="center">
  <i>Benchmarked on <a href="https://github.com/Bobronium/copium/actions/workflows/build.yaml">GitHub Actions</a> using <a href="https://github.com/Bobronium/copium/blob/f540fecceb13b517a2fdcc99b1ca388e8826bca7/tools/run_benchmark.py">tools/run_benchmark.py</a>, charted with <a href="https://github.com/Bobronium/copium/blob/f540fecceb13b517a2fdcc99b1ca388e8826bca7/tools/generate_chart.py">tools/generate_chart.py</a></i>
</div>

## Highlights

- ⚡ 4-28x faster than `copy.deepcopy()` on builtin types
- 🧠 uses ~44% less memory than `copy.deepcopy()` on average
- 🧪 passes all tests in `CPython/Lib/test/test_copy.py`
- 🎯 behaves exactly the same as `copy.deepcopy()` for all [`datamodelzoo.CASES`](https://github.com/Bobronium/datamodelzoo/blob/00ec1632b4037670628c865a0db2c8bc259abb75/src/datamodelzoo/__init__.py#L18)
- 🛡️ tested for refcount, recursion, threading and memo edge cases
- 🐍 pre-built wheels for Python 3.10-3.14 on Linux/macOS/Windows (x64/ARM64)
- 🔓 passes all tests on free-threaded Python builds

## Installation

> [!WARNING]
> This is an alpha version. Run your test suite with `COPIUM_PATCH_DEEPCOPY=1` to verify compatibility in your environment.
 
```bash
pip install copium
```


## Usage

Simply export `COPIUM_PATCH_DEEPCOPY=1` before running your application. You
don't have to change a single line of code:

`cat example.py`

```python
from copy import deepcopy

assert deepcopy(x := []) is not x
```

`COPIUM_PATCH_DEEPCOPY=1 python example.py`

---

To enable the patch manually:

```py
import copium.patch

copium.patch.enable()
```

---

To use manually:

```py
from copium import deepcopy

assert deepcopy(x := []) is not x
```

The `copium` module includes all public declarations of stdlib `copy` module, so it's generally safe to:

```diff
- from copy import copy, deepcopy, Error
+ from copium import copy, deepcopy, Error
```

---

## Speedups on Python 3.14

### `tuple`

- `()` ~5.66x
- `tuple[int, ...]` ~12.46x (20 items)
- `tuple[int, ...]` ~28.28x (5000 items)
- `tuple[tuple[str, tuple[tuple[str, tuple[tuple[str, tuple[tuple[str, tuple[int, ...]]]]]]]]]]` ~14.54x

### `list`

- `[]` ~4.97x
- `list[int]` ~9.58x (20 items)
- `list[int]` ~16.23x (5000 items)
- `list[str | list[str | list[str | list[str | list[int]]]]]` ~9.19x

### `dict`

- `{}` ~4.59x
- `dict[str, int]` ~5.95x (20 items)
- `dict[str, int]` ~3.94x (5000 items)
- `dict[str, dict[str, ...]]` ~6.19x

### `set`

- `set()` ~15.87x
- `set[int]` ~6.55x (20 items)
- `set[int]` ~3.69x (5000 items)
- `set[frozenset[frozenset[int]]]` ~13.72x

### other

- `int`/`str`/`bytes` ~4.86x
- `dataclasses` ~2.74x

Expect much higher speedups on Python 3.13 and lower.


