codernity avatar codernity committed 4ba18f1

Documentation updates.

Comments (0)

Files changed (5)

CodernityDB/database.py

         self.opened = False
 
     def create_new_rev(self, old_rev=None):
+        """
+        Creates new revision number based on previous one.
+        Increments it + random bytes. On overflow starts from 0 again.
+        """
         if old_rev:
             try:
                 rev_num = int(old_rev[:4], 16)
         return name
 
     def edit_index(self, index, reindex=False, ind_kwargs=None):
+        """
+        Allows to edit existing index.
+
+        :param bool redindex: should be the index reindexed after change
+
+        :returns: index name
+        """
         if ind_kwargs is None:
             ind_kwargs = {}
         ind_obj, name = self.__write_index(index, -1, edit=True)
                 self.add_index('path:' + ind, create=False)
 
     def __compat_things(self):
+        """
+        Things for compatibility.
+        """
         # patch for rev size change
         if not self.id_ind:
             return

CodernityDB/tree_index.py

 
 
 class TreeBasedIndex(IU_TreeBasedIndex):
+    pass
 
 
 class MultiTreeBasedIndex(IU_MultiTreeBasedIndex):
 Indexes
 -------
 
+.. note::
+   If you're **not interested in CodernityDB development / extending** you don't need to read this section, 
+   please then refer to :ref:`database_indexes`, **otherwise** please remember that index methods are called from
+   ``Database`` object.
+
+   
+
 General Index
 ^^^^^^^^^^^^^
 

docs/database_indexes.rst

    For api documentation please see :py:class:`.HashIndex`
 
 
+.. seealso::
+
+   :ref:`multiple_keys_index`
+      for Multiindex hash based implementation (more than one key per database data).
+
+
 Below you will find explained in details parameters for that index
 type.
 
     :py:class:`CodernityDB.tree_index.TreeBasedIndex`
         For documentation
 
+   :ref:`multiple_keys_index`
+      for Multiindex tree based implementation (more than one key per database data).
+
 
 duplicate keys
     Duplicate keys are stored inside tree structure. So in worst case
 
 
 
+.. _multiple_keys_index:
+
+Multikeys index
+----------------
+
+Multikeys indexes (aka Multiindex) are indexes where you can have more than one key per database data. They share the same properties as their bases (:ref:`internal_hash_index` and :ref:`internal_tree_index`).
+
+Imagine something like infix search:
+
+.. code-block:: python
+    
+    class TreeMultiTest(MultiTreeBasedIndex):
+
+        custom_header = """from CodernityDB.tree_index import MultiTreeBasedIndex
+    from itertools import izip"""
+
+        def __init__(self, *args, **kwargs):
+            kwargs['key_format'] = '16s'
+            super(TreeMultiTest, self).__init__(*args, **kwargs)
+            self.__l = kwargs.get('w_len', 2)
+
+        def make_key_value(self, data):
+            name = data['w']
+            l = self.__l
+            max_l = len(name)
+            out = set()
+            for x in xrange(l - 1, max_l):
+                m = (name, )
+                for y in xrange(0, x):
+                    m += (name[y + 1:],)
+                out.update(set(''.join(x).rjust(16, '_').lower() for x in izip(*m)))  #ignore import error
+            return out, dict(w=name)
+
+        def make_key(self, key):
+            return key.rjust(16, '_').lower()
+    
+By using that index you will be able to perform infix search over all words in your database. Only one difference from non multi index is that ``make_key_value`` has to return iterable (the best will be set because it has unique values). Then you can easily run something like that:
+    
+.. code-block:: python
+    
+    db = Database('/tmp/multi')
+    db.create()
+    db.add_index(TreeMultiTest(db.path, "words"))
+    
+    db.insert(dict(w='Codernity'))
+    
+    print db.get('words', 'dern')['w']  # "Codernity"
+    print db.get('words', 'cod')['w']  # "Codernity"
+    
+
+As you can see implementing infix/suffix/prefix search mechanism in CodernityDB is very easy.
+    
+.. note::
+    Multiindex requires more time to insert data. Get speed is exactly as fast as in non multiindex (same rules applies to both of them).
+    
+Obviously that's not only one use case for that indexes, it's just probably the most obvious usage example.
+    
+Currently both Hash and Tree indexes have multiindex implementations: ``MultiHashIndex`` and ``MultiTreeBasedIndex`` (yes they are just prefixed by word ``Multi``).
+
+
+
+
 .. _internal_index_functions:
 
 Index functions
         class MyIndex(HashIndex):
             def __init__(self, *args, **kwargs):
                 kwargs['key_format'] = 'I'
-                super(WithXIndex, self).__init__(*args, **kwargs)
+                super(MyIndex, self).__init__(*args, **kwargs)
             def make_key_value(self,data):
                 if data['a'] == a:
                     return data['b'], None
     class MyIndex(HashIndex):
         def __init__(self, *args, **kwargs):
             kwargs['key_format'] = 'I'
-            super(WithXIndex, self).__init__(*args, **kwargs)
+            super(MyIndex, self).__init__(*args, **kwargs)
         def make_key_value(self,data):
             if data['a'] == a:
                 return data['b'], None
 I want to have a bit customized CodernityDB
     No problem, just contact us to get more details about that.
 
+Can I do prefix/infix/suffix search in CodernityDB ?
+    Sure! Please refer to :ref:`multiple_keys_index`. By using such method you will get very fast prefix/infix/suffix search mechanism.
+
 I want to use CodernityDB in commercial project, do I have to pay for it?
     CodernityDB is released on `Apache 2.0 license`_, it allows you to freely use it even for commercial purposes without any need to pay for it. IT'S FREE FOR COMMERCIAL USE. 
 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.