copium 0.1.dev1__tar.gz

copium-0.1.dev1/.github/workflows/build.yaml

@@ -0,0 +1,81 @@
+name: Build
+
+on:
+  push:
+    tags: [ "v*" ]
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+
+jobs:
+  wheels:
+    # Separate native runners so mac gets native arm64 & x86_64 (universal2), Windows gets MSVC, etc.
+    strategy:
+      fail-fast: false
+      max-parallel: 64
+      matrix:
+        build:
+          # Linux
+          - { os: ubuntu-latest,    platform: linux,   archs: x86_64, arch_label: "x86_64" }
+          - { os: ubuntu-24.04-arm, platform: linux,   archs: aarch64, arch_label: "ARM64" }
+          # - { os: ubuntu-latest, platform: linux, archs: ppc64le, arch_label: "ppc64le" }
+          # - { os: ubuntu-latest, platform: linux, archs: s390x,   arch_label: "s390x" }
+          # Windows
+          # - { os: windows-latest,   platform: windows, archs: AMD64,  arch_label: "x64" }
+          # - { os: windows-11-arm,   platform: windows, archs: ARM64,  arch_label: "ARM64" }
+          # macOS
+          - { os: macos-15,         platform: macos,   archs: arm64,  arch_label: "Apple Silicon" }
+          - { os: macos-15-intel,   platform: macos,   archs: x86_64, arch_label: "Intel" }
+        python:
+          - { display: "3.10", tag: "cp310" }
+          - { display: "3.11", tag: "cp311" }
+          - { display: "3.12", tag: "cp312" }
+          - { display: "3.13", tag: "cp313" }
+          - { display: "3.14", tag: "cp314" }
+
+    runs-on: ${{ matrix.build.os }}
+
+    name: "Python ${{ matrix.python.display }} / ${{ fromJSON('{\"linux\":\"Linux\",\"windows\":\"Windows\",\"macos\":\"macOS\"}')[matrix.build.platform] }} / ${{ matrix.build.arch_label }}"
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up QEMU
+        if: runner.os == 'Linux' && runner.arch == 'X64'
+        uses: docker/setup-qemu-action@v3
+        with:
+          platforms: all
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v3.2.1
+        env:
+          CIBW_BUILD: "${{ matrix.python.tag }}-*"
+          CIBW_ARCHS: "${{ matrix.build.archs }}"
+          CIBW_BUILD_VERBOSITY: 1
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: "Wheels-${{ matrix.python.display }}-${{ fromJSON('{\"linux\":\"Linux\",\"windows\":\"Windows\",\"macos\":\"macOS\"}')[matrix.build.platform] }}-${{ matrix.build.arch_label }}"
+          path: ./wheelhouse/*.whl
+
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Build sdist
+        run: uv build --sdist
+      - name: Upload sdist
+        uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz

copium-0.1.dev1/.github/workflows/lint.yaml

@@ -0,0 +1,22 @@
+name: Lint
+on:
+  push:
+    branches: [ "**" ]
+    tags: [ "*" ]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.14"
+          enable-cache: true
+      - uses: go-task/setup-task@v1
+      - run: task setup
+      - run: task lint

copium-0.1.dev1/.github/workflows/publish.yaml

@@ -0,0 +1,87 @@
+name: Publish
+
+on:
+  # Auto-publish after Build completes
+  workflow_run:
+    workflows: [ "Build" ]
+    types: [ "completed" ]
+  # Manual publish from a specific Build run
+  workflow_dispatch:
+    inputs:
+      run-id:
+        description: "Build workflow run ID to fetch artifacts from (Actions ➜ Build ➜ a completed run)"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+  id-token: write
+
+concurrency:
+  # Use head SHA for auto, current SHA for manual, so concurrent publishes of the same ref collapse.
+  group: publish-${{ (github.event_name == 'workflow_run' && github.event.workflow_run.head_sha) || github.sha }}
+  cancel-in-progress: true
+
+jobs:
+  publish:
+    # Conditions:
+    # - Auto path: Build succeeded, and original trigger was a push to main OR a tag push (head_branch == null for tags)
+    # - Manual path: always allowed; caller supplies run-id
+    if: >
+      (github.event_name == 'workflow_run' &&
+       github.event.workflow_run.conclusion == 'success' &&
+       github.event.workflow_run.event == 'push' &&
+       (github.event.workflow_run.head_branch == 'main' || github.event.workflow_run.head_branch == null))
+      || (github.event_name == 'workflow_dispatch')
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/copium
+    steps:
+      - name: Resolve source run-id
+        id: resolve
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_run" ]; then
+            echo "RUN_ID=${{ github.event.workflow_run.id }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "RUN_ID=${{ inputs.run-id }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Prepare directories
+        run: |
+          rm -rf artifacts dist
+          mkdir -p artifacts dist
+
+      - name: Download Wheels
+        uses: dawidd6/action-download-artifact@v3
+        with:
+          run_id: ${{ steps.resolve.outputs.RUN_ID }}
+          name: "^Wheels-"
+          name_is_regexp: true
+          path: artifacts
+          if_no_artifact_found: fail
+
+      - name: Download sdist
+        uses: dawidd6/action-download-artifact@v3
+        with:
+          run_id: ${{ steps.resolve.outputs.RUN_ID }}
+          name: sdist
+          path: artifacts
+          if_no_artifact_found: fail
+
+      - name: Flatten artifacts into ./dist
+        shell: bash
+        run: |
+          shopt -s globstar nullglob
+          # Copy wheels and sdists from any artifact subfolder into ./dist
+          for f in artifacts/**/*.whl artifacts/**/*.tar.gz; do
+            cp -v "$f" dist/
+          done
+          echo "Contents of dist:"
+          ls -l dist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          skip-existing: true  # Safe for dev versions or reruns

