Couchbase Python Client

Python client for Couchbase

NOTE: This is the documentation for the 4.x version of the client. This is mostly compatible with the older 3.x version. Please refer to the release32 branch for the older 3.x version.

Contents

• Prerequisites
• Installing
• Building
• Using the SDK
• Logging
• Building Documentation
• Testing
• Contributing
• Support & Additional Resources
• License
• Appendix

Prerequisites

• Couchbase Server
• You may need a C++ compiler supporting C++ 17 and Python development files, unless a binary wheel is available for your platform. With the 4.0.2 release, wheels are available on Windows, MacOS and Linux (via manylinux) for Python 3.7 - 3.10.
• CMake (version >= 3.18), unless a binary wheel is available for your platform.
• Git, unless a binary wheel is available for your platform.
• OpenSSL is now required for the 4.x Python SDK.
• If using the Twisted Framework and the txcouchbase API, Twisted >= 21.7.0 is required.

Debian and Ubuntu

First-time setup:

$ sudo apt install git-all python3-dev python3-pip python3-setuptools cmake build-essential libssl-dev

NOTE: We have provided Dockerfiles to demonstrate steps to achieve a working setup for various linux platforms. See the dockerfiles folder in the Python SDK examples folder for details.

See Debian and Ubuntu install section to install SDK.

RHEL and CentOS

First-time setup:

$ sudo yum install git-all gcc gcc-c++ python3-devel python3-pip python3-setuptools cmake openssl-devel

:exclamation:IMPORTANT:exclamation:

Some of the defaults for older operating systems like Centos/RHEL 7 and 8 have defaults to do not meet the 4.x Python SDK minimum requirements. Be sure to update to the minimum requirements prior to installing the SDK. Most notably be sure to check the following:

• The default Python version might be less than 3.7. If so, the Python version will need to be udpated.
• The default OpenSSL version might be less than 1.1.1. If so, the OpenSSL version will need to be updated.
• The gcc version must provide C++17 support. If the installed gcc version does not support C++17, gcc will need to be updated.
• The installed CMake version might be less than 3.17. If so, the CMake version will need to be updated. Check out the steps here to update CMake.

NOTE: We have provided Dockerfiles to demonstrate steps to achieve a working setup for various linux platforms. See the dockerfiles folder in the Python SDK examples folder for details.

See RHEL and Centos install section to install SDK.

Mac OS

It is not recommended to use the vendor-supplied Python that ships with OS X. Best practice is to use a Python virtual environment such as pyenv or venv (after another version of Python that is not vendor-supplied has been installed) to manage multiple versions of Python.

:exclamation:IMPORTANT:exclamation:

There can be a problem when using the Python (3.8.2) that ships with Xcode on Catalina. It is advised to install Python with one of the following:

• pyenv
• Homebrew
• Install Python via python.org

pyenv

See detailed walk through in Appendix. Also, see pyenv install docs for further details.

NOTE: If using pyenv, make sure the python interpreter is the pyenv default, or a virtual environment has been activiated. Otherwise cmake might not be able to find the correct version of Python3 to use when building.

Homebrew

See Homebrew install docs for further details.

Get the latest packages:

$ brew update

Install Python:

$ brew install python

Update path:

• zsh: console $ echo 'export PATH="/usr/local/bin:"$PATH' >> ~/.zshrc
• bash: console $ echo 'export PATH="/usr/local/bin:"$PATH' >> ~/.bash_profile

Install OpenSSL:

$ brew install openssl@1.1

To get OpenSSL to be found by cmake on macos, find where openssl was installed via homebrew:

brew info openssl@1.1

This will show you how to get it seen by pkg-config. To check that it worked, do this:

pkg-config --modversion openssl

See Mac OS install section to install SDK.

Windows

Wheels are available on Windows for Python 3.7, 3.8, 3.9 and 3.10.

Best practice is to use a Python virtual environment such as venv or pyenv (checkout the pyenv-win project) to manage multiple versions of Python.

If wanting to install from source, see the Windows building section for details.

See Windows install section to install SDK.

Installing

Back to Contents

You can always get the latest supported release version from pypi.

NOTE: If you have a recent version of pip, you may use the latest development version by issuing the following incantation: console pip install git+https://github.com/couchbase/couchbase-python-client.git

NOTE: The Python Client installer relies on PEP517 which older versions of PIP do not support. If you experience issues installing it is advised to upgrade your PIP/setuptools installation as follows:

console python3 -m pip install --upgrade pip setuptools wheel

Debian and Ubuntu

First, make sure the prerequisites have been installed.

Install the SDK:

$ python3 -m pip install couchbase

RHEL and CentOS

First, make sure the prerequisites have been installed.

Install the SDK:

$ python3 -m pip install couchbase

Mac OS

First, make sure the prerequisites have been installed.

Install the SDK:

$ python -m pip install couchbase

Windows

First, make sure the prerequisites have been installed.

