diff options
Diffstat (limited to 'docs/library/btree.rst')
-rw-r--r-- | docs/library/btree.rst | 53 |
1 files changed, 32 insertions, 21 deletions
diff --git a/docs/library/btree.rst b/docs/library/btree.rst index bd7890586a..9322d32e6a 100644 --- a/docs/library/btree.rst +++ b/docs/library/btree.rst @@ -22,8 +22,14 @@ Example:: # First, we need to open a stream which holds a database # This is usually a file, but can be in-memory database - # using uio.BytesIO, a raw flash section, etc. - f = open("mydb", "w+b") + # using uio.BytesIO, a raw flash partition, etc. + # Oftentimes, you want to create a database file if it doesn't + # exist and open if it exists. Idiom below takes care of this. + # DO NOT open database with "a+b" access mode. + try: + f = open("mydb", "r+b") + except OSError: + f = open("mydb", "w+b") # Now open a database itself db = btree.open(f) @@ -33,6 +39,11 @@ Example:: db[b"1"] = b"one" db[b"2"] = b"two" + # Assume that any changes are cached in memory unless + # explicitly flushed (or database closed). Flush database + # at the end of each "transaction". + db.flush() + # Prints b'two' print(db[b"2"]) @@ -71,18 +82,18 @@ Functions other parameters are optional and keyword-only, and allow to tweak advanced parameters of the database operation (most users will not need them): - * `flags` - Currently unused. - * `cachesize` - Suggested maximum memory cache size in bytes. For a + * *flags* - Currently unused. + * *cachesize* - Suggested maximum memory cache size in bytes. For a board with enough memory using larger values may improve performance. The value is only a recommendation, the module may use more memory if values set too low. - * `pagesize` - Page size used for the nodes in BTree. Acceptable range + * *pagesize* - Page size used for the nodes in BTree. Acceptable range is 512-65536. If 0, underlying I/O block size will be used (the best compromise between memory usage and performance). - * `minkeypage` - Minimum number of keys to store per page. Default value + * *minkeypage* - Minimum number of keys to store per page. Default value of 0 equivalent to 2. - Returns a `BTree` object, which implements a dictionary protocol (set + Returns a BTree object, which implements a dictionary protocol (set of methods), and some additional methods described below. Methods @@ -92,7 +103,7 @@ Methods Close the database. It's mandatory to close the database at the end of processing, as some unwritten data may be still in the cache. Note that - this does not close underlying streamw with which the database was opened, + this does not close underlying stream with which the database was opened, it should be closed separately (which is also mandatory to make sure that data flushed from buffer to the underlying storage). @@ -101,10 +112,10 @@ Methods Flush any data in cache to the underlying stream. .. method:: btree.__getitem__(key) -.. method:: btree.get(key, default=None) -.. method:: btree.__setitem__(key, val) -.. method:: btree.__detitem__(key) -.. method:: btree.__contains__(key) + btree.get(key, default=None) + btree.__setitem__(key, val) + btree.__detitem__(key) + btree.__contains__(key) Standard dictionary methods. @@ -114,20 +125,20 @@ Methods to get access to all keys in order. .. method:: btree.keys([start_key, [end_key, [flags]]]) -.. method:: btree.values([start_key, [end_key, [flags]]]) -.. method:: btree.items([start_key, [end_key, [flags]]]) + btree.values([start_key, [end_key, [flags]]]) + btree.items([start_key, [end_key, [flags]]]) These methods are similar to standard dictionary methods, but also can take optional parameters to iterate over a key sub-range, instead of - the entire database. Note that for all 3 methods, `start_key` and - `end_key` arguments represent key values. For example, ``values()`` + the entire database. Note that for all 3 methods, *start_key* and + *end_key* arguments represent key values. For example, `values()` method will iterate over values corresponding to they key range - given. None values for `start_key` means "from the first key", no - `end_key` or its value of None means "until the end of database". - By default, range is inclusive of `start_key` and exclusive of - `end_key`, you can include `end_key` in iteration by passing `flags` + given. None values for *start_key* means "from the first key", no + *end_key* or its value of None means "until the end of database". + By default, range is inclusive of *start_key* and exclusive of + *end_key*, you can include *end_key* in iteration by passing *flags* of `btree.INCL`. You can iterate in descending key direction - by passing `flags` of `btree.DESC`. The flags values can be ORed + by passing *flags* of `btree.DESC`. The flags values can be ORed together. Constants |