Unit tests

Python bindings to knncolle

Overview

The knncolle Python package implements Python bindings to the C++ library of the same name for nearest neighbor (NN) searches. Downstream packages can re-use the NN search algorithms in knncolle, either via Python or by directly calling C++ through shared pointers. This is inspired by the BiocNeighbors Bioconductor package, which does the same thing for R packages.

Quick start

Install it:

pip install knncolle

And run the desired search:

# Mocking up data with 20 dimensions, 1000 observations
import numpy
y = numpy.random.rand(1000, 20) 

# Building a search index with vantage point trees:
import knncolle
params = knncolle.VptreeParameters()
idx = knncolle.build_index(params, y)

# Performing the search:
res = knncolle.find_knn(idx, num_neighbors=10)

res.index # each row is an observation, each column is a neighbor
## array([[881,  74, 959, ..., 917, 385, 522],
##        [586,   8, 874, ..., 895,  52, 591],
##        [290, 215, 298, ..., 148, 627, 443],
##        ...,
##        [773,  44, 669, ..., 775, 287, 819],
##        [658, 847, 691, ..., 630, 861, 434],
##        [796, 158,  11, ..., 606, 815, 882]],
##       shape=(1000, 10), dtype=uint32)

res.distance # distances to the neighbors in 'index'
## array([[1.12512471, 1.12792771, 1.15229055, ..., 1.21499808, 1.2176659 ,
##         1.23952456],
##        [0.9988856 , 1.03782045, 1.08870223, ..., 1.16899062, 1.17007634,
##         1.17147675],
##        [1.2471501 , 1.26328659, 1.2643019 , ..., 1.32229768, 1.32679721,
##         1.33451926],
##        ...,
##        [1.05765983, 1.08981287, 1.11295647, ..., 1.18395012, 1.1976068 ,
##         1.21577234],
##        [0.96758957, 1.02363497, 1.05326212, ..., 1.21518925, 1.22847612,
##         1.24106054],
##        [1.17846147, 1.22299985, 1.2248128 , ..., 1.35088373, 1.39274142,
##         1.40207528]], shape=(1000, 10))

Check out the reference documentation for details.

Switching algorithms

We can easily switch to a different NN search algorithm by supplying a different params object. For example, we could use the Approximate Nearest Neighbors Oh Yeah (Annoy) algorithm:

an_params = knncolle.AnnoyParameters()
an_idx = knncolle.build_index(an_params, y)

We can also tweak the search parameters in our Parameters object during or after its construction. For example, with the hierarchical navigable small worlds (HNSW) algorithm:

h_params = knncolle.HnswParameters(num_links=20, distance="Manhattan")
h_params.ef_construction = 150
h_idx = knncolle.build_index(h_params, y)

Currently, we support Annoy, HNSW, vantage point trees, k-means k-nearest neighbors, and an exhaustive brute-force search. More algorithms can be added by extending knncolle as described below without any change to end-user code.

Use with C++

The raison d'être of the knncolle Python package is to facilitate the re-use of the neighbor search algorithms by C++ code in other Python packages. The idea is that downstream packages will link against the knncolle C++ interface so that they can re-use the search indices created by the knncolle Python package. This allows developers to (i) save time by avoiding the need to re-compile all desired algorithms and (ii) support more algorithms in extensions to the knncolle framework. To do so:

Add knncolle.includes() and assorthead.includes() to the compiler's include path for the package. This can be done through include_dirs= of the Extension() definition in setup.py or by adding a target_include_directories() in CMake, depending on the build system.
Call knncolle.build_index() to construct a GenericIndex instance. This exposes a shared pointer to the C++-allocated index via its ptr property.
Pass ptr to C++ code as a uintptr_t referencing a knncolle::Prebuilt. which can be interrogated as described in the knncolle documentation.

So, for example, the C++ code in our downstream package might look like this:

#include "knncolle_py.h"

int do_something(uintptr_t ptr) {
    const auto& prebuilt = knncolle_py::cast_prebuilt(ptr)->ptr;
    // Do something with the search index interface.
    return 1;
}

PYBIND11_MODULE(lib_downstream, m) {
    m.def("do_something", &do_something);
}

Which can then be called from Python:

