Package: couchbase
Couchbase Python ClientPython client forCouchbaseNOTE: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 therelease32branch for the older 3.x version.ContentsPrerequisitesInstallingBuildingUsing the SDKBuilding DocumentationTestingContributingSupport & Additional ResourcesLicenseAppendixPrerequisitesCouchbase ServerYou 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 UbuntuFirst-time setup:$sudoaptinstallgit-allpython3-devpython3-pippython3-setuptoolscmakebuild-essentiallibssl-devNOTE:We have providedDockerfilesto demonstrate steps to achieve a working setup for various linux platforms. See thedockerfiles folderin the Python SDK examples folder for details.SeeDebian and Ubuntuinstall section to install SDK.RHEL and CentOSFirst-time setup:$sudoyuminstallgit-allgccgcc-c++python3-develpython3-pippython3-setuptoolscmakeopenssl-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 SDKminimum 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 versionwillneed to be udpated.The default OpenSSL version might be less than 1.1.1.  If so, the OpenSSL versionwillneed to be updated.The gcc version must provide C++17 support.  If the installed gcc version does not support C++17, gccwillneed to be updated.The installed CMake version might be less than 3.17.  If so, the CMake versionwillneed to be updated.  Check out the stepshereto update CMake.NOTE:We have providedDockerfilesto demonstrate steps to achieve a working setup for various linux platforms. See thedockerfiles folderin the Python SDK examples folder for details.SeeRHEL and Centosinstall section to install SDK.Mac OSIt 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:pyenvHomebrewInstall Python viapython.orgpyenvSee detailed walk through inAppendix.  Also, see pyenv installdocsfor 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.HomebrewSee Homebrew installdocsfor further details.Get the latest packages:$brewupdateInstall Python:$brewinstallpythonUpdate path:zsh:$echo'export PATH="/usr/local/bin:"$PATH'>>~/.zshrcbash:$echo'export PATH="/usr/local/bin:"$PATH'>>~/.bash_profileInstall OpenSSL:$brewinstallopenssl@1.1To get OpenSSL to be found by cmake on macos, find where openssl was
installed via homebrew:brew info openssl@1.1This will show you how to get it seen by pkg-config. To check that it
worked, do this:pkg-config --modversion opensslSeeMac OSinstall section to install SDK.WindowsWheels 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 thepyenv-winproject) to manage multiple versions of Python.If wanting to install from source, see theWindows buildingsection for details.SeeWindows installsection to install SDK.InstallingBack to ContentsYou can always get the latest supported release version frompypi.NOTE:If you have a recent version ofpip, you may use the latest development version by issuing the following incantation:pip install git+https://github.com/couchbase/couchbase-python-client.gitNOTE: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:python3 -m pip install --upgrade pip setuptools wheelDebian and UbuntuFirst, make sure theprerequisiteshave been installed.Install the SDK:$python3-mpipinstallcouchbaseRHEL and CentOSFirst, make sure theprerequisiteshave been installed.Install the SDK:$python3-mpipinstallcouchbaseMac OSFirst, make sure theprerequisiteshave been installed.Install the SDK:$python-mpipinstallcouchbaseWindowsFirst, make sure theprerequisiteshave 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 frompython.org:-C:\Users\Administrator\AppData\Local\Programs\Python\Python39\python -m venv C:\python\python39-C:\python\python39\Scripts\activateInstall the SDK (if using Python 3.7, 3.8, 3.9 or 3.10):python -m pip install couchbaseAlternative Installation MethodsIn order to successfully install with the following methods, ensure a proper build system is in place (see theWindows buildingsection for details).Source Install (i.e. no wheel)First, ensure all therequirementsfor a build system are met.Install the SDK:python -m pip install couchbase --no-binary couchbaseLocal InstallFirst, ensure all therequirementsfor 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.gitWhere 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.gitMove into the directory created after cloning the Python SDK repository:cd couchbase-python-clientNOTE:If the--recurse-submodulesoption was not used when cloning the Python SDK repository, run (after moving into the cloned repository directory)git submodule update --init --recursiveto recursively update and initialize the submodules.Install the SDK from source:python -m pip install .Anaconda/MinicondaTo use the SDK within the Anaconda/Miniconda platform, make sure the prerequisites for the desired Operating System are met:Debian and UbuntuRHEL and CentosMac OSWindowsIn theAnaconda Prompt, create a new environment:(base)C:\Users\user1>conda create -n test_env python=3.9Activate the environment(base)C:\Users\user1>conda activate test_envInstall the SDK:(test_env)C:\Users\user1>python -m pip install couchbaseNOTE:If using Windows, and no wheel is available, see theAlternative Install Methods Windowssection.  The same process should work within the Anaconda/Miniconda platform.BuildingBack to ContentsNOTE:This section only applies to building from source.Build System SetupLinuxMake sure the prerequisites have been installed:Debian and UbuntuRHEL and CentosMac OSFirst, make sure theprerequisiteshave been installed.Install cmake:$brewinstallcmakeInstall command line developer tools:$ xcode-select --installNOTE:It is possible that installing or updating to the the latest version ofXcodeis needed.If setuptools is not installed:$python-mpipinstallsetuptoolsWindowsRequirementsDownload and installGitDownload and installVisual Studio 2019CheckDesktop development with C++prior to installingDownload and installCMake>= v 3.18Download and installPythonVS2019 NotesIf seeing issues when trying to build (steps in), some things to check/try:Try running the build commands within theDeveloper Command Prompt for VS2019Make sureMSBuildcan find the correctVCTargetsPathIt is possible theVCTargetsPathenvironment 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\v160Make sureCMakeis picking up the correct generatorIt is possible theCMAKE_GENERATORenvironment variable needs to be setset CMAKE_GENERATOR=Visual Studio 16 2019Build the Python SDKClone this Python SDK repository:git clone --depth 1 --recurse-submodules https://github.com/couchbase/couchbase-python-client.gitNOTE:If the--recurse-submodulesoption was not used when cloning the Python SDK repository, run (after moving into the cloned repository directory)git submodule update --init --recursiveto recursively update and initialize the submodules.Move into the directory created after cloning the Python SDK repository:cd couchbase-python-clientThe following will compile the module locally:python setup.py build_ext --inplaceYou can also modify the environmentCFLAGSandLDFLAGSvariables.:exclamation:WARNING:If you do not intend to install this module, ensure you set thePYTHONPATHenvironment 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 thecouchbasemodule could not be found.Installpip install .:exclamation:WARNING:If you are on Linux/Mac OS you may need to remove the build directory:rm -rf ./buildbefore installing with pip:pip3 install ..Using the SDKBack to ContentsConnectingSeeofficial documentationfor further details on connecting.# needed for any cluster connectionfromcouchbase.clusterimportClusterfromcouchbase.authimportPasswordAuthenticator# options for a cluster and SQL++ (N1QL) queriesfromcouchbase.optionsimportClusterOptions,QueryOptions# get a reference to our clustercluster=Cluster.connect('couchbase://localhost',ClusterOptions(PasswordAuthenticator('Administrator','password')))NOTE:The authenticator is always required.Basic OperationsSee official documentation for further details onWorking with Data.Building upon the example code in theConnectingsection:# get a reference to our bucketcb=cluster.bucket('travel-sample')# get a reference to the default collectioncb_coll=cb.default_collection()# get a documentresult=cb_coll.get('airline_10')print(result.content_as[dict])# using SQL++ (a.k.a N1QL)call_sign='CBS'sql_query='SELECT VALUE name FROM `travel-sample` WHERE type = "airline" AND callsign = $1'query_res=cluster.query(sql_query,QueryOptions(positional_parameters=[call_sign]))forrowinquery_res:print(row)Async OperationsThe Python Couchbase SDK supports asynchronous I/O through the use of the asyncio (Python standard library) or the Twisted async framework.AsyncioTo use asyncio, importacouchbase.clusterinstead ofcouchbase.cluster.  TheacouchbaseAPI offers an API similar to thecouchbaseAPI.fromacouchbase.clusterimportCluster,get_event_loopfromcouchbase.optionsimportClusterOptionsfromcouchbase.authimportPasswordAuthenticatorasyncdefwrite_and_read(key,value):cluster=awaitCluster.connect('couchbase://localhost',ClusterOptions(PasswordAuthenticator('Administrator','password')))cb=cluster.bucket('default')awaitcb.on_connect()cb_coll=cb.default_collection()awaitcb_coll.upsert(key,value)result=awaitcb_coll.get(key)returnresultloop=get_event_loop()rv=loop.run_until_complete(write_and_read('foo','bar'))print(rv.content_as[str])TwistedTo use with Twisted, importtxcouchbase.clusterinstead ofcouchbase.cluster.  ThetxcouchbaseAPI offers an API similar to thecouchbaseAPI.NOTE:The minimum required Twisted version is 21.7.0.:exclamation:WARNING:The 4.x SDK introduced a breaking change where the txcouchbase package must be importedpriorto importing the reactor (see example below).  This is so that the asyncio reactor can be installed.# IMPORTANT -- the txcouchbase import must occur PRIOR to importing the reactorimporttxcouchbasefromtwisted.internetimportreactor,deferfromtxcouchbase.clusterimportTxClusterfromcouchbase.optionsimportClusterOptionsfromcouchbase.authimportPasswordAuthenticatordefafter_upsert(res,key,d):print('Set key.  Result CAS: ',res.cas)# trigger get_document callbackd.callback(key)defupsert_document(key,doc):d=defer.Deferred()res=cb.upsert(key,doc)res.addCallback(after_upsert,key,d)returnddefon_get(res,_type=str):print('Got res:\n',res.content_as[_type])reactor.stop()defget_document(key):res=cb.get(key)res.addCallback(on_get)# create a cluster objectcluster=TxCluster('couchbase://localhost',ClusterOptions(PasswordAuthenticator('Administrator','password')))# create a bucket objectbucket=cluster.bucket('default')# create a collection objectcb=bucket.default_collection()d=upsert_document('testDoc_1',{'id':1,'type':'testDoc','info':'fake document'})d.addCallback(get_document)reactor.run()Building DocumentationBack to ContentsThe documentation is using Sphinx and a number of extensions.  To build the documentation be sure topip installthe sphinx_requirements.txt.python3 -m pip install -r sphinx_requirements.txtTo build the documentation, go into the docs directory and run:make htmlThe HTML output can be found in docs/build/html/.Alternatively, you can also build the documentation from the top-level directory:python setup.py build_sphinxOnce built, the docs will be in in build/sphinx/html.  You can open the index.html file with the following command:open docs/build/sphinx/html/index.htmlTestingBack to ContentsFor running the tests, be sure topip installthe dev_requirements.txt.  The Couchbase Python SDK uses pytest for the test suite.python3 -m pip install -r dev_requirements.txtThe tests need a running Couchbase instance. For this, a test_config.ini file must be present, containing various connection parameters. The default test_config.ini file may be found in the tests directory. You may modify the values of the test_config.ini file as needed.To run the tests for the blocking API (i.e. couchbase API):python -m pytest -m pycbc_couchbase -p no:asyncio -v -p no:warningsTo run the tests for the asyncio API (i.e. acouchbase API):python -m pytest -m pycbc_acouchbase --asyncio-mode=strict -v -p no:warningsContributingBack to ContentsWe welcome contributions from the community!  Please see follow the steps outlinedhereto get started.The Python SDK uses pre-commit in order to handle linting, formatting and verifying the code base.
pre-commit can be installed either by installing the development requirements:python3 -m pip install -r dev_requirements.txtOr by installing pre-commit separatelypython3 -m pip install pre-commitTo run pre-commit, use the following:pre-commit run --all-filesLicenseBack to ContentsThe Couchbase Python SDK is licensed under the Apache License 2.0.SeeLICENSEfor further details.Support & Additional ResourcesBack to ContentsIf you found an issue, please file it in ourJIRA.The Couchbase Discord server is a place where you can collaborate about all things Couchbase. Connect with others from the community, learn tips and tricks, and ask questions.Join Discord and contribute.You can ask questions in ourforums.Theofficial documentationcan be consulted as well for general Couchbase concepts and offers a more didactic approach to using the SDK.AppendixBack to ContentsMac OS pyenv InstallSee pyenv installdocsfor further details.Get the latest packages:$brewupdateFor TLS/SSL support:$brewinstallopenssl@1.1Install pyenv:$brewinstallpyenvNOTE:It is possible that Xcode might need to be reinstalled.  Tryoneof the following:Use commandxcode-select --installInstall the latest version ofXcodeForZsh, run the following commands to update.zprofileand.zshrc.  See pyenv installdocsfor further details on other shells.$echo'eval "$(pyenv init --path)"'>>~/.zprofile$echo'eval "$(pyenv init -)"'>>~/.zshrcNOTE:You need to restart your login session for changes to take affect.  On MacOS, restarting terminal windows should suffice.Install Python version:$pyenvinstall3.9.7Set local shell to installed Python version:$pyenvlocal3.9.7To use virtualenvwrapper with pyenv, install pyenv-virtualenvwrapper:$brewinstallpyenv-virtualenvwrapperTo setup a virtualenvwrapper in your pyenv shell, run eitherpyenv virtualenvwrapperorpyenv virtualenvwrapper_lazyNOTE:If issues withpyenv virtualenvwrapper, usingpython -m pip install virtualenvwrappershould accomplish the same goal.Make a virtualenv:$mkvirtualenvpython-3.9.7-testInstall the SDK:$python-mpipinstallcouchbaseRun individual pre-commit commandsTo run pre-commit hooks separately, use the following.autopep8pre-commit run autopep8 --all-filesbanditpre-commit run bandit --all-filesclang-formatpre-commit run clang-format --all-filesflake8pre-commit run flake8 --all-filesisortpre-commit run isort --all-filestrailing whitespacepre-commit run trailing-whitespace --all-files