LBRYCommunity/lbry-rocksdb
1
0
Fork 0
Code Issues 6 Pull requests 2 Projects Releases Packages Wiki Activity

docs

Browse source
This commit is contained in:
Jack Robison 2022-01-17 18:37:23 -05:00
parent a52c3d911d
commit cd327c06d9
No known key found for this signature in database
GPG key ID: DF25C68FE0239BB2
5 changed files with 80 additions and 72 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

53
docs/api/database.rst
View file

@ -174,6 +174,59 @@ Database object
:rtype: :py:class:`rocksdb.BaseIterator`
.. py:method:: iterator(start=None, column_family=None, iterate_lower_bound=None,
iterate_upper_bound=None, reverse=False, include_key=True,
include_value=True, fill_cache=True, prefix_same_as_start=False,
auto_prefix_mode=False)
:param `rocksdb.ColumnFamilyHandle` column_family: column family handle
:param bytes start: prefix to seek to
:param bytes iterate_lower_bound:
defines the smallest key at which the backward iterator can return an entry.
Once the bound is passed, Valid() will be false. `iterate_lower_bound` is
inclusive ie the bound value is a valid entry.
If prefix_extractor is not null, the Seek target and `iterate_lower_bound`
need to have the same prefix. This is because ordering is not guaranteed
outside of prefix domain.
:param bytes iterate_upper_bound:
defines the extent up to which the forward iterator
can returns entries. Once the bound is reached, Valid() will be false.
"iterate_upper_bound" is exclusive ie the bound value is
not a valid entry. If prefix_extractor is not null:
1. If auto_prefix_mode = true, iterate_upper_bound will be used
to infer whether prefix iterating (e.g. applying prefix bloom filter)
can be used within RocksDB. This is done by comparing
iterate_upper_bound with the seek key.
2. If auto_prefix_mode = false, iterate_upper_bound only takes
effect if it shares the same prefix as the seek key. If
iterate_upper_bound is outside the prefix of the seek key, then keys
returned outside the prefix range will be undefined, just as if
iterate_upper_bound = null.
If iterate_upper_bound is not null, SeekToLast() will position the iterator
at the first key smaller than iterate_upper_bound.
:param bool reverse: run the iteration in reverse - using `reversed` is also supported
:param bool include_key: the iterator should include the key in each iteration
:param bool include_value: the iterator should include the value in each iteration
:param bool fill_cache: Should the "data block"/"index block" read for this iteration be placed in
block cache? Callers may wish to set this field to false for bulk scans.
This would help not to the change eviction order of existing items in the
block cache. Default: true
:param bool prefix_same_as_start:
Enforce that the iterator only iterates over the same prefix as the seek.
This option is effective only for prefix seeks, i.e. prefix_extractor is
non-null for the column family and total_order_seek is false. Unlike
iterate_upper_bound, prefix_same_as_start only works within a prefix
but in both directions. Default: false
:param bool auto_prefix_mode: When true, by default use total_order_seek = true, and RocksDB can
selectively enable prefix seek mode if won't generate a different result
from total_order_seek, based on seek key, and iterator upper bound.
Not supported in ROCKSDB_LITE mode, in the way that even with value true
prefix mode is not used. Default: false
:returns:
A iterator object which is valid and ready to begin using. It will be either a key, item or value
iterator depending on the arguments provided.
:rtype: :py:class:`rocksdb.BaseIterator`
.. py:method:: snapshot()
Return a handle to the current DB state.

17
docs/conf.py
View file