from . import lib_downstream as lib
from knncolle import GenericIndex

def do_something(idx: GenericIndex):
    return lib.do_something(idx.ptr)

In some scenarios, it may be more convenient to construct the search index inside C++, e.g., if the dataset to be searched is not available before the call to the C++ function. This can be accommodated by accepting a uintptr_t to a knncolle::Builder in the C++ code:

#include "knncolle_py.h"

int do_something_mk2(uintptr_t ptr) {
    const auto& builder = knncolle_py::cast_builder(ptr)->ptr;
    // The builder is a algorithm-specific factory that accepts a matrix and
    // returns a search index for that algorithm. Presumably we construct a
    // new search index inside this function and use it.
    return 1;
}

PYBIND11_MODULE(lib_downstream, m) {
    m.def("do_something_mk2", &do_something_mk2);
}

A pointer to the knncolle::Builder can be created by the define_builder() function in Python, and then passed to the C++ code:

from . import lib_downstream as lib
from knncolle import define_builder, Parameters

def do_something(param: Parameters):
    builder, cls = define_builder(param)
    return lib.do_something_mk2(builder.ptr)

Check out the included header for more definitions.

Extending to more algorithms

Via `define_builder()`

The best way to extend knncolle is to do so in C++. This involves writing subclasses of the interfaces in the knncolle library. Once this is done, it is a simple matter of writing the following Python bindings:

Implement a SomeNewParameters class that inherits from Parameters.
Implement a SomeNewIndex class that inherits from GenericIndex. This should accept a single ptr in its constructor and have a ptr property that returns the same value.
Register a define_builder() method that dispatches on SomeNewParameters. This should call into C++ and return a tuple containing a Builder object and the SomeNewIndex constructor.

No new methods are required for find_knn(), build_index(), etc. as the default method will work automatically if a define_builder() method is available. This approach also allows the new method to be used in C++ code of downstream packages.

Without `define_builder()`

If it is not possible to implement the search algorithm in C++, we can still extend knncolle in Python. Each extension package should:

Implement a SomeNewParameters class that inherits from Parameters.
Implement a SomeNewIndex class that inherits from Index. This can have an arbitrary structure, i.e., it does not need to have a ptr property.
Register a build_index() method that dispatches on SomeNewParameters. This should return an instance of SomeNewIndex.
Register a method for any number of these generics: find_knn(), find_distance(), find_neighbors(), query_knn(), query_distance(), query_neighbors(). These methods should dispatch on SomeNewParameters and return the appropriate result object.

This approach will not support re-use by C++ code in other Python packages.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

knncolle-0.3.1.tar.gz (43.1 kB view details)

Uploaded Aug 14, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

knncolle-0.3.1-cp315-cp315t-musllinux_1_2_x86_64.whl (1.3 MB view details)

Uploaded Aug 14, 2026 CPython 3.15tmusllinux: musl 1.2+ x86-64

knncolle-0.3.1-cp315-cp315t-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (232.2 kB view details)

Uploaded Aug 14, 2026 CPython 3.15tmanylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

knncolle-0.3.1-cp315-cp315t-macosx_11_0_arm64.whl (183.8 kB view details)

Uploaded Aug 14, 2026 CPython 3.15tmacOS 11.0+ ARM64

knncolle-0.3.1-cp315-cp315-musllinux_1_2_x86_64.whl (1.3 MB view details)

Uploaded Aug 14, 2026 CPython 3.15musllinux: musl 1.2+ x86-64

knncolle-0.3.1-cp315-cp315-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (231.6 kB view details)

Uploaded Aug 14, 2026 CPython 3.15manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

knncolle-0.3.1-cp315-cp315-macosx_11_0_arm64.whl (183.8 kB view details)

Uploaded Aug 14, 2026 CPython 3.15macOS 11.0+ ARM64

knncolle-0.3.1-cp314-cp314t-musllinux_1_2_x86_64.whl (1.3 MB view details)

Uploaded Aug 14, 2026 CPython 3.14tmusllinux: musl 1.2+ x86-64

knncolle-0.3.1-cp314-cp314t-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (232.1 kB view details)

Uploaded Aug 14, 2026 CPython 3.14tmanylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

