Package: bplustree
An on-disk B+tree for Python 3.It feels like a dict, but stored on disk. When to use it?When the data to store does not fit in memoryWhen the data needs to be persistedWhen keeping the keys in order is importantThis project is under development: the format of the file may change between
versions. Do not use as your primary source of data.QuickstartInstall Bplustree with pip:pip install bplustreeCreate a B+tree index stored on a file and use it with:>>>frombplustreeimportBPlusTree>>>tree=BPlusTree('/tmp/bplustree.db',order=50)>>>tree[1]=b'foo'>>>tree[2]=b'bar'>>>tree[1]b'foo'>>>tree.get(3)>>>tree.close()Keys and valuesKeys must have a natural order and must be serializable to bytes. Some default
serializers for the most common types are provided. For example to index UUIDs:>>>importuuid>>>frombplustreeimportBPlusTree,UUIDSerializer>>>tree=BPlusTree('/tmp/bplustree.db',serializer=UUIDSerializer(),key_size=16)>>>tree.insert(uuid.uuid1(),b'foo')>>>list(tree.keys())[UUID('48f2553c-de23-4d20-95bf-6972a89f3bc0')]Values on the other hand are always bytes. They can be of arbitrary length,
the parametervalue_size=128defines the upper bound of value sizes that
can be stored in the tree itself. Values exceeding this limit are stored in
overflow pages. Each overflowing value occupies at least a full page.IteratingSince keys are kept in order, it is very efficient to retrieve elements in
order:>>>foriintree:...print(i)...12>>>forkey,valueintree.items():...print(key,value)...1b'foo'2b'bar'It is also possible to iterate over a subset of the tree by giving a Python
slice:>>>forkey,valueintree.items(slice(start=0,stop=10):...print(key,value)...1b'foo'2b'bar'Both methods use a generator so they don’t require loading the whole content
in memory, but copying a slice of the tree into a dict is also possible:>>>tree[0:10]{1:b'foo',2:b'bar'}ConcurrencyThe tree is thread-safe, it follows the multiple readers/single writer pattern.It is safe to:Share an instance of aBPlusTreebetween multiple threadsIt is NOT safe to:Share an instance of aBPlusTreebetween multiple processesCreate multiple instances ofBPlusTreepointing to the same fileDurabilityA write-ahead log (WAL) is used to ensure that the data is safe. All changes
made to the tree are appended to the WAL and only merged into the tree in an
operation called a checkpoint, usually when the tree is closed. This approach
is heavily inspired by other databases like SQLite.If tree doesn’t get closed properly (power outage, process killed…) the WAL
file is merged the next time the tree is opened.PerformancesLike any database, there are many knobs to finely tune the engine and get the
best performance out of it:order, or branching factor, defines how many entries each node will holdpage_sizeis the amount of bytes allocated to a node and the length of
read and write operations. It is best to keep it close to the block size of
the diskcache_sizeto keep frequently used nodes at hand. Big caches prevent the
expensive operation of creating Python objects from raw pages but use more
memorySome advices to efficiently use the tree:Insert elements in ascending order if possible, prefer UUID v1 to UUID v4Insert in batch withtree.batch_insert(iterator)instead of usingtree.insert()in a loopLet the tree iterate for you instead of usingtree.get()in a loopUsetree.checkpoint()from time to time if you insert a lot, this will
prevent the WAL from growing unboundedUse small keys and values, set their limit and overflow values accordinglyStore the file and WAL on a fast diskLicenseMIT
Copyright (c) 2017 Nicolas Le ManchetPermission 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.