bsondb

PyPI version Python versions License: MIT

An embedded, file-backed document database for Python with a PyMongo-like local API (BsonDBClient, Database, Collection, ObjectId), built on a native C BSON serialization engine, an mmap-backed storage engine, and a persisted on-disk B-Tree index.

There is no network protocol and no real mongod involved — BsonDBClient is a local facade over BSON documents stored in memory-mapped files on disk.

  • License: MIT
  • Python: 3.10+
  • Dependencies: none (stdlib + native extension only)

Table of contents

Features

Area What's implemented
BSON codec encode(dict) -> bytes / decode(bytes) -> dict, ObjectId, full exception hierarchy
Storage engine Append-only, mmap-backed collection data file per collection, with crash recovery on unclean shutdown
Collection API Insert, find, update, replace, delete, count/distinct, drop, compact (see table below)
Indexing Persisted on-disk B+Tree per indexed field, used to accelerate equality queries and enforce unique constraints

Quickstart

pip install -e ".[dev]"

import bsondb

client = bsondb.BsonDBClient("./data")
coll = client.mydb.people

coll.create_index("age")
coll.insert_many([{"name": "Ada", "age": 36}, {"name": "Bo", "age": 20}])
print(list(coll.find({"age": {"$gte": 30}})))

coll.update_one({"name": "Ada"}, {"$set": {"age": 37}})
coll.delete_one({"name": "Bo"})
client.close()

Supported operations

Category Methods / operators
Insert insert_one, insert_many
Query find, find_one — dot-notation fields, projection, skip/limit
Query operators $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $and, $or, $not
Update update_one, update_many ($set, $unset, $inc, upsert), replace_one
Find-and-modify find_one_and_update, find_one_and_delete, find_one_and_replace
Delete delete_one, delete_many
Aggregation count_documents, estimated_document_count, distinct
Maintenance drop, compact
Indexing create_index, drop_index, list_indexes

Development

Quickest path, using Task:

task install   # create .venv and pip install -e ".[dev]"
task test      # run the Python and C test suites

Without Task:

# Install with dev dependencies and run the Python test suite
pip install -e ".[dev]"
pytest tests/python_tests/ -v

# Optional: smoke-build the standalone C engine + C test executables
cmake -S . -B build -DBUILD_TESTING=ON && cmake --build build
ctest --test-dir build --output-on-failure

For OS-specific prerequisites (C compiler, Task, CMake), the full Taskfile.yml task reference, and a walkthrough of how a document flows through the codebase, see docs/development.md.

Project layout

Path Contents
include/custom_bson/ Public C headers (BSON engine, mmap abstraction, storage/record format, B-Tree index)
src/c_engine/ Storage/BSON engine implementation (pure C11, no Python dependency)
src/python_bindings/ CPython C-API bindings: _bson_core.c (encode/decode), _storage_core.c (storage/index)
python/bsondb/ Pure-Python package: ObjectId, exceptions, BsonDBClient/Database/Collection, query/index/cursor logic
tests/ C and Python test suites
docs/ Wire protocol spec and API reference

Documentation

Scope limits

  • Single-process access only
  • Single-field indexes only
  • Index acceleration applies to equality queries only

See docs/api_reference.md for full details.

License

MIT

Project links

Data verified by PyPI on Aug 1, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for rrkpdev from gravatar.com rrkpdev

GitHub Statistics

Data verified by PyPI on Aug 1, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Provides Extra

dev

Tags

database bson embedded-database document-database mongodb pymongo

Classifiers

Report project as malware

Download files

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

Source Distribution

bsondb-0.0.1.tar.gz (49.7 kB view details)

Uploaded Source

Built Distributions

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

bsondb-0.0.1-cp314-cp314-win_amd64.whl (58.3 kB view details)

Uploaded CPython 3.14Windows x86-64

bsondb-0.0.1-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (167.9 kB view details)

Uploaded CPython 3.14manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

bsondb-0.0.1-cp313-cp313-win_amd64.whl (57.3 kB view details)

