documented adaptor.py