@ -47,17 +47,16 @@ source_suffix = '.rst'
master_doc = 'index'
# General information about the project.
project = u'python-rocksdb'
copyright = u'2014, sh'
project = u'lbry-rocksdb'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '0.6'
version = '0.8'
# The full version, including alpha/beta/rc tags.
release = '0.6.7'
release = '0.8.2'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
@ -180,7 +179,7 @@ html_static_path = ['_static']
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'python-rocksdbdoc'
htmlhelp_basename = 'lbry-rocksdbdoc'
# -- Options for LaTeX output ---------------------------------------------
@ -200,7 +199,7 @@ latex_elements = {
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
('index', 'python-rocksdb.tex', u'python-rocksdb Documentation',
('index', 'lbry-rocksdb.tex', u'lbry-rocksdb Documentation',
u'sh', 'manual'),
]
@ -230,7 +229,7 @@ latex_documents = [
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'python-rocksdb', u'python-rocksdb Documentation',
('index', 'lbry-rocksdb', u'python-rocksdb Documentation',
[u'sh'], 1)
]
@ -244,8 +243,8 @@ man_pages = [
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', 'python-rocksdb', u'python-rocksdb Documentation',
u'sh', 'python-rocksdb', 'One line description of project.',
('index', 'lbry-rocksdb', u'lbry-rocksdb Documentation',
u'sh', 'lbry-rocksdb', 'One line description of project.',
'Miscellaneous'),
]

8
docs/index.rst
View file

@ -1,4 +1,4 @@
Welcome to python-rocksdb's documentation!
Welcome to lbry-rocksdb's documentation!
==========================================
Overview
@ -11,7 +11,7 @@ Python bindings to the C++ interface of http://rocksdb.org/ using cython::
print db.get(b"a")
Tested with python2.7 and python3.4 and RocksDB version 5.3.0
Tested with python 3.7, 3.8, and 3.9 with RocksDB version 6.25.3
.. toctree::
:maxdepth: 2
@ -25,9 +25,9 @@ Tested with python2.7 and python3.4 and RocksDB version 5.3.0
Contributing
------------
Source can be found on `github <https://github.com/stephan-hof/pyrocksdb>`_.
Source can be found on `github <https://github.com/lbryio/lbry-rocksdb>`_.
Feel free to fork and send pull-requests or create issues on the
`github issue tracker <https://github.com/stephan-hof/pyrocksdb/issues>`_
`github issue tracker <https://github.com/lbryio/lbry-rocksdb/issues>`_
RoadMap/TODO
------------

70
docs/installation.rst
View file

@ -2,65 +2,21 @@ Installing
==========
.. highlight:: bash
With distro package and pypi
****************************
This requires librocksdb-dev>=5.0
From pypi
*********
.. code-block:: bash
apt-get install python-virtualenv python-dev librocksdb-dev
virtualenv venv
source venv/bin/activate
pip install python-rocksdb
From source
***********
Building rocksdb
----------------
Briefly describes how to build rocksdb under an ordinary debian/ubuntu.
For more details consider https://github.com/facebook/rocksdb/blob/master/INSTALL.md
pip install lbry-rocksdb
From source (ubuntu)
********************
.. code-block:: bash
apt-get install build-essential libsnappy-dev zlib1g-dev libbz2-dev libgflags-dev
git clone https://github.com/facebook/rocksdb.git
cd rocksdb
mkdir build && cd build
cmake ..
make
Systemwide rocksdb
^^^^^^^^^^^^^^^^^^
The following command installs the shared library in ``/usr/lib/`` and the
header files in ``/usr/include/rocksdb/``::
make install-shared INSTALL_PATH=/usr
To uninstall use::
make uninstall INSTALL_PATH=/usr
Local rocksdb
^^^^^^^^^^^^^
If you don't like the system wide installation, or you don't have the
permissions, it is possible to set the following environment variables.
These varialbes are picked up by the compiler, linker and loader
.. code-block:: bash
export CPLUS_INCLUDE_PATH=${CPLUS_INCLUDE_PATH}:`pwd`/../include
export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:`pwd`
export LIBRARY_PATH=${LIBRARY_PATH}:`pwd`
Building python-rocksdb
-----------------------
.. code-block:: bash
apt-get install python-virtualenv python-dev
virtualenv venv
source venv/bin/activate
pip install git+git://github.com/twmht/python-rocksdb.git#egg=python-rocksdb
sudo apt install build-essential binutils
git clone https://github.com/lbryio/lbry-rocksdb.git
cd lbry-rocksdb
git submodule update --init --recursive
git pull --recurse-submodules
make clean && make
pip install -e .
python -m unittest discover . -v

4
tox.ini
View file

@ -1,6 +1,6 @@
[tox]
envlist = py27,py35,py36
minversion = 2.0
envlist = py37,py38,py39
minversion = 3.7
skipsdist = True
[testenv]