NOTE: Commands assume user is working within a virtual environment. For example, the following commands have been executed after downloading and installing Python from python.org:

-C:\Users\Administrator\AppData\Local\Programs\Python\Python39\python -m venv C:\python\python39

-C:\python\python39\Scripts\activate

Install the SDK (if using Python 3.7, 3.8, 3.9 or 3.10):

python -m pip install couchbase

Alternative Installation Methods

In order to successfully install with the following methods, ensure a proper build system is in place (see the Windows building section for details).

Source Install (i.e. no wheel)

First, ensure all the requirements for a build system are met.

Install the SDK:

python -m pip install couchbase --no-binary couchbase

Local Install

First, ensure all the requirements for a build system are met.

Clone this Python SDK repository:

git clone --depth 1 --branch <tag_name> --recurse-submodules https://github.com/couchbase/couchbase-python-client.git

Where tag_name is equal to the latest release.

Example: git clone --depth 1 --branch 4.0.0 --recurse-submodules https://github.com/couchbase/couchbase-python-client.git

Move into the directory created after cloning the Python SDK repository:

cd couchbase-python-client

NOTE: If the --recurse-submodules option was not used when cloning the Python SDK repository, run (after moving into the cloned repository directory) git submodule update --init --recursive to recursively update and initialize the submodules.

Install the SDK from source:

python -m pip install .

Anaconda/Miniconda

To use the SDK within the Anaconda/Miniconda platform, make sure the prerequisites for the desired Operating System are met: - Debian and Ubuntu - RHEL and Centos - Mac OS - Windows

In the Anaconda Prompt, create a new environment:

(base) C:\Users\user1>conda create -n test_env python=3.9

Activate the environment

(base) C:\Users\user1>conda activate test_env

Install the SDK:

(test_env) C:\Users\user1>python -m pip install couchbase

NOTE: If using Windows, and no wheel is available, see the Alternative Install Methods Windows section. The same process should work within the Anaconda/Miniconda platform.

Building

Back to Contents

NOTE: This section only applies to building from source.

Build System Setup

Linux

Make sure the prerequisites have been installed: - Debian and Ubuntu - RHEL and Centos

Mac OS

First, make sure the prerequisites have been installed.

Install cmake:

$ brew install cmake

Install command line developer tools:

$ xcode-select --install

NOTE: It is possible that installing or updating to the the latest version of Xcode is needed.

If setuptools is not installed:

$ python -m pip install setuptools

Windows

Requirements

• Download and install Git
• Download and install Visual Studio 2019
  • Check Desktop development with C++ prior to installing
• Download and install CMake >= v 3.18
• Download and install Python

VS2019 Notes

If seeing issues when trying to build (steps in ), some things to check/try: - Try running the build commands within the Developer Command Prompt for VS2019 - Make sure MSBuild can find the correct VCTargetsPath + It is possible the VCTargetsPath environment variable needs to be set. The below example is based on a typical path, but the actual setting should match that of your current environment setup. * set VCTargetsPath=C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\MSBuild\Microsoft\VC\v160 - Make sure CMake is picking up the correct generator + It is possible the CMAKE_GENERATOR environment variable needs to be set * set CMAKE_GENERATOR=Visual Studio 16 2019

Build the Python SDK

Clone this Python SDK repository:

git clone --depth 1 --recurse-submodules https://github.com/couchbase/couchbase-python-client.git

NOTE: If the --recurse-submodules option was not used when cloning the Python SDK repository, run (after moving into the cloned repository directory) git submodule update --init --recursive to recursively update and initialize the submodules.

Move into the directory created after cloning the Python SDK repository:

cd couchbase-python-client

The following will compile the module locally:

python setup.py build_ext --inplace

You can also modify the environment CFLAGS and LDFLAGS variables.

:exclamation:WARNING: If you do not intend to install this module, ensure you set the PYTHONPATH environment variable to this directory before running any scripts depending on it. Failing to do so may result in your script running against an older version of this module (if installed), or throwing an exception stating that the couchbase module could not be found.

Install

pip install .

:exclamation:WARNING: If you are on Linux/Mac OS you may need to remove the build directory: rm -rf ./build before installing with pip: pip3 install ..

Using the SDK

Back to Contents

Connecting

See official documentation for further details on connecting.

# needed for any cluster connection
from couchbase.cluster import Cluster
from couchbase.auth import PasswordAuthenticator

# options for a cluster and SQL++ (N1QL) queries
from couchbase.options import ClusterOptions, QueryOptions

# get a reference to our cluster
cluster = Cluster.connect('couchbase://localhost', ClusterOptions(
  PasswordAuthenticator('Administrator', 'password')))

NOTE: The authenticator is always required.

Basic Operations

See official documentation for further details on Working with Data.

Building upon the example code in the Connecting section:

```python

get a reference to our bucket

cb = cluster.bucket('travel-sample')

get a reference to the default collection

cb_coll = cb.default_collection()

get a