copium-0.1.dev1/.github/workflows/test.yaml

@@ -0,0 +1,25 @@
+name: Test
+on:
+  push:
+    branches: [ "**" ]
+    tags: [ "*" ]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Python ${{ matrix.python }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13", "3.14", "3.14t", "3.15"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+          enable-cache: true
+      - uses: go-task/setup-task@v1
+      - run: task test

copium-0.1.dev1/.github/workflows/typecheck.yaml

@@ -0,0 +1,27 @@
+name: Typecheck
+on:
+  push:
+    branches: [ "**" ]
+    tags: [ "*" ]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  typecheck:
+    name: Python ${{ matrix.python }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: [
+          "3.10", "3.11", "3.12", "3.13", "3.14"
+        ]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+          enable-cache: true
+      - uses: go-task/setup-task@v1
+      - run: task typecheck

copium-0.1.dev1/.gitignore

@@ -0,0 +1,41 @@
+# Python / build
+__pycache__/
+*.py[cod]
+*$py.class
+.build/
+./build
+dist/
+.eggs/
+*.egg-info/
+
+# venv
+.venv/
+.env
+venv/
+
+# tooling
+.pytest_cache/
+.mypy_cache/
+.pytype/
+.pyre/
+.dmypy.json
+.hypothesis/
+
+# coverage
+.coverage
+.coverage.*
+htmlcov/
+
+# editors
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+.idea/
+.DS_Store
+.build-cache
+.task
+.pgo
+*.so

copium-0.1.dev1/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) <year> <copyright holders>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

copium-0.1.dev1/LICENSES/MIT.txt

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) <year> <copyright holders>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