knncolle-0.3.1-cp314-cp314t-macosx_11_0_arm64.whl (183.8 kB view details)

Uploaded Aug 14, 2026 CPython 3.14tmacOS 11.0+ ARM64

knncolle-0.3.1-cp314-cp314-musllinux_1_2_x86_64.whl (1.3 MB view details)

Uploaded Aug 14, 2026 CPython 3.14musllinux: musl 1.2+ x86-64

knncolle-0.3.1-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (231.6 kB view details)

Uploaded Aug 14, 2026 CPython 3.14manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

knncolle-0.3.1-cp314-cp314-macosx_11_0_arm64.whl (183.8 kB view details)

Uploaded Aug 14, 2026 CPython 3.14macOS 11.0+ ARM64

knncolle-0.3.1-cp313-cp313-musllinux_1_2_x86_64.whl (1.3 MB view details)

Uploaded Aug 14, 2026 CPython 3.13musllinux: musl 1.2+ x86-64

knncolle-0.3.1-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (231.4 kB view details)

Uploaded Aug 14, 2026 CPython 3.13manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

knncolle-0.3.1-cp313-cp313-macosx_11_0_arm64.whl (183.5 kB view details)

Uploaded Aug 14, 2026 CPython 3.13macOS 11.0+ ARM64

knncolle-0.3.1-cp312-cp312-musllinux_1_2_x86_64.whl (1.3 MB view details)

Uploaded Aug 14, 2026 CPython 3.12musllinux: musl 1.2+ x86-64

knncolle-0.3.1-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (231.4 kB view details)

Uploaded Aug 14, 2026 CPython 3.12manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

knncolle-0.3.1-cp312-cp312-macosx_11_0_arm64.whl (183.4 kB view details)

Uploaded Aug 14, 2026 CPython 3.12macOS 11.0+ ARM64

knncolle-0.3.1-cp311-cp311-musllinux_1_2_x86_64.whl (1.3 MB view details)

Uploaded Aug 14, 2026 CPython 3.11musllinux: musl 1.2+ x86-64

knncolle-0.3.1-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (229.7 kB view details)

Uploaded Aug 14, 2026 CPython 3.11manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

knncolle-0.3.1-cp311-cp311-macosx_11_0_arm64.whl (181.8 kB view details)

Uploaded Aug 14, 2026 CPython 3.11macOS 11.0+ ARM64

knncolle-0.3.1-cp310-cp310-musllinux_1_2_x86_64.whl (1.3 MB view details)

Uploaded Aug 14, 2026 CPython 3.10musllinux: musl 1.2+ x86-64

knncolle-0.3.1-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (228.4 kB view details)

Uploaded Aug 14, 2026 CPython 3.10manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

knncolle-0.3.1-cp310-cp310-macosx_11_0_arm64.whl (180.7 kB view details)

Uploaded Aug 14, 2026 CPython 3.10macOS 11.0+ ARM64

File details

Details for the file knncolle-0.3.1.tar.gz.

File metadata

Download URL: knncolle-0.3.1.tar.gz
Upload date: Aug 14, 2026
Size: 43.1 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for knncolle-0.3.1.tar.gz
Algorithm	Hash digest
SHA256	`3dda874dfefadf353dd1b064aa01134df0923b5456bb308b97e116aebdb1789a`
MD5	`b85f25757572b48ee92c6695d9a65bd8`
BLAKE2b-256	`6356623b9bb27ec545aa9670c6f184eb93dfb580f995ca5c909d8a577aa03f68`

Algorithm	Hash digest
SHA256	`de0758b64cf398ec181705ca1e51d23f3174fe8d6344550842adbcfbb0bcd234`
MD5	`0c54576c8966a14031143b55d15a973c`
BLAKE2b-256	`6f2123ba1f4299f717c783198859bc53d2501f7312ef3fa52beaf8fbd66f13d7`

Algorithm	Hash digest
SHA256	`9c191af8a277e8f8118e4bd7c76fe8eabf32615bd3b4175cbe4ebd4a6d0611ad`
MD5	`9316d99f6e9c9e503cfa3e3e5d207e0c`
BLAKE2b-256	`5415078136ef8313da65637c4ec8f94469792fdae8076751f15861971b609fd9`

