fast-unionfind 1.0.0__tar.gz

fast_unionfind-1.0.0/LICENSE

@@ -0,0 +1,29 @@
+Copyright © 2017-2018 Symantec Corporation. All Rights Reserved.
+Copyright © 2026 Matteo Dell'Amico. All Rights Reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+1. Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in the
+documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

fast_unionfind-1.0.0/MANIFEST.in

@@ -0,0 +1,16 @@
+# What an sdist must carry. setuptools' defaults ship .py but not .pyx or
+# .pxd, and setup.py cythonizes core.pyx -- so without this line a source
+# distribution has no sources to build from. The .pxd matters twice over
+# here: it is not merely a declaration file but where the algorithm itself
+# lives, so a consumer cimporting this package needs it installed.
+recursive-include src/fast_unionfind *.pyx *.pxd
+
+# The generated C is a build artefact: gitignored, and regenerated at build
+# time because Cython is a build requirement (see pyproject's build-system).
+# Excluded so that an sdist cannot pick up a stale copy left in the working
+# tree and build from that instead.
+recursive-exclude src/fast_unionfind *.c
+
+# tests/ ships, so ship the helper every test module imports; without it the
+# shipped tests cannot even be collected.
+include tests/unionfind_testlib.py

fast_unionfind-1.0.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: fast-unionfind
+Version: 1.0.0
+Summary: Disjoint sets (union-find) at C speed, with no dependencies
+Author-email: Matteo Dell'Amico <della@linux.it>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://gitlab.com/bobtables/fast-unionfind
+Keywords: union-find,disjoint-set,dsu,kruskal,connected-components,cython,free-threading
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Cython
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: Cython>=3.0; extra == "test"
+Requires-Dist: setuptools; extra == "test"
+Dynamic: license-file
+
+# fast-unionfind
+
+Disjoint sets (union-find) for Python at C speed, with no dependencies.
+
+```python
+from fast_unionfind import unionfind
+
+uf = unionfind(1_000_000)
+uf.unite(3, 7)          # True: two sets became one
+uf.unite(7, 3)          # False: already the same set
+uf.connected(3, 7)      # True
+uf[7] == uf.find(3)     # True
+```
+
+It is link-by-rank with path halving, so any sequence of m operations over
+n elements costs O(m α(n)) — effectively constant per operation. It has no
+runtime dependencies at all (not even numpy), it is compiled with Cython, and
+it is safe to query from many threads at once, including on free-threaded
+Python.
+
+## Why another union-find
+
+Two reasons.
+
+**There was no C-speed union-find available as a stand-alone package.** The
+fast implementations live inside larger libraries, as internals you cannot
+depend on.
+
+**Building one efficiently is less trivial than it looks.** The union-finds
+inside two widely used clustering libraries, `hdbscan` and scikit-learn, had
+subtle performance bugs that made single-linkage labelling quadratic while
+every result stayed correct. We found and reported both:
+[hdbscan#731](https://github.com/scikit-learn-contrib/hdbscan/issues/731) and
+[scikit-learn#34626](https://github.com/scikit-learn/scikit-learn/issues/34626)
+(a fix is in review as
+[#34872](https://github.com/scikit-learn/scikit-learn/pull/34872)).
+
+## Install
+
+```
+pip install fast-unionfind
+```
+
+Building from source needs a C compiler and Cython.
+
+## Python API
+
+`unionfind(n)` builds a union-find over the elements `0 … n-1` and picks the
+narrowest index width that fits: a `UnionFind32` (4 bytes per element) up to
+2³²−1 elements, a `UnionFind64` (8 bytes) beyond that. Either class can also be
+built directly. `UnionFind` is their common base, for annotations and
+`isinstance` checks, and cannot be instantiated itself.
+
+| | |
+|---|---|
+| `uf.unite(x, y)` | Merge the sets holding x and y. `True` if they were distinct. |
+| `uf.union(x, y)` | Alias of `unite`, under the name the literature uses. |
+| `uf.find(x)`, `uf[x]` | The representative of x's set. |
+| `uf.connected(x, y)` | Whether x and y are in the same set. |
+| `len(uf)` | The number of elements, not of sets. |
+| `uf.labels()` | Every element's representative, as an `array.array`. |
+| `uf.width` | 32 or 64. |
+| `width_for(n)` | The width `unionfind(n)` would choose, without allocating. |
+
+Elements are ids, not sequence positions. Anything outside `range(n)` raises
+`IndexError`, negative values included, so `uf[-1]` is an error rather than
+the last element.
+
+Representatives change as sets merge, so compare them rather than store them.
+
+There is no set count or grouping method, because both are one visible line on
+top of `labels()`, and writing them out keeps their O(n) cost in plain sight:
+
+```python
+n_sets = len(set(uf.labels()))
+
+groups = collections.defaultdict(list)
+for element, root in enumerate(uf.labels()):
+    groups[root].append(element)
+```
+
+`labels()` returns a buffer, so `numpy.frombuffer(uf.labels(), dtype=...)` wraps
+it without copying if you do have numpy.
+
+Union-finds pickle exactly, ranks included, so a restored one links later unions
+the same way the original would have.
+
+## Cython API
+
+The union-find itself is not a method. It is a pair of fused `cdef inline`
+functions **defined in the `.pxd`**, so a module that cimports them compiles its
+own copy, specialised for its index width, and the C compiler inlines them into
+your loop:
+
+```cython
+from libc.stdint cimport uint32_t
+from fast_unionfind.core cimport UnionFind32, uf_find, uf_unite
+
+def kruskal(Py_ssize_t n, uint32_t[::1] ei, uint32_t[::1] ej):
+    cdef UnionFind32 uf = UnionFind32(n)      # owns the memory
+    cdef uint32_t* parents = uf.parents       # plain struct reads:
+    cdef unsigned char* ranks = uf.ranks      # the class is final
+    cdef Py_ssize_t k, merged = 0
+    with nogil:
+        for k in range(ei.shape[0]):
+            if uf_unite(parents, ranks, ei[k], ej[k]):
+                merged += 1
+    return merged
+```
+
+| | |
+|---|---|
+| `uf_find(parents, x)` | Root of x, halving the path. `noexcept nogil`, unchecked. |
+| `uf_unite(parents, ranks, x, y)` | Link by rank. `True` if it merged. `noexcept nogil`, unchecked. |
+
+Both are fused over `uint32_t` and `uint64_t`. Use `UnionFind64`'s `parents` for
+the wide one. They do no bounds checking, which is the point of this layer. Keep
+the owning `UnionFind32`/`UnionFind64` alive for as long as you use its pointers.
+
+The `.pxd` files ship in the wheel, so an installed package is enough for
+Cython to resolve the cimport. To be explicit anyway, add
+`fast_unionfind.get_include()` to your extension's `include_dirs`.
+
+Since the core compiles into your module, a consumer does not even import
+`fast_unionfind` at runtime for these calls, only to construct the object that
+owns the arrays.
+
+## Thread safety
+
+Concurrent `find`s are safe as long as no union is running at the same time.
+They do race, on path-compression stores, but harmlessly. Every such store
+points a node at one of its own ancestors, so the root stays reachable and
+unchanged. A lost write can only undo some compression, never send a walk
+somewhere wrong, and the aligned integer slots mean no store is ever
+half-written. This is what makes a lock-free parallel "are these already
+connected?" filter over a Kruskal edge list sound.
+
+Unions must not run concurrently with each other or with finds. Serialise
+them.
+
+The extension is declared `freethreading_compatible`, and nothing in it needs
+the GIL.
+
+## Performance
+
+Two workloads over m = 4n random edges, written as Cython loops. The first,
+`unite_all`, is Kruskal's scan. The second, `filter_scan`, unites half the
+edges and then asks "already connected?" of all of them, which is two finds
+per edge. The comparison is the same algorithm written the usual way, as
+methods on a `cdef class` cimported from another extension module, where
+Cython must call through the imported vtable and nothing can inline.
+
+| n | workload | inlined core | cimported class | speedup |
+|---:|---|---:|---:|---:|
+| 100 000 | `unite_all` | 2 ms | 3 ms | 1.51× |
+| 100 000 | `filter_scan` | 2 ms | 4 ms | 1.64× |
+| 300 000 | `unite_all` | 7 ms | 9 ms | 1.36× |
+| 300 000 | `filter_scan` | 9 ms | 13 ms | 1.49× |
+| 1 000 000 | `unite_all` | 24 ms | 35 ms | 1.45× |
+| 1 000 000 | `filter_scan` | 32 ms | 51 ms | 1.57× |
+| 10 000 000 | `unite_all` | 1.17 s | 1.53 s | 1.30× |
+| 10 000 000 | `filter_scan` | 1.59 s | 2.17 s | 1.37× |
+
+Best of 50 runs at n ≤ 300 000 and best of 5 above that, on x86-64 with
+GCC -O3, Python 3.14 and Cython 3.3. The gain narrows at 10 million elements,
+where the 40 MB parent array no longer fits in cache and memory traffic
+dominates the call cost.
+
+From Python, method calls cost about 42 ns each, which is almost all
+interpreter overhead and the same as calling a class method directly.
+
+The class-based column was measured before that implementation was retired, so
+it cannot be re-run from this repository. `python benchmarks/bench.py` times
+this package's workloads and Python-level calls, compiling the workloads on
+first use.
+
+## License
+
+BSD 3-clause; see [LICENSE](LICENSE).

fast_unionfind-1.0.0/README.md

@@ -0,0 +1,179 @@
+# fast-unionfind
+
+Disjoint sets (union-find) for Python at C speed, with no dependencies.
+
+```python
+from fast_unionfind import unionfind
+
+uf = unionfind(1_000_000)
+uf.unite(3, 7)          # True: two sets became one
+uf.unite(7, 3)          # False: already the same set
+uf.connected(3, 7)      # True
+uf[7] == uf.find(3)     # True
+```
+
+It is link-by-rank with path halving, so any sequence of m operations over
+n elements costs O(m α(n)) — effectively constant per operation. It has no
+runtime dependencies at all (not even numpy), it is compiled with Cython, and
+it is safe to query from many threads at once, including on free-threaded
+Python.
+
+## Why another union-find
+
+Two reasons.
+
+**There was no C-speed union-find available as a stand-alone package.** The
+fast implementations live inside larger libraries, as internals you cannot
+depend on.
+
+**Building one efficiently is less trivial than it looks.** The union-finds
+inside two widely used clustering libraries, `hdbscan` and scikit-learn, had
+subtle performance bugs that made single-linkage labelling quadratic while
+every result stayed correct. We found and reported both:
+[hdbscan#731](https://github.com/scikit-learn-contrib/hdbscan/issues/731) and
+[scikit-learn#34626](https://github.com/scikit-learn/scikit-learn/issues/34626)
+(a fix is in review as
+[#34872](https://github.com/scikit-learn/scikit-learn/pull/34872)).
+
+## Install
+
+```
+pip install fast-unionfind
+```
+
+Building from source needs a C compiler and Cython.
+
+## Python API
+
+`unionfind(n)` builds a union-find over the elements `0 … n-1` and picks the
+narrowest index width that fits: a `UnionFind32` (4 bytes per element) up to
+2³²−1 elements, a `UnionFind64` (8 bytes) beyond that. Either class can also be
+built directly. `UnionFind` is their common base, for annotations and
+`isinstance` checks, and cannot be instantiated itself.
+
+| | |
+|---|---|
+| `uf.unite(x, y)` | Merge the sets holding x and y. `True` if they were distinct. |
+| `uf.union(x, y)` | Alias of `unite`, under the name the literature uses. |
+| `uf.find(x)`, `uf[x]` | The representative of x's set. |
+| `uf.connected(x, y)` | Whether x and y are in the same set. |
+| `len(uf)` | The number of elements, not of sets. |
+| `uf.labels()` | Every element's representative, as an `array.array`. |
+| `uf.width` | 32 or 64. |
+| `width_for(n)` | The width `unionfind(n)` would choose, without allocating. |
+
+Elements are ids, not sequence positions. Anything outside `range(n)` raises
+`IndexError`, negative values included, so `uf[-1]` is an error rather than
+the last element.
+
+Representatives change as sets merge, so compare them rather than store them.
+
+There is no set count or grouping method, because both are one visible line on
+top of `labels()`, and writing them out keeps their O(n) cost in plain sight:
+
+```python
+n_sets = len(set(uf.labels()))
+
+groups = collections.defaultdict(list)
+for element, root in enumerate(uf.labels()):
+    groups[root].append(element)
+```
+
+`labels()` returns a buffer, so `numpy.frombuffer(uf.labels(), dtype=...)` wraps
+it without copying if you do have numpy.
+
+Union-finds pickle exactly, ranks included, so a restored one links later unions
+the same way the original would have.
+
+## Cython API
+
+The union-find itself is not a method. It is a pair of fused `cdef inline`
+functions **defined in the `.pxd`**, so a module that cimports them compiles its
+own copy, specialised for its index width, and the C compiler inlines them into
+your loop:
+
+```cython
+from libc.stdint cimport uint32_t
+from fast_unionfind.core cimport UnionFind32, uf_find, uf_unite
+
+def kruskal(Py_ssize_t n, uint32_t[::1] ei, uint32_t[::1] ej):
+    cdef UnionFind32 uf = UnionFind32(n)      # owns the memory
+    cdef uint32_t* parents = uf.parents       # plain struct reads:
+    cdef unsigned char* ranks = uf.ranks      # the class is final
+    cdef Py_ssize_t k, merged = 0
+    with nogil:
+        for k in range(ei.shape[0]):
+            if uf_unite(parents, ranks, ei[k], ej[k]):
+                merged += 1
+    return merged
+```
+
+| | |
+|---|---|
+| `uf_find(parents, x)` | Root of x, halving the path. `noexcept nogil`, unchecked. |
+| `uf_unite(parents, ranks, x, y)` | Link by rank. `True` if it merged. `noexcept nogil`, unchecked. |
+
+Both are fused over `uint32_t` and `uint64_t`. Use `UnionFind64`'s `parents` for
+the wide one. They do no bounds checking, which is the point of this layer. Keep
+the owning `UnionFind32`/`UnionFind64` alive for as long as you use its pointers.
+
+The `.pxd` files ship in the wheel, so an installed package is enough for
+Cython to resolve the cimport. To be explicit anyway, add
+`fast_unionfind.get_include()` to your extension's `include_dirs`.
+
+Since the core compiles into your module, a consumer does not even import
+`fast_unionfind` at runtime for these calls, only to construct the object that
+owns the arrays.
+
+## Thread safety
+
+Concurrent `find`s are safe as long as no union is running at the same time.
+They do race, on path-compression stores, but harmlessly. Every such store
+points a node at one of its own ancestors, so the root stays reachable and
+unchanged. A lost write can only undo some compression, never send a walk
+somewhere wrong, and the aligned integer slots mean no store is ever
+half-written. This is what makes a lock-free parallel "are these already
+connected?" filter over a Kruskal edge list sound.
+
+Unions must not run concurrently with each other or with finds. Serialise
+them.
+
+The extension is declared `freethreading_compatible`, and nothing in it needs
+the GIL.
+
+## Performance
+
+Two workloads over m = 4n random edges, written as Cython loops. The first,
+`unite_all`, is Kruskal's scan. The second, `filter_scan`, unites half the
+edges and then asks "already connected?" of all of them, which is two finds
+per edge. The comparison is the same algorithm written the usual way, as
+methods on a `cdef class` cimported from another extension module, where
+Cython must call through the imported vtable and nothing can inline.
+
+| n | workload | inlined core | cimported class | speedup |
+|---:|---|---:|---:|---:|
+| 100 000 | `unite_all` | 2 ms | 3 ms | 1.51× |
+| 100 000 | `filter_scan` | 2 ms | 4 ms | 1.64× |
+| 300 000 | `unite_all` | 7 ms | 9 ms | 1.36× |
+| 300 000 | `filter_scan` | 9 ms | 13 ms | 1.49× |
+| 1 000 000 | `unite_all` | 24 ms | 35 ms | 1.45× |
+| 1 000 000 | `filter_scan` | 32 ms | 51 ms | 1.57× |
+| 10 000 000 | `unite_all` | 1.17 s | 1.53 s | 1.30× |
+| 10 000 000 | `filter_scan` | 1.59 s | 2.17 s | 1.37× |
+
+Best of 50 runs at n ≤ 300 000 and best of 5 above that, on x86-64 with
+GCC -O3, Python 3.14 and Cython 3.3. The gain narrows at 10 million elements,
+where the 40 MB parent array no longer fits in cache and memory traffic
+dominates the call cost.
+
+From Python, method calls cost about 42 ns each, which is almost all
+interpreter overhead and the same as calling a class method directly.
+
+The class-based column was measured before that implementation was retired, so
+it cannot be re-run from this repository. `python benchmarks/bench.py` times
+this package's workloads and Python-level calls, compiling the workloads on
+first use.
+
+## License
+
+BSD 3-clause; see [LICENSE](LICENSE).

fast_unionfind-1.0.0/pyproject.toml

@@ -0,0 +1,103 @@
+[build-system]
+requires = ["setuptools>=77", "Cython>=3.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fast-unionfind"
+version = "1.0.0"
+description = "Disjoint sets (union-find) at C speed, with no dependencies"
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+authors = [{ name = "Matteo Dell'Amico", email = "della@linux.it" }]
+requires-python = ">=3.10"
+# No runtime dependencies at all, and that is a feature rather than an
+# accident: the structure needs two raw arrays, so pulling in numpy for them
+# would cost every install on an interpreter the scientific stack has not
+# built wheels for yet -- free-threaded builds in particular, where that lag
+# is routinely months.
+dependencies = []
+keywords = ["union-find", "disjoint-set", "dsu", "kruskal",
+            "connected-components", "cython", "free-threading"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Cython",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+Homepage = "https://gitlab.com/bobtables/fast-unionfind"
+
+[project.optional-dependencies]
+# The Cython-consumer test compiles a module against the installed .pxd,
+# which is the only thing here that needs a toolchain at test time.
+test = ["pytest", "Cython>=3.0", "setuptools"]
+
+[tool.setuptools]
+packages = ["fast_unionfind"]
+# src/ layout: keeps the repo root free of a bare `fast_unionfind/` directory,
+# which would otherwise shadow the installed package whenever the root lands
+# on sys.path (running pytest from here, `python -c "import fast_unionfind"`,
+# ...) and silently import a namespace package with no extension module in it.
+package-dir = { "" = "src" }
+
+[tool.setuptools.package-data]
+# The .pxd is not a build artefact here, it is the algorithm: a consumer that
+# cimports this package compiles these bodies into its own object file. An
+# install without them still runs Python callers and silently breaks Cython
+# ones, so they ship with the wheel, not just the sdist.
+fast_unionfind = ["*.pxd"]
+
+[tool.cibuildwheel]
+# 64-bit only: Windows' "auto" still adds 32-bit x86, which this package has
+# never been built or tested on. PyPy and GraalPy are opt-in in cibuildwheel,
+# so this is CPython, free-threaded builds included.
+skip = "*-win32"
+# The whole suite against every wheel; it takes seconds. The test extra
+# brings Cython and setuptools, so the cimport test compiles a consumer
+# against the installed .pxd -- the part a broken wheel would break.
+test-extras = ["test"]
+test-command = "pytest {project}/tests"
+
+[tool.pytest.ini_options]
+# importlib mode does not prepend rootdir/test dirs to sys.path, so tests
+# always resolve `fast_unionfind` to the *installed* package rather than to
+# whatever directory happens to sit next to them. Belt and braces with the
+# src/ layout above: either alone fixes the shadowing, together they make it
+# impossible.
+addopts = "--import-mode=importlib"
+testpaths = ["tests"]
+# importlib mode deliberately does not put the test directory on sys.path, so
+# the shared scaffolding in tests/unionfind_testlib.py needs saying
+# explicitly. The module is named for this package rather than something like
+# `helpers`, since what goes on sys.path here could otherwise shadow someone
+# else's module.
+pythonpath = ["tests"]
+
+[tool.ruff]
+# 79, matching the prose in this project's docstrings and comments, which are
+# hand-wrapped to it. The formatter leaves comment and docstring *text* alone,
+# so it will not undo that wrapping -- but a wider limit would let new code
+# drift away from it.
+line-length = 79
+extend-exclude = ["src/*/*.c", "build"]
+
+[tool.ruff.lint]
+# F is the useful half: undefined names, unused imports, star-import damage.
+# E501 keeps the line length honest. Deliberately not the whole default set --
+# this is a tidiness tool here, and the bugs worth catching in this codebase
+# have all been the kind no linter sees.
+select = ["F", "E501"]
+
+[tool.ruff.lint.pycodestyle]
+# The formatter targets 79 and reflows code to it, but it deliberately leaves
+# comment and docstring *text* alone -- so a sentence that lands on 80 cannot
+# be fixed by the tool, only by hand, and would nag forever. E501 is therefore
+# a backstop against genuinely runaway lines rather than a second opinion on
+# prose: wrap at 79 by hand as the rest of this codebase does, and let the
+# linter object only past 88.
+max-line-length = 88

fast_unionfind-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fast_unionfind-1.0.0/setup.py

@@ -0,0 +1,34 @@
+"""Build script for the Cython extension; all metadata is in pyproject.toml."""
+
+import os
+import sys
+
+from Cython.Build import cythonize
+from setuptools import Extension, setup
+
+if sys.platform == "win32":
+    extra_compile_args = ["/O2"]
+else:
+    # -O3 so the parent-array init loop vectorises and the inlined find/unite
+    # in a caller's scan stay tight. No -ffast-math family here and no
+    # -fopenmp: there is no floating point in this package and no parallel
+    # loop of its own -- callers parallelise over it, which needs nothing
+    # from this build.
+    extra_compile_args = ["-O3"]
+    # -march=native produces a faster but machine-specific binary; opt in
+    # when building for the machine you'll run on, not for a portable wheel.
+    if os.environ.get("FAST_UNIONFIND_NATIVE"):
+        extra_compile_args.append("-march=native")
+
+setup(
+    ext_modules=cythonize(
+        [
+            Extension(
+                "fast_unionfind.core",
+                ["src/fast_unionfind/core.pyx"],
+                extra_compile_args=extra_compile_args,
+            ),
+        ],
+        language_level=3,
+    ),
+)

fast_unionfind-1.0.0/src/fast_unionfind/__init__.pxd

@@ -0,0 +1,5 @@
+# Marks fast_unionfind as a cimportable package, so that an installed copy
+# resolves `from fast_unionfind.core cimport uf_find, UnionFind32` off
+# sys.path. numpy ships the same empty marker for the same reason; without it
+# Cython finds the directory but not the package, and the cimport fails with
+# "cannot find module".

fast_unionfind-1.0.0/src/fast_unionfind/__init__.py

@@ -0,0 +1,65 @@
+# Copyright (c) 2017-2018 Symantec Corporation. All Rights Reserved.
+# Copyright (c) 2026 Matteo Dell'Amico. All Rights Reserved.
+# Redistribution and use governed by the BSD 3-clause license in LICENSE.
+
+"""Disjoint sets (union-find) at C speed, with no dependencies.
+
+`unionfind(n)` builds one over the elements `0..n-1`, picking `UnionFind32`
+or `UnionFind64` by size; `UnionFind` is the base type to name in annotations
+and `isinstance` checks. Merge with `unite(x, y)`, which returns True only
+when it actually merged something, and query with `find(x)` or `uf[x]`.
+
+    >>> from fast_unionfind import unionfind
+    >>> uf = unionfind(5)
+    >>> uf.unite(0, 1), uf.unite(1, 2), uf.unite(0, 2)
+    (True, True, False)
+    >>> uf.connected(0, 2)
+    True
+
+Link by rank and path halving, so a sequence of m operations over n elements
+costs O(m alpha(n)) -- effectively constant per operation. Path compression is
+easy to lose without a single wrong answer to show for it: the union-finds in
+`hdbscan` and scikit-learn lost theirs that way, and their labelling went
+quadratic. See the README.
+
+Cython callers should `cimport` the core rather than call these methods:
+
+    from fast_unionfind.core cimport UnionFind32, uf_find, uf_unite
+
+`uf_find` and `uf_unite` are fused `cdef inline` functions defined in the
+.pxd, so they inline into your loop -- no call, no GIL, no numpy. The
+extension type is only there to own the allocation.
+"""
+
+import os
+
+from .core import (
+    UnionFind,
+    UnionFind32,
+    UnionFind64,
+    unionfind,
+    width_for,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "UnionFind",
+    "UnionFind32",
+    "UnionFind64",
+    "get_include",
+    "unionfind",
+    "width_for",
+]
+
+
+def get_include():
+    """Directory holding this package's .pxd files.
+
+    Cython finds them on sys.path unaided, thanks to the `__init__.pxd`
+    marker, so this is belt and braces for a build that would rather be
+    explicit:
+
+        Extension(..., include_dirs=[fast_unionfind.get_include()])
+    """
+    return os.path.dirname(__file__)