Add a search function for the api

Makefile

@@ -5,7 +5,7 @@
 
 ## Global Version of the project, must be updated in each significant change in 
 ## the API & Desktop Gui
-VERSION=0.7.23
+VERSION=0.7.28
 
 ## Next releases:
 RELEASE=$(VERSION)Kahraman

src/alfanous/__init__.py

@@ -15,14 +15,19 @@
 ##     You should have received a copy of the GNU Affero General Public License
 ##     along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-""" hint: use `alfanous.do` method for search, suggestion and get most useful info"""
+""" hint: 
+
+    Use `alfanous.search` for searching in Quran verses and translations.
+    Use `alfanous.get_info` for getting meta info.
+    Use `alfanous.do` method for search, suggestion and get most useful info.
+    """
 
 # import Output object
 from alfanous.Outputs import Raw as _search_engine
 # import default Paths
 from alfanous.Data import Paths as PATHS
 
-DEFAULTS, DOMAINS, HELPMESSAGES, ERRORS = _search_engine.DEFAULTS, _search_engine.DOMAINS, _search_engine.HELPMESSAGES, _search_engine.ERRORS
+DEFAULTS, DOMAINS, HELPMESSAGES = _search_engine.DEFAULTS, _search_engine.DOMAINS, _search_engine.HELPMESSAGES
 FLAGS = DEFAULTS["flags"].keys()
 
 from alfanous.Outputs import Fields as _fields
@@ -36,7 +41,7 @@
 # Pivot function for search, suggestion, show info
 def do(flags):
     """
-    Perform action defined in `flags` and return results as `dict`.
+    Perform the action defined in `flags` and return results as `dict`.
     
     flags is a dict with values for those keys:
     - "action": action to be performed, could be "search" or "suggest" or "show". default is "search"
@@ -54,19 +59,40 @@ def do(flags):
     """
     return _R.do(flags)
 
-# search in aya
-def search_aya(query):
-    "search in verses of Quran"
-    return do({"query":query})
-
-def search_aya_minimal(query):
-    "search in verses of Quran (minimal info)"
-    return do({"query":query, "view":"minimal", "highlight":"none"})
-
-# search in translation
-def search_translation(query):
-    "search in translations of Quran"
-    return do({"query":query,"unit":"translation"})
+def search(query, unit="aya", page = 1, sortedby = "relevance", fuzzy = False, view= "normal", highlight = "bold",  flags={}):
+    """ Search for query in Quran
+    
+    @param query: search query, examples: الحمد, qwl, gid:1.
+    @param unit: search unit, possible values = ['aya', 'word', 'translation']
+    @param page: page to be retrieved, possible values = 1..INF
+    @param sortedby: order of results, possible values = ['relevance', 'mushaf', 'tanzil', 'subject', 'ayalength']
+    @param fuzzy: use fuzzy search, possible values = [True, False]
+    @param view: information to be retrieved, possible values = ['minimal', 'normal', 'full', 'statistic', 'linguistic', 'recitation','costum']
+    @param highlight: type of highlight, possible values = ['css', 'html', 'genshi', 'bold', 'bbcode']
+    @param flags: extra flags as a dict , check alfanous.FLAGS and alfanous.DOMAINS.
+    
+    
+    Example:
+    -------
+        >>> search("qawol",page=2, fuzzy = True)
 
-def show_all_info():
-    return do({"action":"show","query":"all"})
+    """
+    all_flags = flags
+    all_flags.update({"action":"search", 
+                      "unit":unit,
+                      "query":query,
+                      "page": page,
+                      "sortedby":sortedby,
+                      "fuzzy":fuzzy,
+                      "view": view,
+                      "highlight": highlight
+                       })
+    return do(all_flags)
+
+def get_info(query = "all"):
+    """
+    Show useful meta info.
+    
+    @param query: info to be retrieved, possible_values = ['chapters', 'defaults', 'domains', 'errors', 'fields', 'fields_reverse', 'flags', 'help_messages', 'hints', 'information', 'recitations', 'roots', 'surates', 'translations']
+    """
+    return do({"action":"show","query":query})

src/alfanous/resources/information.json

@@ -1,7 +1,8 @@
 {
 "engine": "Alfanous", 
 "wiki": "https://github.com/Alfanous-team/alfanous/blob/master/README.rst", 
-"description": "Alfanous is a Quranic search engine provides simple and advanced search services in the diverse information of the Holy Quran .",
+"description": "Alfanous is a Quranic search engine provides simple and advanced search services in the diverse information of the Holy Quran .", 
+"usage":"\n\n-------\nInstall\n-------\n\n.. code-block:: sh\n\n    $ sudo pip install alfanous\n\n-----\nUsage\n-----\nYou can use it from console:\n\n.. code-block:: sh\n\n    $ alfanous-console -a search -q الله \n\nor from Python:\n\n.. code-block:: python\n\n    >>> import alfanous\n    >>> alfanous.search(u\"الله\")\n    >>> alfanous.search(u\"qwl\")     # Buckwalter transliteration\n\n\nMore about `API <https://github.com/Alfanous-team/alfanous/tree/master/src/alfanous>`_\n",
 "json_output_system_note": "\n    This is the <a href='http://json.org/'>JSON</a> output system 2 of <a href=\"http://www.alfanous.org\">Alfanous</a> project, we call it <b>Alfanous JOS2</b>. This feature is in Alpha test and the Json schema may be it's not stable . We are waiting for real feedback and suggestions to improve its efficacy,quality and stability. To contact the author ,please send a direct email to <b> assem.ch[at]gmail.com</b> or to the mailing list <b>alfanous [at] googlegroups.com</b>\n    <br/><br/> For more details  visit the page of this service <a href=\"https://github.com/Alfanous-team/alfanous/blob/master/src/alfanous-cgi/README.rst\">here</a>\n    ",
 "console_note":"this is console interface of Alfanous, try -h to get help ",
 "author": "Assem chelli",

src/alfanous/setup.py

@@ -25,7 +25,10 @@
 current_version = information["version"] if information.has_key( "version" ) \
 		  else 0.7
 current_description = information["description"] if information.has_key( "description" ) \
-		  else """ Alfanous is a search engine provide the simple and advanced search in the Holy Qur'an and more features.."""
+            else """ Alfanous is a search engine provide the simple and advanced search in the Holy Qur'an and more features.."""
+current_lib_usage = information["lib_usage"] if information.has_key( "lib_usage" ) \
+            else "    $ sudo pip install alfanous"
+
 #TODO may add pre-install code here
 
 setup( 
@@ -48,7 +51,7 @@
 	maintainer_email = "[email protected]",
 
 	package_dir = {'alfanous':'.'},
-	long_description = current_description,
+	long_description = current_description+current_lib_usage,
 	keywords = "quran search indexing engine alfanous",
 	url = "http://www.alfanous.org/",
 	#download_url = "https://sourceforge.net/projects/alfanous/files/",