Algorithm	Hash digest
SHA256	`1e1a8bf8aeb059390f0e6b5976b2f008b36d21887ad54d98d80eaca54fc5f664`
MD5	`f3e9437eb33d5633ba4837550c406ff4`
BLAKE2b-256	`22b3c40548d911d3853d4051cfd8f8b3f8536fca8e37c9e15a416a3bf0993438`

Algorithm	Hash digest
SHA256	`88081e8e4f1f7dbe3dc5fce5a3267fc4fd8c9b020e662b9d4dc4ea5b59b0b143`
MD5	`2e6c5647ddc795f93a2328c3ab94877b`
BLAKE2b-256	`906a836420bdf175cb4ef754aebd0b860cec5f81a800d420cb0df2385de67154`

Algorithm	Hash digest
SHA256	`e49301d2130594a9e9b40532c376f6d51ee1520b263e49ae9522607182b73082`
MD5	`5d3272a0f01290c1d11944c0a8fec4a0`
BLAKE2b-256	`d593cbe1b3e1dbd6cc3af89b91c99f0bfd39a130b110a89f4707d04a800593a7`

Algorithm	Hash digest
SHA256	`0b50c7e9a00744e212a75cabf6e35838757df9bd471cc878a3fccb2539b0768e`
MD5	`bdd34944cfab842648a6459683368822`
BLAKE2b-256	`dd328986987c01a462a1f3ee31272304d67261bb59363160fe95814d02e34d24`

Algorithm	Hash digest
SHA256	`a2439ca022b94e87bd8c1ca49ed51ddfe9867e061cce0fbd9bc1e7f67804fb34`
MD5	`a6139a90b913176ada07d81f2f4f616a`
BLAKE2b-256	`4abeefa28f9872ac90bc535d1c55526932125107fb56290c2973ce77445815e7`

Algorithm	Hash digest
SHA256	`da04b39da11b3e02d89db817b03636600e0ce508265d613eac71cc3f8814677d`
MD5	`6b7b1d1d1bf88f1473fb9af4cb5302d6`
BLAKE2b-256	`63b6c577feea13ad1e8f2c179ee780518f7b8bb06542c24f9e7ebbc105bfc808`

Algorithm	Hash digest
SHA256	`c5c8bbf423afc69db5f14376f08c87acb9e65beb5c03559069fd74c5624aabfb`
MD5	`0a012a71bfe5184a770df5c59eb4864a`
BLAKE2b-256	`a4d8da1203cbd73208f8683099205cae8b08bece1e656b7e92dc10329915eaf3`

Algorithm	Hash digest
SHA256	`a1b8b47547a1994cfcaa5d3a67e3c250dac1986cf6779e27740d3757b314bb25`
MD5	`849f4031a6f23e439aeb7adc6d21e2e5`
BLAKE2b-256	`134f85d185243edcec483ae9edbc54eb12b6298a6582ceeb2304839a8d601c17`

Algorithm	Hash digest
SHA256	`2cd2b86723b42211a7510912e08a8cbb6d0d1a3f6f511ccb8e4101676965a467`
MD5	`72228e81f88d6293c53a8f75649061dd`
BLAKE2b-256	`d5b762f58f6e69aeab44d4924b5051bc9f116ef622a4b3a1c7b91073b782f103`

Algorithm	Hash digest
SHA256	`fac7d544e4032c731d229f94abfbedecc2b2545516f70d032b342542b2abd704`
MD5	`bb92971e19ef91e86d4e236a2cf8773c`
BLAKE2b-256	`f50ded82aa2c43ccecd13172991c6fe74ace60665a078173dc118ebcd0bdbfea`

Algorithm	Hash digest
SHA256	`7a0b0f0710d5d1f0ddafd6f37585f8ff611a01d47335101e86ec5c81d341ef49`
MD5	`2b500da8db273df62edbc5962b0de8fa`
BLAKE2b-256	`7751a28f8f4bed295ef64d6e7157d616ad6b7619ea6fa8b3529895fe574cd057`

