.. _view-ref:

Views classes
-------------

This document describe the detail of **View** API. 

* :ref:`view-results`: A ViewResults instance is constructed 
  by View, SLowView, AllDocumentView and Viewdefinition
  objects. Results are only retrieved when you use one method
  of ViewResults instance.

* :ref:`view`: Object that allow you to retrieve resulys of a view
  in db.

* :ref:`temporary_view`: same as view but for temporary view

* :ref:`allview`: use by Database.documents method

* :ref:`viewdef`: A ViewDefiniton object allow you to easyly create a 
  view and add it to a database. You could sync a database to add allo 
  cached ViewDefintion's object.

Sample usage of a view :

    >>> from simplecouchdb import Server, Database, Views
    >>> server = Server()
    >>> db = Database(name="test", server=server)
    >>> results = db.view.get("test/all")

at this step, ou have only set an instance of ViewResults.

On only retrieved results when you for example iter results :

    >>> list_of_results = list(results)

.. _view-results:

ViewResults class
^^^^^^^^^^^^^^^^^

This class is returned by Views object. ViewResults object can be constructed and passed around without hitting the CouchDB server. No database activity actually occurs until you do something to evaluate the viewresult.

You can evaluate a ViewResult in the following ways:

* **Iteration**: A ViewResult is iterable and it execute the resquest to CouchDB the first time you execute it. 

* **len()**. A ViewResults is evaluated when you call len() on it. This, as you might expect, returns the length of the result list.

* **list()**. Force evaluation by calling list() on it

    .. code-block:: python
        
        list = list(db.view("test/all"))

**Description of the class**

.. autoclass:: simplecouchdb.client.ViewResults
    :members: offset, total_rows

    **Properties**

    .. attribute:: view

        Instance of View used by ViewResults.

    .. attribute:: wrapper
    
        callable to wrap result in an object

    .. attribute:: params

        view parameters

    **Methods**

    .. automethod:: simplecouchdb.client.ViewResults.__len__

    .. automethod:: simplecouchdb.client.ViewResults.__iter__

    .. automethod:: simplecouchdb.client.ViewResults.__nonzero__

    .. automethod:: simplecouchdb.client.ViewResults.fetch

.. _view:

View class
^^^^^^^^^^

**Usage example**:

    >>> db = self.server.create_db('simplecouchdb_test')
    >>> doc1 = { '_id': 'test', 'lastname': 'doo', 'firtsname': "john", 'docType': 'identity' }
    >>> db.save(doc1)
    >>> doc2 = { '_id': 'test2', 'lastname': 'dupont', 'firstname': "jean", 'docType': 'identity'}
    >>> db.save(doc2)
    >>> design_doc = { '_id': '_design/test', 'language': 'javascript', 
        'views': {  'all': { "map": """function(doc) {
        if (doc.docType == "identity") { emit(doc._id, doc); }}""" } }}
    >>> db.save(design_doc)
    >>> results = db.view.get('test/all')
    >>> len(results)
    2
    >>> self.server.delete_db('simplecouchdb_test')


.. autoclass:: simplecouchdb.client.View

    **Properties**

    .. attribute:: database

        Database instance on which is the view is executed

    **Methods**

    .. automethod:: simplecouchdb.client.View.__call__

    .. automethod:: simplecouchdb.client.View.get

    .. automethod:: simplecouchdb.client.View.count


.. _temporary_view:

TempView class
^^^^^^^^^^^^^^^^^^^

This object is used to retrieve result from a couchdb temp view.
It is inherited from :class:`simplecouchdb.client.View` object.

**Usage example**:

    >>> db = self.server.create_db('simplecouchdb_test')
    >>> db = self.server.create_db('simplecouchdb_test')
    >>> doc1 = { '_id': 'test', 'lastname': 'doo', 'firtsname': "john", 'docType': 'identity' }
    >>> db.save(doc1)
    >>> doc2 = { '_id': 'test2', 'lastname': 'dupont', 'firstname': "jean", 'docType': 'identity'}
    >>> db.save(doc2)
    >>> design_doc = { "map": """function(doc) { if (doc.docType == "identity") { emit(doc._id, doc); }}""" } 
    >>> results = db.slow_view.get(design_doc)
    >>> len(results)
    2
    >>> self.server.delete_db('simplecouchdb_test')


.. autoclass:: simplecouchdb.client.TempView

    ..automethod:: simplecouchdb.client.TempView.get


.. _allview:

AllDocumentsView class
^^^^^^^^^^^^^^^^^^^^^^

This view object nherited from :class:`simplecouchdb.client.View`, is only used by :meth:`simplecouchdb.client.Database.documents`

.. autoclass:: simplecouchdb.client.AllDocumentsView


.. _viewdef:

ViewDefinition class
^^^^^^^^^^^^^^^^^^^^

This object is used o create and register views for a database.

**Example usage**:

    >>> view = ViewDefinition('test', 'all', map_fun= """function(doc) 
        { if (doc.docType == "identity") { emit(doc._id, doc);}}""")
    >>> db = self.server.create_db('simplecouchdb_test')
        >>> doc1 = { '_id': 'test', 'string': 'test', 'number': 4, 'docType': 'test' }
    >>> db.save(doc1)
    >>> doc2 = { '_id': 'test2', 'string': 'test', 'number': 2, 'docType': 'test'}
    >>> db.save(doc2)
    >>> view.sync(db)
    >>> results = db.view.get('test/all')
    >>> len(results)
    2
    >>> self.server.delete_db('simplecouchdb_test')


.. autoclass:: simplecouchdb.client.ViewDefinition
    
    **Properties**

    .. attribute:: design_name

        name of design document

    .. attribute:: view_nane 

        name of view
    
    .. attribute:: map_fun

        str of file object, string for map function
    
    .. attribute:: reduce_fun

        str of file object, string for reduce function
    .. attribute:: language

        language of view, default is javascript
    
    .. attribute:: wrapper

        default wrapper of view
    
    .. attribute:: params
        
        default parameters of view

    **Methods**

    .. automethod:: simplecouchdb.client.ViewDefinition.register

    .. automethod:: simplecouchdb.client.ViewDefinition.sync

    .. automethod:: simplecouchdb.client.ViewDefinition.get


ViewCache class
^^^^^^^^^^^^^^^^^^^

.. autoclass:: simplecouchdb.client.ViewCache

    **Methods**
 
    .. automethod:: simplecouchdb.client.ViewCache.add_view

    .. automethod:: simplecouchdb.client.ViewCache.get_views

    .. automethod:: simplecouchdb.client.ViewCache.get_view


Other
^^^^^

.. autofunction:: simplecouchdb.client.register_view


.. seealso:: Reference :ref:`database`

