Mercurial > pub > dyncall > bindings
annotate python/pydc/README.txt @ 46:c21d1c2c84e1
- removed pydc.py wrapper overhead (which only called pydcext.so functions, directly, anyways)
* implies renaming pydcext.* to pydc.*
* while at it, iterate directly over args that are passed in (before we did extract fptr, sig and a tuple for the args and iterated over latter afterwards); we might have a tiny perf improvement now
- added type stub as package_data
| author | Tassilo Philipp |
|---|---|
| date | Fri, 13 Nov 2020 14:10:31 +0100 |
| parents | 0f86a5ecfe61 |
| children | edf5c85de5ac |
| rev | line source |
|---|---|
| 0 | 1 dyncall python bindings |
| 28 | 2 Copyright 2007-2016 Daniel Adler |
| 3 2018-2020 Tassilo Philipp | |
| 4 | |
| 5 Dec 4, 2007: initial | |
| 6 Mar 22, 2016: update to dyncall 0.9, includes breaking sig char changes | |
| 7 Apr 19, 2018: update to dyncall 1.0 | |
| 8 Apr 7, 2020: update to dyncall 1.1, Python 3 support, using the Capsule | |
| 9 API, as well as support for python unicode strings | |
| 34 | 10 Apr 11, 2020: support for getting loaded library path |
| 11 Apr 12, 2020: breaking change: restrict 'Z' conversions to immutable types | |
| 12 and 'p' to mutable types (and handles) | |
| 37 | 13 Apr 13, 2020: added signature char support to specify calling conventions |
|
44
0f86a5ecfe61
- python: allow None to be passed for 'p'ointers, always passing NULL
Tassilo Philipp
parents:
37
diff
changeset
|
14 Oct 27, 2020: allowing 'None' for 'p' params, always passing NULL |
|
46
c21d1c2c84e1
- removed pydc.py wrapper overhead (which only called pydcext.so functions, directly, anyways)
Tassilo Philipp
parents:
44
diff
changeset
|
15 Nov 13, 2020: removed pydc.py wrapper overhead (which only called pydcext.so |
|
c21d1c2c84e1
- removed pydc.py wrapper overhead (which only called pydcext.so functions, directly, anyways)
Tassilo Philipp
parents:
44
diff
changeset
|
16 functions; implies renaming pydcext.* to pydc.*), added type stub |
|
c21d1c2c84e1
- removed pydc.py wrapper overhead (which only called pydcext.so functions, directly, anyways)
Tassilo Philipp
parents:
44
diff
changeset
|
17 as package_data |
| 5 | 18 |
| 0 | 19 |
| 7 | 20 BUILD/INSTALLATION |
|
16
a40084782546
- added support for more return values to python binding
cslag
parents:
10
diff
changeset
|
21 ================== |
| 4 | 22 |
| 23 1) make sure dyncall is built and libraries/headers are in include paths or | |
| 24 CFLAGS points to them, etc. | |
| 25 | |
| 10 | 26 2) Build and install this extension with: |
|
16
a40084782546
- added support for more return values to python binding
cslag
parents:
10
diff
changeset
|
27 |
|
a40084782546
- added support for more return values to python binding
cslag
parents:
10
diff
changeset
|
28 python setup.py install |
|
a40084782546
- added support for more return values to python binding
cslag
parents:
10
diff
changeset
|
29 |
| 28 | 30 Building a wheel package isn't supported, currently. |
| 4 | 31 |
| 32 | |
| 0 | 33 API |
|
16
a40084782546
- added support for more return values to python binding
cslag
parents:
10
diff
changeset
|
34 === |
| 0 | 35 |
|
46
c21d1c2c84e1
- removed pydc.py wrapper overhead (which only called pydcext.so functions, directly, anyways)
Tassilo Philipp
parents:
44
diff
changeset
|
36 In a nutshell: |
|
c21d1c2c84e1
- removed pydc.py wrapper overhead (which only called pydcext.so functions, directly, anyways)
Tassilo Philipp
parents:
44
diff
changeset
|
37 |
| 37 | 38 libhandle = load(libpath) # if path == None => handle to running process |
| 39 libpath = get_path(libhandle) # if handle == None => path to executable | |
| 5 | 40 funcptr = find(libhandle, symbolname) |
| 41 call(funcptr, signature, ...) | |
| 29 | 42 free(libhandle) |
| 0 | 43 |
|
46
c21d1c2c84e1
- removed pydc.py wrapper overhead (which only called pydcext.so functions, directly, anyways)
Tassilo Philipp
parents:
44
diff
changeset
|
44 Notes: |
|
c21d1c2c84e1
- removed pydc.py wrapper overhead (which only called pydcext.so functions, directly, anyways)
Tassilo Philipp
parents:
44
diff
changeset
|
45 - a pydc.pyi stub file with the precise interface description is available |
|
c21d1c2c84e1
- removed pydc.py wrapper overhead (which only called pydcext.so functions, directly, anyways)
Tassilo Philipp
parents:
44
diff
changeset
|
46 - there are no functions to set the calling convention mode, however, it can be |
|
c21d1c2c84e1
- removed pydc.py wrapper overhead (which only called pydcext.so functions, directly, anyways)
Tassilo Philipp
parents:
44
diff
changeset
|
47 set using the signature |
|
c21d1c2c84e1
- removed pydc.py wrapper overhead (which only called pydcext.so functions, directly, anyways)
Tassilo Philipp
parents:
44
diff
changeset
|
48 - not specifying any calling convention in the signature string will use the |
|
c21d1c2c84e1
- removed pydc.py wrapper overhead (which only called pydcext.so functions, directly, anyways)
Tassilo Philipp
parents:
44
diff
changeset
|
49 platform's default one |
| 37 | 50 |
| 7 | 51 |
| 0 | 52 SIGNATURE FORMAT |
|
16
a40084782546
- added support for more return values to python binding
cslag
parents:
10
diff
changeset
|
53 ================ |
| 0 | 54 |
|
35
75fe1dec0eb4
- added support for signature-based calling convention switch
Tassilo Philipp
parents:
34
diff
changeset
|
55 ignoring calling convention mode switching for simplicity, the signature is |
|
75fe1dec0eb4
- added support for signature-based calling convention switch
Tassilo Philipp
parents:
34
diff
changeset
|
56 a string with the following format (using * as regex-like repetition): |
| 0 | 57 |
|
35
75fe1dec0eb4
- added support for signature-based calling convention switch
Tassilo Philipp
parents:
34
diff
changeset
|
58 "x*)y" |
| 0 | 59 |
|
35
75fe1dec0eb4
- added support for signature-based calling convention switch
Tassilo Philipp
parents:
34
diff
changeset
|
60 where x is positional parameter-type charcode (per argument), y is result-type charcode |
|
75fe1dec0eb4
- added support for signature-based calling convention switch
Tassilo Philipp
parents:
34
diff
changeset
|
61 |
| 0 | 62 |
| 34 | 63 SIG | FROM PYTHON 2 | FROM PYTHON 3 | C/C++ | TO PYTHON 2 | TO PYTHON 3 |
| 64 ----+---------------------------------+---------------------------------+---------------------------------+--------------------------------------+--------------------------------------- | |
| 65 'v' | | | void | None (Py_None) (e.g. ret of "...)v") | None (Py_None) (e.g. ret of "...)v") | |
| 66 'B' | bool (PyBool) | bool (PyBool) # | int/bool | bool (PyBool) | bool (PyBool) @ | |
| 67 'c' | int (PyInt) % | int (PyLong) % | char | int (PyInt) | int (PyLong) | |
| 68 | str (with only a single char) % | str (with only a single char) % | char | int (PyInt) | int (PyLong) | |
| 69 'C' | int (PyInt) % | int (PyLong) % | unsigned char | int (PyInt) | int (PyLong) | |
| 70 | str (with only a single char) % | str (with only a single char) % | unsigned char | int (PyInt) | int (PyLong) | |
| 71 's' | int (PyInt) % | int (PyLong) % | short | int (PyInt) | int (PyLong) | |
| 72 'S' | int (PyInt) % | int (PyLong) % | unsigned short | int (PyInt) | int (PyLong) | |
| 73 'i' | int (PyInt) | int (PyLong) | int | int (PyInt) | int (PyLong) | |
| 74 'I' | int (PyInt) | int (PyLong) | unsigned int | int (PyInt) | int (PyLong) | |
| 75 'j' | int (PyInt) | int (PyLong) | long | int (PyInt) | int (PyLong) | |
| 76 'J' | int (PyInt) | int (PyLong) | unsigned long | int (PyInt) | int (PyLong) | |
| 77 'l' | int (PyInt) | int (PyLongLong) | long long | long (PyLong) | int (PyLong) | |
| 78 | long (PyLong) | - | long long | long (PyLong) | int (PyLong) | |
| 79 'L' | int (PyInt) | int (PyLongLong) | unsigned long long | long (PyLong) | int (PyLong) | |
| 80 | long (PyLong) | - | unsigned long long | long (PyLong) | int (PyLong) | |
| 81 'f' | float (PyFloat) $ | float (PyFloat) $ | float | float (PyFloat) ^ | float (PyFloat) ^ | |
| 82 '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) | |
| 84 | 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) | |
|
44
0f86a5ecfe61
- python: allow None to be passed for 'p'ointers, always passing NULL
Tassilo Philipp
parents:
37
diff
changeset
|
86 | None (Py_None) | None (Py_None) | void* (always NULL) | int,long (Py_ssize_t) | int (Py_ssize_t) |
| 34 | 87 'Z' | str (PyString) ! | str (PyUnicode) ! | const char* (UTF-8 for unicode) | int (PyString) | str (PyUnicode) |
| 88 | unicode (PyUnicode) ! | - | const char* (UTF-8 for unicode) | int (PyString) | str (PyUnicode) | |
| 89 | - | bytes (PyBytes) ! | const char* (UTF-8 for unicode) | int (PyString) | str (PyUnicode) | |
| 90 | bytearray (PyByteArray) ! | bytearray (PyByteArray) ! | const char* (UTF-8 for unicode) | int (PyString) | str (PyUnicode) | |
| 0 | 91 |
| 37 | 92 Annotations: |
|
35
75fe1dec0eb4
- added support for signature-based calling convention switch
Tassilo Philipp
parents:
34
diff
changeset
|
93 # converted to 1 if True and 0 otherwise |
|
75fe1dec0eb4
- added support for signature-based calling convention switch
Tassilo Philipp
parents:
34
diff
changeset
|
94 @ converted to False if 0 and True otherwise |
|
75fe1dec0eb4
- added support for signature-based calling convention switch
Tassilo Philipp
parents:
34
diff
changeset
|
95 % range/length checked |
|
75fe1dec0eb4
- added support for signature-based calling convention switch
Tassilo Philipp
parents:
34
diff
changeset
|
96 $ cast to single precision |
|
75fe1dec0eb4
- added support for signature-based calling convention switch
Tassilo Philipp
parents:
34
diff
changeset
|
97 ^ cast to double precision |
|
75fe1dec0eb4
- added support for signature-based calling convention switch
Tassilo Philipp
parents:
34
diff
changeset
|
98 & mutable buffer when passed to C |
|
75fe1dec0eb4
- added support for signature-based calling convention switch
Tassilo Philipp
parents:
34
diff
changeset
|
99 ! immutable buffer when passed to C, as strings (in any form) are considered objects, not buffers |
|
75fe1dec0eb4
- added support for signature-based calling convention switch
Tassilo Philipp
parents:
34
diff
changeset
|
100 |
|
75fe1dec0eb4
- added support for signature-based calling convention switch
Tassilo Philipp
parents:
34
diff
changeset
|
101 |
| 37 | 102 Also supported are specifying calling convention switches using '_'-prefixed |
| 103 signature characters: | |
| 104 | |
| 105 SIG | DESCRIPTION | |
| 106 ----+----------------------------------------------------------------------------------------------------------- | |
| 107 '_' | prefix indicating that next signature character specifies calling convention; char is one of the following | |
| 108 ':' | platform's default calling convention | |
| 109 'e' | vararg function | |
| 110 '.' | vararg function's variadic/ellipsis part (...), to be specified before first vararg | |
| 111 'c' | only on x86: cdecl | |
| 112 's' | only on x86: stdcall | |
| 113 'F' | only on x86: fastcall (MS) | |
| 114 'f' | only on x86: fastcall (GNU) | |
| 115 '+' | only on x86: thiscall (MS) | |
| 116 '#' | only on x86: thiscall (GNU) | |
| 117 'A' | only on ARM: ARM mode | |
| 118 'a' | only on ARM: THUMB mode | |
| 119 '$' | syscall | |
|
35
75fe1dec0eb4
- added support for signature-based calling convention switch
Tassilo Philipp
parents:
34
diff
changeset
|
120 |
|
16
a40084782546
- added support for more return values to python binding
cslag
parents:
10
diff
changeset
|
121 |
|
a40084782546
- added support for more return values to python binding
cslag
parents:
10
diff
changeset
|
122 TODO |
|
a40084782546
- added support for more return values to python binding
cslag
parents:
10
diff
changeset
|
123 ==== |
|
a40084782546
- added support for more return values to python binding
cslag
parents:
10
diff
changeset
|
124 |
| 28 | 125 - callback support |
| 5 | 126 |
|
35
75fe1dec0eb4
- added support for signature-based calling convention switch
Tassilo Philipp
parents:
34
diff
changeset
|
127 |
| 30 | 128 BUGS |
| 129 ==== | |
| 130 | |
| 131 - when using Python 2, the dyncall call vm object is never dcFree'd, as there | |
| 132 is no way to call a "freefunc" as introduced with Python 3 module definitions | |
| 133 (see PEP 3121 for details) | |
| 134 |