Algorithm	Hash digest
SHA256	`f805aea3b17f21465e42e6d7a2351ff6c46b4da3921e8279f275f1bbbb2aab5f`
MD5	`2a0cf8511df5da705985b032244edda3`
BLAKE2b-256	`5be849a751aa59d2f81522ef2c6da3bdeb1ad45e493b7a842362a83c65825964`

Algorithm	Hash digest
SHA256	`5b9aded6be541f242cb1e2140297ae1e9bb8c27686844e1ff1dda9b5a8af41c6`
MD5	`5a6a2460c2fdc48140d2cd85d94b3d9d`
BLAKE2b-256	`ffbc09e3f7907b9cf3585b699a3ed574ddb7256814aac9b2b1a659558d930797`

Algorithm	Hash digest
SHA256	`71df575ad7460bef7b319a63509a1f4a25ff04fe9cc59a31b245b8b1c565050b`
MD5	`59d4105050e320bc4595fd6048fb9018`
BLAKE2b-256	`d0a7c9fe7c75438dcae739b1e9bb461d3dd02341f92200e0356e25651a2fa57b`

Algorithm	Hash digest
SHA256	`7e699a49834b66e58319d9b367f4bdb74a9d285e3c2e084b1f413bcd1e722e82`
MD5	`5bf0cd8336e5c6b726b63b52d18f524d`
BLAKE2b-256	`17ed43f8e4637a5d5ad8f8514028b516bef46837fc6f963423cb50f4e0b62d5d`

Algorithm	Hash digest
SHA256	`6867078af65ec98fcf25dec16a6903c090e096586e336775d29fb0582acfc8b1`
MD5	`d42967a6793767b6170fa0d29bfbe759`
BLAKE2b-256	`d1969a9176012407d23d628f8827632294ab6d9e0f3fca4bada0247f20a3d3e2`

Algorithm	Hash digest
SHA256	`66404fa607f766ae806c26814faf412bbde61cb4e0d054d93ab61daa697e0b06`
MD5	`c4a4b6c3aafce1c02b8f9d2ff16832eb`
BLAKE2b-256	`3da87944ae7bd681cad41650a7c1bea3a5a99812f185c06ffc43a89ec99c2338`

Algorithm	Hash digest
SHA256	`f5b2c094a598e0028b18ef5df667a4c6bc7bf5df568917c59267ca681191aecb`
MD5	`994d7d467926f822e0ed48b3ff77acee`
BLAKE2b-256	`d4e319c1ddef582b265276e33efc6d2a99e0a3458577abefc90650d66a2157ea`

knncolle 0.3.1

Python bindings to knncolle

Overview

Quick start

Switching algorithms

Other searches

Use with C++

Extending to more algorithms

Via define_builder()

Without define_builder()

Project links

Key dates

2 maintainers

Credits

GitHub Statistics

License

Requires

Provides Extra

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

Via `define_builder()`

Without `define_builder()`

Algorithm	Hash digest
SHA256	`50d09e37a31b150d5c5c52ce5e3050b40544e5a5ddd6d463f34a51a01e6acedf`
MD5	`6904ed628df102697d1672fa34e056c9`
BLAKE2b-256	`864a8a66de21544d434a755b176618ba8361c3e91558fd57909bd8b146acab97`

Algorithm	Hash digest
SHA256	`9664bf2e3a394decc93cb78d7bf6d00ac030dc90e09d2b5e1b12032c28342bdf`
MD5	`6339f79c3f6521d73ecd6b27c5044801`
BLAKE2b-256	`7a3000eedc3df646f90b95581dd0a3806c27e5bb19d5049ebcd64efff9e96c47`

Algorithm	Hash digest
SHA256	`aec20cb95293db7d398999adf235ab6bb1b61e04ad3bd12b8a0b2851428ddda8`
MD5	`be9060e05443713ff68f2f62efa49294`
BLAKE2b-256	`0441d4ea4a6d2b3a3d37f99ca114fad2c422dd49455a35c97d6885a846af8fd7`

Algorithm	Hash digest
SHA256	`38835ba4ee894d815c3f07eb183f3a21ec647bcfd59bffa1ec055dec94947ea9`
MD5	`f4304038a19db6e26285e268a0774593`
BLAKE2b-256	`59981f925018073ed49cb58fa0cd79572cd694fe6b6a95e7034fa01c8cc20a14`