Mercurial > pub > dyncall > bindings
annotate python/pydc/README.txt @ 59:2725de59454a
- fixed potentially uninitialized ptr
- added todo item to release GIL under certain circumstances
author | Tassilo Philipp |
---|---|
date | Tue, 22 Jun 2021 18:49:02 +0200 |
parents | 80b11152c659 |
children | 8e905c0798c7 |
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 |
57 | 18 Jan 23, 2021: update to dyncall 1.2 (only version bump) |
54
918dab7a6606
- added callback support (comes with some bigger refactoring)
Tassilo Philipp
parents:
52
diff
changeset
|
19 Feb 2, 2021: added callback support (comes with some bigger refactoring); |
918dab7a6606
- added callback support (comes with some bigger refactoring)
Tassilo Philipp
parents:
52
diff
changeset
|
20 allow CPython's Py{CObject,Capsule} to be used as 'p'ointers |
5 | 21 |
0 | 22 |
7 | 23 BUILD/INSTALLATION |
16
a40084782546
- added support for more return values to python binding
cslag
parents:
10
diff
changeset
|
24 ================== |
4 | 25 |
26 1) make sure dyncall is built and libraries/headers are in include paths or | |
27 CFLAGS points to them, etc. | |
28 | |
10 | 29 2) Build and install this extension with: |
16
a40084782546
- added support for more return values to python binding
cslag
parents:
10
diff
changeset
|
30 |
a40084782546
- added support for more return values to python binding
cslag
parents:
10
diff
changeset
|
31 python setup.py install |
a40084782546
- added support for more return values to python binding
cslag
parents:
10
diff
changeset
|
32 |
28 | 33 Building a wheel package isn't supported, currently. |
4 | 34 |
35 | |
0 | 36 API |
16
a40084782546
- added support for more return values to python binding
cslag
parents:
10
diff
changeset
|
37 === |
0 | 38 |
54
918dab7a6606
- added callback support (comes with some bigger refactoring)
Tassilo Philipp
parents:
52
diff
changeset
|
39 In a nutshell for all calls: |
46
c21d1c2c84e1
- removed pydc.py wrapper overhead (which only called pydcext.so functions, directly, anyways)
Tassilo Philipp
parents:
44
diff
changeset
|
40 |
37 | 41 libhandle = load(libpath) # if path == None => handle to running process |
42 libpath = get_path(libhandle) # if handle == None => path to executable | |
54
918dab7a6606
- added callback support (comes with some bigger refactoring)
Tassilo Philipp
parents:
52
diff
changeset
|
43 funcptr = find(libhandle, symbolname) # lookup symbol by name |
918dab7a6606
- added callback support (comes with some bigger refactoring)
Tassilo Philipp
parents:
52
diff
changeset
|
44 call(funcptr, signature, ...) # call C func w/ signature and corresponding args |
918dab7a6606
- added callback support (comes with some bigger refactoring)
Tassilo Philipp
parents:
52
diff
changeset
|
45 free(libhandle) # free library |
918dab7a6606
- added callback support (comes with some bigger refactoring)
Tassilo Philipp
parents:
52
diff
changeset
|
46 |
918dab7a6606
- added callback support (comes with some bigger refactoring)
Tassilo Philipp
parents:
52
diff
changeset
|
47 For callback objects to be passed as 'p'ointer args: |
918dab7a6606
- added callback support (comes with some bigger refactoring)
Tassilo Philipp
parents:
52
diff
changeset
|
48 |
918dab7a6606
- added callback support (comes with some bigger refactoring)
Tassilo Philipp
parents:
52
diff
changeset
|
49 cbhandle = new_callback(signature, pyfunc) # signature reflecting C func ptr |
918dab7a6606
- added callback support (comes with some bigger refactoring)
Tassilo Philipp
parents:
52
diff
changeset
|
50 free_callback(cbhandle) # release callback object |
0 | 51 |
46
c21d1c2c84e1
- removed pydc.py wrapper overhead (which only called pydcext.so functions, directly, anyways)
Tassilo Philipp
parents:
44
diff
changeset
|
52 Notes: |
c21d1c2c84e1
- removed pydc.py wrapper overhead (which only called pydcext.so functions, directly, anyways)
Tassilo Philipp
parents:
44
diff
changeset
|
53 - 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
|
54 - 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
|
55 set using the signature |
c21d1c2c84e1
- removed pydc.py wrapper overhead (which only called pydcext.so functions, directly, anyways)
Tassilo Philipp
parents:
44
diff
changeset
|
56 - 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
|
57 platform's default one |
37 | 58 |
7 | 59 |
0 | 60 SIGNATURE FORMAT |
16
a40084782546
- added support for more return values to python binding
cslag
parents:
10
diff
changeset
|
61 ================ |
0 | 62 |
35
75fe1dec0eb4
- added support for signature-based calling convention switch
Tassilo Philipp
parents:
34
diff
changeset
|
63 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
|
64 a string with the following format (using * as regex-like repetition): |
0 | 65 |
35
75fe1dec0eb4
- added support for signature-based calling convention switch
Tassilo Philipp
parents:
34
diff
changeset
|
66 "x*)y" |
0 | 67 |
35
75fe1dec0eb4
- added support for signature-based calling convention switch
Tassilo Philipp
parents:
34
diff
changeset
|
68 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
|
69 |
0 | 70 |
34 | 71 SIG | FROM PYTHON 2 | FROM PYTHON 3 | C/C++ | TO PYTHON 2 | TO PYTHON 3 |
72 ----+---------------------------------+---------------------------------+---------------------------------+--------------------------------------+--------------------------------------- | |
73 'v' | | | void | None (Py_None) (e.g. ret of "...)v") | None (Py_None) (e.g. ret of "...)v") | |
74 'B' | bool (PyBool) | bool (PyBool) # | int/bool | bool (PyBool) | bool (PyBool) @ | |
75 'c' | int (PyInt) % | int (PyLong) % | char | int (PyInt) | int (PyLong) | |
76 | str (with only a single char) % | str (with only a single char) % | char | int (PyInt) | int (PyLong) | |
77 'C' | int (PyInt) % | int (PyLong) % | unsigned char | int (PyInt) | int (PyLong) | |
78 | str (with only a single char) % | str (with only a single char) % | unsigned char | int (PyInt) | int (PyLong) | |
79 's' | int (PyInt) % | int (PyLong) % | short | int (PyInt) | int (PyLong) | |
80 'S' | int (PyInt) % | int (PyLong) % | unsigned short | int (PyInt) | int (PyLong) | |
81 'i' | int (PyInt) | int (PyLong) | int | int (PyInt) | int (PyLong) | |
82 'I' | int (PyInt) | int (PyLong) | unsigned int | int (PyInt) | int (PyLong) | |
83 'j' | int (PyInt) | int (PyLong) | long | int (PyInt) | int (PyLong) | |
84 'J' | int (PyInt) | int (PyLong) | unsigned long | int (PyInt) | int (PyLong) | |
85 'l' | int (PyInt) | int (PyLongLong) | long long | long (PyLong) | int (PyLong) | |
86 | long (PyLong) | - | long long | long (PyLong) | int (PyLong) | |
87 'L' | int (PyInt) | int (PyLongLong) | unsigned long long | long (PyLong) | int (PyLong) | |
88 | long (PyLong) | - | unsigned long long | long (PyLong) | int (PyLong) | |
89 'f' | float (PyFloat) $ | float (PyFloat) $ | float | float (PyFloat) ^ | float (PyFloat) ^ | |
90 'd' | float (PyFloat) | float (PyFloat) | double | float (PyFloat) | float (PyFloat) | |
91 'p' | bytearray (PyByteArray) & | bytearray (PyByteArray) & | void* | int,long (Py_ssize_t) | int (Py_ssize_t) | |
92 | int (PyInt) | int (PyLong) | void* | int,long (Py_ssize_t) | int (Py_ssize_t) | |
93 | 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
|
94 | None (Py_None) | None (Py_None) | void* (always NULL) | int,long (Py_ssize_t) | int (Py_ssize_t) |
54
918dab7a6606
- added callback support (comes with some bigger refactoring)
Tassilo Philipp
parents:
52
diff
changeset
|
95 | (PyCObject,PyCapsule) | (PyCObject,PyCapsule) | void* | int,long (Py_ssize_t) | int (Py_ssize_t) @@@ test |
52 | 96 'Z' | str (PyString) ! | str (PyUnicode) ! | const char* (UTF-8 for unicode) | str (PyString) | str (PyUnicode) |
97 | unicode (PyUnicode) ! | - | const char* (UTF-8 for unicode) | str (PyString) | str (PyUnicode) | |
98 | - | bytes (PyBytes) ! | const char* (UTF-8 for unicode) | str (PyString) | str (PyUnicode) | |
99 | bytearray (PyByteArray) ! | bytearray (PyByteArray) ! | const char* (UTF-8 for unicode) | str (PyString) | str (PyUnicode) | |
0 | 100 |
37 | 101 Annotations: |
35
75fe1dec0eb4
- added support for signature-based calling convention switch
Tassilo Philipp
parents:
34
diff
changeset
|
102 # converted to 1 if True and 0 otherwise |
75fe1dec0eb4
- added support for signature-based calling convention switch
Tassilo Philipp
parents:
34
diff
changeset
|
103 @ converted to False if 0 and True otherwise |
75fe1dec0eb4
- added support for signature-based calling convention switch
Tassilo Philipp
parents:
34
diff
changeset
|
104 % range/length checked |
75fe1dec0eb4
- added support for signature-based calling convention switch
Tassilo Philipp
parents:
34
diff
changeset
|
105 $ cast to single precision |
75fe1dec0eb4
- added support for signature-based calling convention switch
Tassilo Philipp
parents:
34
diff
changeset
|
106 ^ cast to double precision |
75fe1dec0eb4
- added support for signature-based calling convention switch
Tassilo Philipp
parents:
34
diff
changeset
|
107 & mutable buffer when passed to C |
54
918dab7a6606
- added callback support (comes with some bigger refactoring)
Tassilo Philipp
parents:
52
diff
changeset
|
108 ! 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 |
35
75fe1dec0eb4
- added support for signature-based calling convention switch
Tassilo Philipp
parents:
34
diff
changeset
|
109 |
75fe1dec0eb4
- added support for signature-based calling convention switch
Tassilo Philipp
parents:
34
diff
changeset
|
110 |
37 | 111 Also supported are specifying calling convention switches using '_'-prefixed |
112 signature characters: | |
113 | |
114 SIG | DESCRIPTION | |
115 ----+----------------------------------------------------------------------------------------------------------- | |
116 '_' | prefix indicating that next signature character specifies calling convention; char is one of the following | |
117 ':' | platform's default calling convention | |
118 'e' | vararg function | |
119 '.' | vararg function's variadic/ellipsis part (...), to be specified before first vararg | |
120 'c' | only on x86: cdecl | |
121 's' | only on x86: stdcall | |
122 'F' | only on x86: fastcall (MS) | |
123 'f' | only on x86: fastcall (GNU) | |
124 '+' | only on x86: thiscall (MS) | |
125 '#' | only on x86: thiscall (GNU) | |
126 'A' | only on ARM: ARM mode | |
127 'a' | only on ARM: THUMB mode | |
128 '$' | syscall | |
35
75fe1dec0eb4
- added support for signature-based calling convention switch
Tassilo Philipp
parents:
34
diff
changeset
|
129 |
16
a40084782546
- added support for more return values to python binding
cslag
parents:
10
diff
changeset
|
130 |
a40084782546
- added support for more return values to python binding
cslag
parents:
10
diff
changeset
|
131 TODO |
a40084782546
- added support for more return values to python binding
cslag
parents:
10
diff
changeset
|
132 ==== |
a40084782546
- added support for more return values to python binding
cslag
parents:
10
diff
changeset
|
133 |
54
918dab7a6606
- added callback support (comes with some bigger refactoring)
Tassilo Philipp
parents:
52
diff
changeset
|
134 - calling convention mode handling for callbacks (not sure if ever needed?) |
50
edf5c85de5ac
put pyi next to so for mypy to pick it up, directly
Tassilo Philipp
parents:
46
diff
changeset
|
135 - pydoc "man page" |
edf5c85de5ac
put pyi next to so for mypy to pick it up, directly
Tassilo Philipp
parents:
46
diff
changeset
|
136 - stub location: the pydc-stubs folder isn't picked up by mypy, so I question why this is the suggested way |
edf5c85de5ac
put pyi next to so for mypy to pick it up, directly
Tassilo Philipp
parents:
46
diff
changeset
|
137 - get into freebsd ports |
59 | 138 - releasing GIL when calling into C code (*only* when none of the arguments is a mutable buffer, though) |
5 | 139 |
35
75fe1dec0eb4
- added support for signature-based calling convention switch
Tassilo Philipp
parents:
34
diff
changeset
|
140 |
30 | 141 BUGS |
142 ==== | |
143 | |
144 - when using Python 2, the dyncall call vm object is never dcFree'd, as there | |
145 is no way to call a "freefunc" as introduced with Python 3 module definitions | |
146 (see PEP 3121 for details) | |
147 |