Metadata-Version: 2.1
Name: CouchDB2
Version: 1.11.0
Summary: C
Home-page: https://github.com/pekrau/CouchDB2
Author: Per Kraulis
Author-email: per.kraulis@gmail.com
License: MIT
Description: # CouchDB2
        
        CouchDB v2.x Python 3 interface in a single module.
        Also a command line tool; [see below](#command-line-tool).
        
        Most, but not all, features of this module work with CouchDB version < 2.0.
        
        ## Installation
        
        The CouchDB2 module is available at [PyPi](https://pypi.org/project/CouchDB2/).
        It can be installed using [pip](https://pip.pypa.io/en/stable/):
        
        ```
        $ pip install couchdb2
        ```
        
        The module relies on `requests`: http://docs.python-requests.org/en/master/
        
        ## Example code
        
        ```python
        import couchdb2
        
        server = couchdb2.Server()   # Arguments required according to local setup
        db = server.create("test")
        
        doc1 = {"_id": "myid", "name": "mydoc", "level": 4}
        db.put(doc1)
        doc = db["myid"]
        assert doc == doc1
        
        doc2 = {"name": "another", "level": 0}
        db.put(doc2)
        print(doc2)
        # {"_id": "66b5...", "_rev": "1-f3ac...", "name": "another", "level": 0}
        
        db.put_design("mydesign", 
                      {"views":
                       {"name": {"map": "function (doc) {emit(doc.name, null);}"}
                       }
                      })
        result = db.view("mydesign", "name", key="another", include_docs=True)
        assert len(result) == 1
        print(result[0].doc)         # Same printout as above, using OrderedDict
        
        db.destroy()
        ```
        
        ## News
        
        - 1.11.0
          - Added `db.changes()`. **But not adequately tested!**
          - Corrected returned value from `set_replicate`: JSON data rather than
            response from `requests`.
          - Refactored code: Got rid of `object_pairs_hook=dict` in `json()`.
            `response.json()` on a separate line everywhere.
        - 1.10.0
          - Changed to unittest for the test script. Got rid of package `pytest`.
            Added some tests.
          - Improved the documentation in source and README.
          - Fixed setup.py.
          - Added `__del__` to Server class.
          - Simplified `get_scheduler_docs`.
          - Hid module-level functions which are just help functions for the
            command-line tool.
          - Removed `CouchDB version >= 2.0` from some methods incorrectly
            marked as such.
          - Changed signatures of class Database methods `__init__`, `create`,
            `find` and `explain`.
        - 1.9.5
          - Added `__str__` to Server class.
        - 1.9.4
          - Added `update` parameter on views; thanks to https://github.com/rbarreiro
          - Added `n` and `q` parameters when creating a database; thanks to
            https://github.com/elChapoSing
        - 1.9.3
          - Handle `get_attachment` rev/If-Match issue; thanks to https://github.com/seb4itik
        - 1.9.2
          - Added retrieve of conflicts; thanks to https://github.com/seb4itik
        - 1.9.1
          - Added `ca_file` parameter for HTTPS; thanks to https://github.com/seb4itik
        - 1.9.0
          - Changed `put_attachment` and `delete_attachment` to update the input
            `doc` by the new `_rev` value.
        - 1.8.5
          - Added `ids()`: Return an iterator over all document identifiers.
        - 1.8.4
          - Added `get_bulk(ids)`: Get several documents in one operation.
        
        ## `class Server`
        ```python
        server = Server(href="http://localhost:5984/",
                        username=None, password=None,
                        use_session=True, ca_file=None)
        ```
        An instance of the class is a connection to the CouchDB server.
        
        - `href` is the URL to the CouchDB server itself.
        - `username` and `password` specify the CouchDB user account to use.
        - If `use_session` is `True`, then an authenticated session is used
          transparently. Otherwise, the values of `username` and `password` are
          sent with each request.
        - `ca_file` is a path to a file or a directory containing CAs if
          you need to access databases in HTTPS.
        
        ### `server.version`
        
        Property attribute providing the version of the CouchDB server software.
        
        ### `server.user_context`
        
        Property attribute providing the user context of the connection.
        
        ### `__str__`
        ```python
        str(server)
        ```
        Returns a simple string representation of the server interface.
        
        ### `__len__`
        ```python
        len(server)
        ```
        Returns the number of user-defined databases.
        
        ### `__iter__`
        ```python
        for db in server: ...
        ```
        Returns an iterator over all user-defined databases on the server.
        
        ### `__getitem__`
        ```python
        db = server[name]
        ```
        Gets the named database.
        
        ### `__contains__`
        ```python
        if name in server: ...
        ```
        Does the named database exist?
        
        ### `__call__`
        ```python
        data = server()
        ```
        Returns meta information about the server.
        
        ### `__del__`
        
        Clean-up: Closes the `requests` session.
        
        Not for explicit use; it is automatically called when the Python
        garbage collection mechanism deletes the instance.
        
        ### `server.up()`
        
        Is the server up and running, ready to respond to requests?
        Returns a boolean.
        
        *CouchDB version >= 2.0*
        
        ### `server.get(name, check=True)`
        
        Gets the named database. Returns an instance of class `Database`.
        
        Raises `NotFoundError` if `check` is `True` and the database does not exist.
        
        ### `server.create(name, n=3, q=8, partitioned=False)`
        
        Creates the named database. Raises `CreationError` if it already exists.
        
        - `name`: The name of the database.
        - `n`: The number of replicas.
        - `q`: The number of shards.
        - `partitioned`: Whether to create a partitioned database.
        
        ### `server.get_config(nodename="_local")`
        
        Gets the named node's configuration.
        
        ### `server.get_active_tasks()`
        
        Returns a list of running tasks.
        
        ### `server.get_cluster_setup(ensure_dbs_exists=None)`
        
        Returns the status of the node or cluster.
        
        `ensure_dbs_exists` is a list system databases to ensure exist on the
        node/cluster. Defaults to `["_users","_replicator"]`.
        
        *CouchDB version >= 2.0*
        
        ### `server.set_cluster_setup(doc)`
        
        Configures a node as a single node, as part of a cluster, or finalise a
        cluster.
        
        See the CouchDB documentation for the contents of `doc`.
        
        *CouchDB version >= 2.0*
        
        ### `server.get_membership()`
        
        Returns data about the nodes that are part of the cluster.
        
        *CouchDB version >= 2.0*
        
        ### `server.set_replicate(doc)`
        
        Request, configure, or stop, a replication operation.
        
        See the CouchDB documentation for the contents of `doc`.
        
        ### `server.get_scheduler_jobs(limit=None, skip=None)`
        
        Gets a list of replication jobs.
        
        - `limit`: How many results to return.
        - `skip`: How many result to skip starting at the beginning,
          ordered by replication ID.
        
        ### `server.get_scheduler_docs(limit=None, skip=None)`
        
        Gets information about replication document states.
        
        - `limit`: How many results to return.
        - `skip`: How many result to skip starting at the beginning,
          ordered by document ID.
        
        ### `server.get_node_stats(nodename="_local")`
        
        Returns statistics for the running server.
        
        ### `server.get_node_system(nodename="_local")`
        
        Returns various system-level statistics for the running server.
        
        ## `class Database`
        ```python
        db = Database(server, name, check=True)
        ```
        
        An instance of the class is an interface to a CouchDB database.
        
        - `server`: An instance of Server.
        - `name`: The name of the database.
        - If `check` is `True`, then raise `NotFoundError` if the the database
          does not exist.
        
        ### `__str__`
        ```python
        str(db)
        ```
        Returns the name of the CouchDB database.
        
        ### `__len__`
        ```python
        len(db)
        ```
        Returns the number of documents in the database.
        
        ### `__contains__`
        ```python
        if identifier in db: ...
        ```
        Does a document with the given identifier exist in the database?
        
        ### `__iter__`
        ```python
        for doc in db: ...
        ```
        Returns an iterator over all documents in the database.
        
        ### `__getitem__`
        ```python
        doc = db[id]
        ```
        Returns the document with the given id.
        
        ### `db.exists()`
        
        Does the database exist? Returns a boolean.
        
        ### `db.check()`
        
        Raises `NotFoundError` if the database does not exist.
        
        ### `db.create(n=3, q=8, partitioned=False)`
        
        Creates the database. Raises `CreationError` if it already exists.
        
        - `n`: The number of replicas.
        - `q`: The number of shards.
        - `partitioned`: Whether to create a partitioned database.
        
        ### `db.destroy()`
        
        Deletes the database and all its contents.
        
        ### `db.get_info()`
        
        Returns a dictionary with information about the database.
        
        ### `db.get_security()`
        
        Returns a dictionary with security information for the database.
        
        ### `db.set_security(doc)`
        
        Sets the security information for the database.
        
        See the CouchDB documentation for the contents of `doc`.
        
        ### `db.compact(finish=False, callback=None)`
        
        Compacts the CouchDB database by rewriting the disk database file
        and removing old revisions of documents.
        
        - If `finish` is `True`, then return only when compaction is done.
        - In addition, if defined, the function `callback(seconds)` is called
          every second until compaction is done.
        
        ### `db.compact_design(designname)`
        
        Compacts the view indexes associated with the named design document.
        
        ### `db.view_cleanup()`
        
        Removes unnecessary view index files due to changed views in
        design documents of the database.
        
        ### `db.get(id, default=None, rev=None, revs_info=False, conflicts=False)`
        
        Returns the document with the given identifier, or the `default` value
        if not found.
        
        - `rev`: Retrieves document of specified revision, if specified.
        - `revs_info`: Whether to include detailed information for all known
          document revisions.
        - `conflicts`: Whether to include information about conflicts in
          the document in the `_conflicts` attribute.
        
        ### `db.get_bulk(ids)`
        
        Gets several documents in one operation, given a list of document identifiers,
        each of which is a string (the document `_id`), or a tuple of the
        document `(_id, _rev)`.
        
        Returns a list of documents. If no document is found for a specified
        `_id` or `(_id, _rev`), `None` is returned in that slot of the list.
        
        ### `db.ids()`
        ```python
        for identifier in db.ids(): ...
        ```
        
        Returns an iterator over all document identifiers.
        
        ### `db.put(doc)`
        
        Inserts or updates the document.
        
        If the document is already in the database, the `_rev` item must
        be present in the document; its value will be updated.
        
        If the document does not contain an item `_id`, it is added
        having a UUID4 hex value. The `_rev` item will also be added.
        
        ### `db.update(docs)`
        
        Performs a bulk update or insertion of the given documents using a
        single HTTP request.
        
        Returns an iterable (list) over the resulting documents.
        
        `docs` is a sequence of dictionaries or `Document` objects, or
        objects providing an `items()` method that can be used to convert
        them to a dictionary.
        
        The return value of this method is a list containing a tuple for every
        element in the `docs` sequence. Each tuple is of the form
        `(success, docid, rev_or_exc)`, where `success` is a boolean
        indicating whether the update succeeded, `docid` is the ID of the
        document, and `rev_or_exc` is either the new document revision, or
        an exception instance (e.g. `ResourceConflict`) if the update failed.
        
        If an object in the documents list is not a dictionary, this method
        looks for an `items()` method that can be used to convert the object
        to a dictionary.
                          
        ### `db.delete(doc)`
        
        Deletes the document, which must contain the `_id` and `_rev` items.
        
        ### `db.purge(docs)`
        
        Performs purging (complete removal) of the given list of documents.
        
        Uses a single HTTP request to purge all given documents. Purged
        documents do not leave any meta-data in the storage and are not
        replicated.
        
        ### `db.get_designs()`
        
        Returns the design documents for the database.
        
        **NOTE:** *CouchDB version >= 2.2*
        
        ### `db.get_design(designname)`
        
        Gets the named design document.
        
        ### `db.put_design(designname, doc, rebuild=True)`
        
        Inserts or updates the design document under the given name.
        
        If the existing design document is identical, no action is taken and
        `False` is returned, else the document is updated and `True` is returned.
        
        If `rebuild` is `True`, force view indexes to be rebuilt after update
        by accessing the view. This may take some time.
        
        Example of doc:
        ```
          {"views":
            {"name":
              {"map": "function (doc) {emit(doc.name, null);}"},
             "name_sum":
              {"map": "function (doc) {emit(doc.name, 1);}",
               "reduce": "_sum"},
             "name_count":
              {"map": "function (doc) {emit(doc.name, null);}",
               "reduce": "_count"}
          }}
        ```
        
        More info: http://docs.couchdb.org/en/latest/api/ddoc/common.html
        
        ### `db.view(designname, viewname, **kwargs)`
        
        Query a view index to obtain data and/or documents.
        
        Keyword arguments (default value is `None` unless specified):
        
        - `key`: Return only rows that match the specified key.
        - `keys`: Return only rows where they key matches one of those specified as a list.
        - `startkey`: Return rows starting with the specified key.
        - `endkey`: Stop returning rows when the specified key is reached.
        - `skip`: Skip the number of rows before starting to return rows.
        - `limit`: Limit the number of rows returned.
        - `sorted=True`: Sort the rows by the key of each returned row. The items
          `total_rows` and `offset` are not available if set to `False`.
        - `descending=False`: Return the rows in descending order.
        - `group=False`: Group the results using the reduce function of the design
          document to a group or a single row. If set to `True` implies `reduce`
          to `True` and defaults the `group_level` to the maximum.
        - `group_level`: Specify the group level to use. Implies `group` is `True`.
        - `reduce`: If set to `False` then do not use the reduce function if there is
          one defined in the design document. Default is to use the reduce function
          if defined.
        - `include_docs=False`: If `True`, include the document for each row. This
          will force `reduce` to `False`.
        - `update="true"`: Whether ir not the view should be updated prior to
          returning the result. Supported value are `"true"`, `"false"` and `"lazy"`.
        
        Returns an instance of [class ViewResult](#class-viewresultrows-offset-total_rows),
        containing the following attributes:
        
        - `rows`: The list of `Row` objects.
        - `offset`: The offset used for the set of rows.
        - `total_rows`: The total number of rows selected.
        
        A Row object contains the following attributes:
        
        - `id`: The identifier of the document, if any.
        - `key`: The key for the index row.
        - `value`: The value for the index row.
        - `doc`: The document, if any.
        
        ### `db.get_indexes()`
        
        Returns a list of all Mango indexes in the database.
        
        *CouchDB version >= 2.0*
        
        ### `db.put_index(fields, ddoc=None, name=None, selector=None)`
        
        Stores a Mango index specification.
        
        - `fields`: A list of fields to index.
        - `ddoc`: The design document name. Generated if none given.
        - `name`: The name of the index. Generated if none given.
        - `selector`: A partial filter selector, which may be omitted.
        
        Returns a dictionary with items `id` (design document name; sic!),
        `name` (index name) and `result` (`created` or `exists`).
        
        *CouchDB version >= 2.0*
        
        ### `db.delete_index(designname, name)`
        
        Deletes the named index in the design document of the given name.
        
        *CouchDB version >= 2.0*
        
        ### `db.find(selector, **kwargs)`
        ```python
        data = db.find(selector, limit=25, skip=None, sort=None, fields=None,
                       use_index=None, bookmark=None, update=True, conflicts=False)
        ```
        Selects documents according to the Mango index `selector`.
        
        - `selector`: The Mango index. For more information on selector syntax,
           see https://docs.couchdb.org/en/latest/api/database/find.html#find-selectors
        - `limit`: Maximum number of results returned.
        - `skip`: Skip the given number of results.
        - `sort`: A list of dictionaries specifying the order of the results,
          where the field name is the key and the direction is the value;
          either `"asc"` or `"desc"`.
        - `fields`: List specifying which fields of each result document should
          be returned. If omitted, return the entire document.
        - `use_index`: String or list of strings specifying the index(es) to use.
        - `bookmark`: A string that marks the end the previous set of results.
          If given, the next set of results will be returned.
        - `update`: Whether to update the index prior to returning the result.
        - `conflicts`: Whether to include conflicted documents.
        
        Returns a dictionary with items `docs`, `warning`, `execution_stats`
        and `bookmark`.
        
        *CouchDB version >= 2.0*
        
        ### `db.explain(selector, **kwargs)`
        ```python
        data = db.explain(selector, use_index=None, limit=None, skip=None,
                          sort=None, fields=None, bookmark=None)
        ```
        Returns info on which index is being used by the query.
        
        - `selector`: The Mango index. For more information on selector syntax,
           see https://docs.couchdb.org/en/latest/api/database/find.html#find-selectors
        - `limit`: Maximum number of results returned.
        - `skip`: Skip the given number of results.
        - `sort`: A list of dictionaries specifying the order of the results,
          where the field name is the key and the direction is the value;
          either `"asc"` or `"desc"`.
        - `fields`: List specifying which fields of each result document should
          be returned. If omitted, return the entire document.
        - `bookmark`: A string that marks the end the previous set of results.
           If given, the next set of results will be returned.
        
        *CouchDB version >= 2.0*
        
        ### `db.get_attachment(doc, filename)`
        
        Returns a file-like object containing the content of the specified attachment.
        
        ### `db.put_attachment(doc, content, filename=None, content_type=None)`
        
        Adds or updates the given file as an attachment to the given document
        in the database.
        
        - `content` is a string or a file-like object.
        - If `filename` is not provided, then an attempt is made to get it from
          the `content` object. If this fails, `ValueError` is raised.
        - If `content_type` is not provided, then an attempt to guess it from
          the filename extension is made. If that does not work, it is
          set to `"application/octet-stream"`
        
        Returns the new revision of the document, in addition to updating
        the `_rev` field in the document.
        
        ### `db.delete_attachment(doc, filename)`
        
        Deletes the attachment.
        
        Returns the new revision of the document, in addition to updating
        the `_rev` field in the document.
        
        ### `db.dump(filepath, callback=None)`
        
        Dumps the entire database to a `tar` file.
        
        Return a tuple `(ndocs, nfiles)` giving the number of documents
        and attached files written out.
        
        If defined, the function `callback(ndocs, nfiles)` is called 
        every 100 documents.
        
        If the filepath ends with `.gz`, then the tar file is gzip compressed.
        The `_rev` item of each document is written out.
        
        ### `db.undump(filepath, callback=None)`
        
        Loads the `tar` file given by the path. It must have been produced by `db.dump`.
        
        Returns a tuple `(ndocs, nfiles)` giving the number of documents
        and attached files read from the file.
        
        If defined, the function `callback(ndocs, nfiles)` is called 
        every 100 documents.
        
        **NOTE**: The documents are just added to the database, ignoring any
        `_rev` items. This means that no document with the same identifier
        may exist in the database.
        
        ## `CouchDB2Exception`
        
        The Base CouchDB2 exception, from which all others derive.
        
        ## `NotFoundError`
        
        No such entity (e.g. database or document) exists.
        
        ## `BadRequestError`
        
        Invalid request; bad name, body or headers.
        
        ## `CreationError`
        
        Could not create the entity; it exists already.
        
        ## `RevisionError`
        
        Wrong or missing `_rev` item in the document to save.
        
        ## `AuthorizationError`
        
        Current user not authorized to perform the operation.
        
        ## `ContentTypeError`
        
        Bad `Content-Type` value in the request.
        
        ## `ServerError`
        
        Internal CouchDB server error.
        
        ## `class ViewResult(rows, offset, total_rows)`
        
        An instance of this class is returned as result from `db.view()`.
        Instances of this class are not supposed to be created by client software.
        
        Attributes:
        
        - `rows`: the list of `Row` objects.
        - `offset`: the offset used for the set of rows.
        - `total_rows`: the total number of rows selected.
        
        ### `__len__`
        ```python
        len(viewresult)
        ```
        Return the number of rows in the view result.
        
        ### `__iter__`
        ```python
        for row in viewresult: ...
        ```
        Return an iterator over all rows in the view result.
        
        ### `__getitem__`
        ```python
        row = viewresult[i]
        ```
        Return the indexed view result row.
        
        ### `vr.json()`
        
        Return the view result data in a JSON-like representation.
        
        ## `class Row(id, key, value, doc)`
        
        Named-tuple object returned in ViewResult list attribute `rows`.
        
        Attributes:
        
        - `id`: the identifier of the document, if any. Alias for `row[0]`.
        - `key`: the key for the index row. Alias for `row[1]`.
        - `value`: the value for the index row. Alias for `row[2]`.
        - `doc`: the document, if any. Alias for `row[3]`.
        
        ## Utility functions at the module level
        
        ### `read_settings(filepath, settings=None)`
        
        Read the settings lookup from a JSON format file.
        
        If `settings` is given, then return an updated copy of it,
        else copy the default settings, update, and return it.
        
        ## Command line tool
        
        The module is also a command line tool for interacting with the CouchDB server.
        It is installed if `pip` is used to install this module.
        
        Settings for the command line tool are updated from the following sources,
        each in the order given and if it exists:
        
        1) Default values are
           ```
           {
             "SERVER": "http://localhost:5984",
             "DATABASE": null,
             "USERNAME": null,
             "PASSWORD": null
           }
           ```
        2) Read from the JSON file `~/.couchdb2` (in your home directory).
        3) Read from the JSON file `settings.json` (in the current working directory).
        4) Read from the JSON file given by command line option `--settings FILEPATH`.
        5) From environment variables.
        6) From command line arguments.
        
        ### Options
        
        To show available command options:
        
        ```
        $ couchdb2 -h
        usage: couchdb2 [options]
        
        CouchDB v2.x command line tool, leveraging Python module CouchDB2.
        
        optional arguments:
          -h, --help            show this help message and exit
          --settings FILEPATH   settings file in JSON format
          -S SERVER, --server SERVER
                                CouchDB server URL, including port number
          -d DATABASE, --database DATABASE
                                database to operate on
          -u USERNAME, --username USERNAME
                                CouchDB user account name
          -p PASSWORD, --password PASSWORD
                                CouchDB user account password
          -q, --password_question
                                ask for the password by interactive input
          --ca_file FILEORDIRPATH
                                file or directory containing CAs
          -o FILEPATH, --output FILEPATH
                                write output to the given file (JSON format)
          --indent INT          indentation level for JSON format output file
          -y, --yes             do not ask for confirmation (delete, destroy)
          -v, --verbose         print more information
          -s, --silent          print no information
        
        server operations:
          -V, --version         output CouchDB server version
          --list                output a list of the databases on the server
        
        database operations:
          --create              create the database
          --destroy             delete the database and all its contents
          --compact             compact the database; may take some time
          --compact_design DDOC
                                compact the view indexes for the named design doc
          --view_cleanup        remove view index files no longer required
          --info                output information about the database
          --security            output security information for the database
          --set_security FILEPATH
                                set security information for the database from the
                                JSON file
          --list_designs        list design documents for the database
          --design DDOC         output the named design document
          --put_design DDOC FILEPATH
                                store the named design document from the file
          --delete_design DDOC  delete the named design document
          --dump FILEPATH       create a dump file of the database
          --undump FILEPATH     load a dump file into the database
        
        document operations:
          -G DOCID, --get DOCID
                                output the document with the given identifier
          -P FILEPATH, --put FILEPATH
                                store the document; arg is literal doc or filepath
          --delete DOCID        delete the document with the given identifier
        
        attachments to document:
          --attach DOCID FILEPATH
                                attach the specified file to the given document
          --detach DOCID FILENAME
                                remove the attached file from the given document
          --get_attach DOCID FILENAME
                                get the attached file from the given document; write
                                to same filepath or that given by '-o'
        
        query a design view, returning rows:
          --view SPEC           design view '{design}/{view}' to query
          --key KEY             key value selecting view rows
          --startkey KEY        start key value selecting range of view rows
          --endkey KEY          end key value selecting range of view rows
          --startkey_docid DOCID
                                return rows starting with the specified document
          --endkey_docid DOCID  stop returning rows when specified document reached
          --group               group the results using the 'reduce' function
          --group_level INT     specify the group level to use
          --noreduce            do not use the 'reduce' function of the view
          --limit INT           limit the number of returned rows
          --skip INT            skip this number of rows before returning result
          --descending          sort rows in descending order (swap start/end keys!)
          --include_docs        include documents in result
        ```
        
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Database :: Front-Ends
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >= 3.6
Description-Content-Type: text/markdown
