From cd327c06d95f4321af375105b8afd5b13c80c05c Mon Sep 17 00:00:00 2001 From: Jack Robison Date: Mon, 17 Jan 2022 18:37:23 -0500 Subject: [PATCH] docs --- docs/api/database.rst | 53 ++++++++++++++++++++++++++++++++ docs/conf.py | 17 +++++------ docs/index.rst | 8 ++--- docs/installation.rst | 70 ++++++++----------------------------------- tox.ini | 4 +-- 5 files changed, 80 insertions(+), 72 deletions(-) diff --git a/docs/api/database.rst b/docs/api/database.rst index 93e5741..0196470 100644 --- a/docs/api/database.rst +++ b/docs/api/database.rst @@ -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. diff --git a/docs/conf.py b/docs/conf.py index 07cb87b..fcbc3f3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -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'), ] diff --git a/docs/index.rst b/docs/index.rst index 0692259..1be7e35 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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 `_. +Source can be found on `github `_. Feel free to fork and send pull-requests or create issues on the -`github issue tracker `_ +`github issue tracker `_ RoadMap/TODO ------------ diff --git a/docs/installation.rst b/docs/installation.rst index e982a23..a8d32b4 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -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 diff --git a/tox.ini b/tox.ini index 7202f07..c0dfabe 100644 --- a/tox.ini +++ b/tox.ini @@ -1,6 +1,6 @@ [tox] -envlist = py27,py35,py36 -minversion = 2.0 +envlist = py37,py38,py39 +minversion = 3.7 skipsdist = True [testenv]