Developers Guide

Setting up your environment

  • install prerequisites (python >= 3.6, git, optionally lz4, snappy)
  • Check out the project
cd ~/workspace
git clone https://github.com/toppk/pysandra
cd pysandra
  • Setup your virtualenv:
python -m venv venv/
source venv/bin/activate
pip install -r  test-requirements.txt
pip install -e .
pip install -e tools/cqlshell

Since you were "inside" the virtualenv, you will have to run source venv/bin/activate each time you start a new shell to get end. You can use deactivate a shell function that active installs, to leave the virtualenv. Within the virtualenv, you can run pytest and the tools as follow:

pytest # run all tests
pytest -m "not live" # run only unit tests
python -mcqlshell.testasync dml  # run the dml test function
PYSANDRA_LOG_LEVEL=DEBUG python -mcqlshell.testasync dml  # run the dml test function with debug logging
testasync dml -d
testasync sim --port 37891 -d # connect to sim server

There are scripts inside pysandra/scripts to help with these steps. (e.g. scripts/bootstrap will setup a virtualenv and install the packages). You can also run the test automation tool nox. Nox will setup its own virtualenvs for execution, however you will still need to be inside of the virtualenv if you don't have nox installed elsewhere. By default nox will do a complete pipeline of linting, formating, then test suits, and ensuring that all packages are up to date. It will also run the test suit against several different python interpretors. There are many ways you can run it, for example:

nox # default run
nox -s check # just the linters
nox -s test # just the tests
nox -s test-3.6 # just the test on python36
nox -s test-3.6 -- -m "live"  # after the "--" the parameters are passed to pytest, in this case just run the tests that hit a cassandra instance on localhost:9042
nox -s serve # start the mkdocs server

You can think of nox as a replacement for a makefile. There are some scripts that have similar execution inside of scripts/ as well

  1. run test automation: nox

Touring the code base

pysandra/ - most of the content in the top level are related to SDLC
   pysandra/ - the driver code
         /__about__.py
         /client.py - this is the entrypoint for users, creates a connection for sending requests
         /connection.py - connect holds connection details, creates a dispatcher to communicate
         /constants.py - constants for the wireprotocol as well as driver settings (timeouts, defaults, etc)
         /core.py - some generic classes in use by other modules
         /dispatcher.py - handles the communications between the client and protocol
         /exceptions.py - exceptions for the driver
         /__init__.py - the API
         /messages.py - the wireprotocol messages (factories and encoders)
         /codecs.py - the encodes, decoders routines
         /types.py - the data types that the API will send to the user
         /utils.py - some utility functions (e.g. loggin)
         /protocol.py - the abstract base class for the protocol handler
         /v4protocol.py - this speaks to the dispatcher to decide how request should look on the wire, and how to handle responses
   tests/ - pytest tests (there are subdirectories for live testing
   tools/ - currently contains testasync.py which has some driver example cases
   scripts/ - some SDLC related scripts (nox can do everything itself, execpt to provide the nox tool :)