jim-easterbrook / python-gphoto2

python-gphoto2 v\ 2.6.3 ======================= python-gphoto2 is a comprehensive Python interface (or binding) to libgphoto2_. It is built using SWIG_ to automatically generate the interface code. This gives direct access to nearly all the libgphoto2 functions_, but sometimes in a rather un-Pythonic manner. Other Python bindings to libgphoto2_ are available: piggyphoto_ uses ctypes_ (included in standard Python installations) to interface to the library. The gphoto2 source tree includes some _ which also use ctypes_. _ uses cffi_. .. contents:: :backlinks: top Installation ------------ Since python-gphoto2 version 2.3.1 "binary wheels" are provided for many Linux and MacOS computers. These include a recent version of the libgphoto2_ libraries, and pre-built Python interface modules, which makes installation quick and easy. Use pip_'s --only-binary option to install one of these wheels:: $ pip3 install gphoto2 --user --only-binary :all: If this fails it is most likely because none of the available wheels is compatible with your computer. In this case you *must* install some dependencies before installing python-gphoto2. See _ for more details. Raspberry Pi ^^^^^^^^^^^^ Binary wheels for the Raspberry Pi are available from piwheels_. You need to install some system packages to use these:: $ sudo apt install libexif12 libgphoto2-6 libgphoto2-port12 libltdl7 $ pip3 install gphoto2 --user --only-binary :all: Using python-gphoto2 -------------------- The Python interface to libgphoto2_ should allow you to do anything you could do in a C program. However, there are still bits missing and functions that cannot be called from Python. Let me know if you run into any problems. The following paragraphs show how the Python interfaces differ from C. See the example programs for typical usage of the Python gphoto2 API. "C" interface ^^^^^^^^^^^^^ These functions are as similar as possible to their libgphoto2_ equivalents. Most of them return an error code which you must check. Using SWIG_ to generate the Python interfaces automatically means that every function in libgphoto2_ *should* be available to Python. You can show the documentation of a function with the pydoc command (or python -m pydoc if you installed gphoto2 with pip inside a virtual environment):: $ pydoc3 gphoto2.gp_camera_folder_list_files Help on built-in function gp_camera_folder_list_files in gphoto2: gphoto2.gp_camera_folder_list_files = gp_camera_folder_list_files(...) gp_camera_folder_list_files(camera, folder, context) -> int Parameters ---------- camera: gphoto2.Camera folder: str context: gphoto2.Context (default=None) Lists the files in supplied . Parameters ---------- • : a Camera • : a folder • : a CameraList • : a GPContext Returns ------- a gphoto2 error code See also gphoto2.Camera.folder_list_files The first part of this text is the function signature and parameter list generated by SWIG. (Note that context is optional - it's only needed if you need the callback functions that can be associated with a context.) The rest of the text is copied from the "doxygen" format documentation in the C source code. (The online _ shows how it is intended to look.) Note that this includes a list parameter that is not in the function signature. In C this is an "output" parameter, a concept that doesn't really exist in Python. The Python version of gp_camera_folder_list_files returns a sequence containing the integer error code and the list value. Most of the libgphoto2_ functions that use pointer parameters to return values in the C API have been adapted like this in the Python API. (Unfortunately I've not found a way to persuade SWIG_ to include this extra return value in the documentation. You should use pydoc to check the actual parameters expected by the Python function.) For example, the C code: .. code:: c #include "gphoto2.h" int error; Camera *camera; error = gp_camera_new(&camera); ... error = gp_camera_unref(camera); has this Python equivalent: .. code:: python import gphoto2 as gp error, camera = gp.gp_camera_new() ... Note that the gp_camera_unref() call is not needed. It is called automatically when the Python camera object is deleted. Here is a complete example program (without any error checking): .. code:: python import gphoto2 as gp error, camera = gp.gp_camera_new() error = gp.gp_camera_init(camera) error, text = gp.gp_camera_get_summary(camera) print('Summary') print('=======') print(text.text) error = gp.gp_camera_exit(camera) "Object oriented" interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^ This is the preferred way to use libgphoto2_ from Python. Most of the libgphoto2_ functions have been added as methods of the appropriate GPhoto2 object. This allows GPhoto2 to be used in a more "Pythonic" style. For example, gp.gp_camera_init(camera) can be replaced by camera.init() . These methods also include error checking. If an error occurs they raise a Python GPhoto2Error exception. The example program can be re-written as follows: .. code:: python import gphoto2 as gp camera = gp.Camera() camera.init() text = camera.get_summary() print('Summary') print('=======') print(str(text)) camera.exit() No additional error checking is required. Error checking ^^^^^^^^^^^^^^ Most of the libgphoto2_ functions return an integer to indicate success or failure. The Python interface includes a check_result() function to check these values and raise a GPhoto2Error exception if an error occurs. This function also removes the error code from lists such as that returned by gp_camera_new() in the example. Using this function the earlier example becomes: .. code:: python import gphoto2 as gp camera = gp.check_result(gp.gp_camera_new()) gp.check_result(gp.gp_camera_init(camera)) text = gp.check_result(gp.gp_camera_get_summary(camera)) print('Summary') print('=======') print(text.text) gp.check_result(gp.gp_camera_exit(camera)) There may be some circums…