Uploaded CPython 3.13Windows x86-64

bsondb-0.0.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (167.8 kB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

bsondb-0.0.1-cp312-cp312-win_amd64.whl (57.3 kB view details)

Uploaded CPython 3.12Windows x86-64

bsondb-0.0.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (167.8 kB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

bsondb-0.0.1-cp311-cp311-win_amd64.whl (57.2 kB view details)

Uploaded CPython 3.11Windows x86-64

bsondb-0.0.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (167.3 kB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

bsondb-0.0.1-cp310-cp310-win_amd64.whl (57.2 kB view details)

Uploaded CPython 3.10Windows x86-64

bsondb-0.0.1-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (165.7 kB view details)

Uploaded CPython 3.10manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

File details

Details for the file bsondb-0.0.1.tar.gz.

File metadata

  • Download URL: bsondb-0.0.1.tar.gz
  • Upload date:
  • Size: 49.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for bsondb-0.0.1.tar.gz
Algorithm Hash digest
SHA256 a87eeeb6845590b7f6bc859b4370ceca7a9e02ba9ec1e75510cc4e7e7cba605d
MD5 057a3ce2e9e61dbc47eaba943ad2b616
BLAKE2b-256 c782f655463ad4b937b8ef5aa3ee0894bd87ddf07566de73afdff73766d05b6e

See more details on using hashes here.

Provenance

The following attestation bundles were made for bsondb-0.0.1.tar.gz:

Publisher: publish.yml on Ravisxcr/bsondb

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file bsondb-0.0.1-cp314-cp314-win_amd64.whl.

File metadata

  • Download URL: bsondb-0.0.1-cp314-cp314-win_amd64.whl
  • Upload date:
  • Size: 58.3 kB
  • Tags: CPython 3.14, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for bsondb-0.0.1-cp314-cp314-win_amd64.whl
Algorithm Hash digest
SHA256 360b7a2cc4a44a4ee9e7a823481780d28e55e6cab21b1b95e606b21a0b7d9ba5
MD5 f317ae595c942d884c653af4c7008478
BLAKE2b-256 4ea84690368cf0a471f7b7be0af1e8d85a13dd5ed2e57db875543a3d07e0b2ee

See more details on using hashes here.

Provenance

The following attestation bundles were made for bsondb-0.0.1-cp314-cp314-win_amd64.whl:

Publisher: publish.yml on Ravisxcr/bsondb

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file bsondb-0.0.1-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for bsondb-0.0.1-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 178ee2d901c71902b4287539be04fb912a74b71392aea2dd7a809c0b8a6d0f8a
MD5 783827acddfd7f79b60f52b2afd6f436
BLAKE2b-256 4ea5c55e1a96e08962aeed72cac42db4f551e6b16dd8d3cd9000a643b7bf8869

See more details on using hashes here.

Provenance

The following attestation bundles were made for bsondb-0.0.1-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl:

Publisher: publish.yml on Ravisxcr/bsondb

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file bsondb-0.0.1-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: bsondb-0.0.1-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 57.3 kB
  • Tags: CPython 3.13, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for bsondb-0.0.1-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 bdaccc67677db7124b8c454a44a2ed1ecf3e24bf583a2bbc57174ab17617cea4
MD5 961e870fd165e757554f06cedfbb7bba
BLAKE2b-256 f9155ab4151ee0bfbe549be44b61c6f293871e1f3a7c0bb4b2b2d7e057ed0da0

See more details on using hashes here.

Provenance

The following attestation bundles were made for bsondb-0.0.1-cp313-cp313-win_amd64.whl:

Publisher: publish.yml on Ravisxcr/bsondb

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file bsondb-0.0.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for bsondb-0.0.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 f0c7c189720d7dd35b5445c8e781eda617979904cc28ffa43eefcbcba52cebdb
MD5 445fac3195bec19dcc1448a1895a3978
BLAKE2b-256 42727c7e621ec5fd43c95c8d032cb00270b4f346bac9f9d6389acde1484976d5

See more details on using hashes here.

Provenance

The following attestation bundles were made for bsondb-0.0.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl:

Publisher: publish.yml on Ravisxcr/bsondb

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file bsondb-0.0.1-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: bsondb-0.0.1-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 57.3 kB
  • Tags: CPython 3.12, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for bsondb-0.0.1-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 cc6f1f15589ad6a613e2aa7d157150dac79df39df312b6c49d3091cbe07dff2b
MD5 64e0e25d9a68636c34e5ab3344ea62cd
BLAKE2b-256 e39ee4975aa44c59bf41cf1f924192fc5b3e556185cb23da93d8691776f7f9a2

See more details on using hashes here.

Provenance

The following attestation bundles were made for bsondb-0.0.1-cp312-cp312-win_amd64.whl:

Publisher: publish.yml on Ravisxcr/bsondb

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file bsondb-0.0.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for bsondb-0.0.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 7e1c0a0d7377585cd0a2bf040e5d8b602152c8e072e472264dcd597c882a1276
MD5 a0fb6fd7945528b587321f15e9be9967
BLAKE2b-256 3c41adae3f01a333fb126269abf2161526cae453cabc9f6779695ce8cb8106dd

See more details on using hashes here.

Provenance

The following attestation bundles were made for bsondb-0.0.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl:

Publisher: publish.yml on Ravisxcr/bsondb

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file bsondb-0.0.1-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: bsondb-0.0.1-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 57.2 kB
  • Tags: CPython 3.11, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for bsondb-0.0.1-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 2ccd83b5162423405d7ba840915a041cd831d0bf31f2a20838675139561b97a1
MD5 880429ef85feea8443de87755590dd12
BLAKE2b-256 eb9188e06933d6b1d63d23ccdfc79492f9d8d46180fa0af77e3876fb2e90a0d2

See more details on using hashes here.

Provenance

The following attestation bundles were made for bsondb-0.0.1-cp311-cp311-win_amd64.whl:

Publisher: publish.yml on Ravisxcr/bsondb

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file bsondb-0.0.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for bsondb-0.0.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 89703e5565ad3dcaa0c3862fa56960b31dd7c088dcb615db135a836a34e17a44
MD5 3155faee789b3a6f0f8c70bc765f5964
BLAKE2b-256 66241a711029dc21eb460fe8b3b97e57305d91f96af7b0481424291fd883c6a2

See more details on using hashes here.

Provenance

The following attestation bundles were made for bsondb-0.0.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl:

Publisher: publish.yml on Ravisxcr/bsondb

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file bsondb-0.0.1-cp310-cp310-win_amd64.whl.

File metadata

  • Download URL: bsondb-0.0.1-cp310-cp310-win_amd64.whl
  • Upload date:
  • Size: 57.2 kB
  • Tags: CPython 3.10, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for bsondb-0.0.1-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 18a30b2f1112f2aa7ec22baed7fee1f06db54bea4f96e712069426c1c919faa4
MD5 4cee106aa136b1d1ede8cf219685b0f5
BLAKE2b-256 7e4890c149070a46b07718be8c3bc5e5ef31fc22ef65a29266c9a696db2f6a5b

See more details on using hashes here.

Provenance

The following attestation bundles were made for bsondb-0.0.1-cp310-cp310-win_amd64.whl:

Publisher: publish.yml on Ravisxcr/bsondb

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file bsondb-0.0.1-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for bsondb-0.0.1-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 bde4f392869f45f4c852f22be497218e7f11444bcefc7cd0f9cb4d2abb0a4d73
MD5 a7fb09c44d885ff312a69bab9cad903a
BLAKE2b-256 77ba7e6aa018e40f415a9eb28fe801996a2e2e7c8da109888cb63d27a8441eda

See more details on using hashes here.

Provenance

The following attestation bundles were made for bsondb-0.0.1-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl:

Publisher: publish.yml on Ravisxcr/bsondb

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page