Mercurial > pub > dyncall > bindings

comparison python/pydc/README.txt @ 54:918dab7a6606

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
- added callback support (comes with some bigger refactoring) - allow CPython's Py{CObject,Capsule} to be used as 'p'ointers
author Tassilo Philipp
date Tue, 02 Feb 2021 20:42:02 +0100
parents c5ca08cd3e78
children 80b11152c659
comparison
equal deleted inserted replaced
53:6387d39ecce2 54:918dab7a6606
13 Apr 13, 2020: added signature char support to specify calling conventions 13 Apr 13, 2020: added signature char support to specify calling conventions
14 Oct 27, 2020: allowing 'None' for 'p' params, always passing NULL 14 Oct 27, 2020: allowing 'None' for 'p' params, always passing NULL
15 Nov 13, 2020: removed pydc.py wrapper overhead (which only called pydcext.so 15 Nov 13, 2020: removed pydc.py wrapper overhead (which only called pydcext.so
16 functions; implies renaming pydcext.* to pydc.*), added type stub 16 functions; implies renaming pydcext.* to pydc.*), added type stub
17 as package_data 17 as package_data
18 Feb 2, 2021: added callback support (comes with some bigger refactoring);
19 allow CPython's Py{CObject,Capsule} to be used as 'p'ointers
18 20
19 21
20 BUILD/INSTALLATION 22 BUILD/INSTALLATION
21 ================== 23 ==================
22 24
31 33
32 34
33 API 35 API
34 === 36 ===
35 37
36 In a nutshell: 38 In a nutshell for all calls:
37 39
38 libhandle = load(libpath) # if path == None => handle to running process 40 libhandle = load(libpath) # if path == None => handle to running process
39 libpath = get_path(libhandle) # if handle == None => path to executable 41 libpath = get_path(libhandle) # if handle == None => path to executable
40 funcptr = find(libhandle, symbolname) 42 funcptr = find(libhandle, symbolname) # lookup symbol by name
41 call(funcptr, signature, ...) 43 call(funcptr, signature, ...) # call C func w/ signature and corresponding args
42 free(libhandle) 44 free(libhandle) # free library
45
46 For callback objects to be passed as 'p'ointer args:
47
48 cbhandle = new_callback(signature, pyfunc) # signature reflecting C func ptr
49 free_callback(cbhandle) # release callback object
43 50
44 Notes: 51 Notes:
45 - a pydc.pyi stub file with the precise interface description is available 52 - a pydc.pyi stub file with the precise interface description is available
46 - there are no functions to set the calling convention mode, however, it can be 53 - there are no functions to set the calling convention mode, however, it can be
47 set using the signature 54 set using the signature
82 'd' | float (PyFloat) | float (PyFloat) | double | float (PyFloat) | float (PyFloat) 89 'd' | float (PyFloat) | float (PyFloat) | double | float (PyFloat) | float (PyFloat)
83 'p' | bytearray (PyByteArray) & | bytearray (PyByteArray) & | void* | int,long (Py_ssize_t) | int (Py_ssize_t) 90 'p' | bytearray (PyByteArray) & | bytearray (PyByteArray) & | void* | int,long (Py_ssize_t) | int (Py_ssize_t)
84 | int (PyInt) | int (PyLong) | void* | int,long (Py_ssize_t) | int (Py_ssize_t) 91 | int (PyInt) | int (PyLong) | void* | int,long (Py_ssize_t) | int (Py_ssize_t)
85 | long (PyLong) | - | void* | int,long (Py_ssize_t) | int (Py_ssize_t) 92 | long (PyLong) | - | void* | int,long (Py_ssize_t) | int (Py_ssize_t)
86 | None (Py_None) | None (Py_None) | void* (always NULL) | int,long (Py_ssize_t) | int (Py_ssize_t) 93 | None (Py_None) | None (Py_None) | void* (always NULL) | int,long (Py_ssize_t) | int (Py_ssize_t)
94 | (PyCObject,PyCapsule) | (PyCObject,PyCapsule) | void* | int,long (Py_ssize_t) | int (Py_ssize_t) @@@ test
87 'Z' | str (PyString) ! | str (PyUnicode) ! | const char* (UTF-8 for unicode) | str (PyString) | str (PyUnicode) 95 'Z' | str (PyString) ! | str (PyUnicode) ! | const char* (UTF-8 for unicode) | str (PyString) | str (PyUnicode)
88 | unicode (PyUnicode) ! | - | const char* (UTF-8 for unicode) | str (PyString) | str (PyUnicode) 96 | unicode (PyUnicode) ! | - | const char* (UTF-8 for unicode) | str (PyString) | str (PyUnicode)
89 | - | bytes (PyBytes) ! | const char* (UTF-8 for unicode) | str (PyString) | str (PyUnicode) 97 | - | bytes (PyBytes) ! | const char* (UTF-8 for unicode) | str (PyString) | str (PyUnicode)
90 | bytearray (PyByteArray) ! | bytearray (PyByteArray) ! | const char* (UTF-8 for unicode) | str (PyString) | str (PyUnicode) 98 | bytearray (PyByteArray) ! | bytearray (PyByteArray) ! | const char* (UTF-8 for unicode) | str (PyString) | str (PyUnicode)
91 99
94 @ converted to False if 0 and True otherwise 102 @ converted to False if 0 and True otherwise
95 % range/length checked 103 % range/length checked
96 $ cast to single precision 104 $ cast to single precision
97 ^ cast to double precision 105 ^ cast to double precision
98 & mutable buffer when passed to C 106 & mutable buffer when passed to C
99 ! immutable buffer when passed to C, as strings (in any form) are considered objects, not buffers 107 ! immutable buffer when passed to C, as strings (in any form) are considered objects, not buffers; also, not allowed as return type in callback signatures
100 108
101 109
102 Also supported are specifying calling convention switches using '_'-prefixed 110 Also supported are specifying calling convention switches using '_'-prefixed
103 signature characters: 111 signature characters:
104 112
120 128
121 129
122 TODO 130 TODO
123 ==== 131 ====
124 132
125 - callback support 133 - calling convention mode handling for callbacks (not sure if ever needed?)
126 - pydoc "man page" 134 - pydoc "man page"
127 - stub location: the pydc-stubs folder isn't picked up by mypy, so I question why this is the suggested way 135 - stub location: the pydc-stubs folder isn't picked up by mypy, so I question why this is the suggested way
128 - get into freebsd ports 136 - get into freebsd ports
129 137
130 138