copium-0.1.dev1/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: copium
+Version: 0.1.dev1
+Summary: Fastest deepcopy implementation for CPython
+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"
+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
+
+# copium
+
+[![image](https://img.shields.io/pypi/v/copium.svg)](https://pypi.python.org/pypi/copium)
+[![image](https://img.shields.io/pypi/l/copium.svg)](https://pypi.python.org/pypi/copium)
+[![image](https://img.shields.io/pypi/pyversions/copium.svg)](https://pypi.python.org/pypi/copium)
+[![Actions status](https://github.com/Bobronium/copium/actions/workflows/build.yml/badge.svg)](https://github.com/Bobronium/copium/actions)
+
+An extremely fast Python copy/deepcopy implementation, written in C.
+
+<div align="center">
+  <picture>
+    <source srcset="https://raw.githubusercontent.com/Bobronium/copium/main/assets/chart_dark.svg" media="(prefers-color-scheme: dark)">
+    <source srcset="https://raw.githubusercontent.com/Bobronium/copium/main/assets/chart_light.svg" media="(prefers-color-scheme: light)">
+    <img src="https://raw.githubusercontent.com/Bobronium/copium/main/assets/chart_light.svg" alt="Benchmark results bar chart">
+  </picture>
+</div>
+
+<div align="center">
+  <i>Getting a deep copy of <a href="https://github.com/python-jsonschema/jsonschema/blob/0798cd7a59caea669e2de2ecac9c6e2dfcb57f6d/jsonschema/validators.py#L812">jsonschema.Draft202012Validator.META_SCHEMA</a>.</i>
+</div>
+
+## Highlights
+
+- ~3x faster on mixed data
+- ~6x faster on typical data
+- [~30 faster in some cases](#benchmarks)
+- [Requires **zero** code changes to adopt](#1-you-set-copium_patch_deepcopy1-before-launch)
+- Passes all tests from `CPython/Lib/test/test_copy.py`
+
+## Installation
+
+```bash
+pip install copium
+```
+
+## Usage
+
+`copium` is designed to be drop-in replacement for `copy` module.
+
+After installation deepcopy will be fast in either of 3 cases:
+
+##### 1) You set `COPIUM_PATCH_DEEPCOPY=1` before launch
+
+##### 2) You call `copium.patch.enable()` manually at launch
+
+##### 3) You use `copium.deepcopy()` directly
+
+Generally any code that uses stdlib `copy` can be replaced with `copium` simply by:
+
+```diff
+- from copy import deepcopy
++ from copium import deepcopy
+```
+
+Alternatively, you can import `copium.patch` once and enable it:
+
+```python
+import copium.patch
+
+
+copium.patch.enable()
+```
+
+Or just `export COPIUM_PATCH_DEEPCOPY=1` before running your Python process.
+
+This will automatically call `copium.patch.enable()` on start, and all calls to `copy.deepcopy()` will be forwarded to
+`copium.deepcopy()`. On Python 3.12+ there's no performance overhead compared to direct
+usage.
+
+There are two main benefits of using `copium.patch`,
+
+- It requires zero code changes
+- It automatically makes any third party code that uses deepcopy faster, for
+  instance, it will speed up instantiations of pydantic
+  models with mutable defaults
+  \(see [pydantic_core](https://github.com/pydantic/pydantic-core/blob/f1239f81d944bcda84bffec64527d46f041ccc9e/src/validators/with_default.rs#L23)).
+
+## Caveats
+
+- `copium.deepcopy()` ignores `sys.getrecursionlimit()`. It still may raise `RecursionError` at some point, but at much
+  larger depths than default interpreter recursion limit (see `tests.test_copium.test_recursion_error`)
+- unless `memo` argument supplied as `dict` when calling `copium.deepcopy()`, special lightweight memo storage will be
+  used to reduce memoization overhead. It implements `MutableMapping` methods, so any custom `__deepcopy__` methods
+  should work as expected
+- `copium.deepcopy()` will raise `TypeError` if `type(memo) is not dict` — if you're unsure what it means, don't worry —
+  you don't need to supply memo to deepcopy in the first place.
+- `copium` uses unstable CPython API. This means that it might break on new major Python release
+
+## Benchmarks
+
+A full benchmark suite is in progress and will be published soon.
+In the meanwhile, you can reproduce the results shown in the chart above with this minimal script
+
+<details>
+<summary>Pyperf case</summary>
+
+```shell
+cat > benchmark.py << 'PY'
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#     "pyperf",
+#     "copium",
+# ]
+# ///
+import pyperf
+
+runner = pyperf.Runner()
+
+setup = """
+import copy
+from decimal import Decimal
+
+payload = {
+        "a": 1,
+        "b": (b := [(1, 2, 3), (4, 5, 6)]),
+        "c": [Decimal("3.14"), complex(), [], (), frozenset(), b],
+}
+"""
+
+runner.timeit(name="deepcopy", stmt=f"b=copy.deepcopy(payload)", setup=setup)
+PY
+```
+
+```shell
+uv run --python 3.14t benchmark.py -q -o copy3.14t.json && \
+COPIUM_PATCH_DEEPCOPY=1 PYTHON_GIL=0 \
+uv run --python 3.14t benchmark.py -q -o copium3.14t.json --copy-env && \
+uvx pyperf compare_to copy3.14t.json copium3.14t.json --table
+```
+
+Output:
+
+```shell
+deepcopy: Mean +- std dev: 20.8 us +- 1.6 us
+deepcopy: Mean +- std dev: 928 ns +- 11 ns
++--------------+---------+--------------------+
+| Benchmark | copy    | copium                |
++===========+=========+=======================+
+| deepcopy  | 20.8 us | 928 ns: 22.40x faster |
++-----------+---------+-----------------------+
+```
+
+```shell
+❯ uv run --python 3.13 benchmark.py -q -o copy3.13.json && \
+COPIUM_PATCH_DEEPCOPY=1 \
+uv run --python 3.13 benchmark.py -q -o copium3.13.json --copy-env && \
+uvx pyperf compare_to copy3.13.json copium3.13.json --table
+```
+
+```shell
+deepcopy: Mean +- std dev: 10.8 us +- 0.9 us
+deepcopy: Mean +- std dev: 880 ns +- 23 ns
++-----------+-----------+-----------------------+
+| Benchmark | copy3.13t | copium3.13t           |
++===========+===========+=======================+
+| deepcopy  | 10.8 us   | 880 ns: 12.26x faster |
++-----------+-----------+-----------------------+
+```
+
+```shell
+❯ uv run --python 3.13t benchmark.py -q -o copy3.13t.json && \
+COPIUM_PATCH_DEEPCOPY=1 PYTHON_GIL=0 \
+uv run --python 3.13t benchmark.py -q -o copium3.13t.json --copy-env && \
+uvx pyperf compare_to copy3.13t.json copium3.13t.json --table
+```
+
+```shell
+deepcopy: Mean +- std dev: 29.0 us +- 6.7 us
+deepcopy: Mean +- std dev: 942 ns +- 29 ns
++-----------+-----------+-----------------------+
+| Benchmark | copy3.13t | copium3.13t           |
++===========+===========+=======================+
+| deepcopy  | 29.0 us   | 942 ns: 30.84x faster |
++-----------+-----------+-----------------------+
+```
+
+</details>
+
+## Development
+
+- Install Task: https://taskfile.dev
+- All checks: `task` / `task MATRIX=1`