Mercurial > pub > dyncall > bindings

annotate python/pydc/README.txt @ 66:7a61dd082341 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
pydc: - fix double free triggered by capsule destructor, when freeing pydc and callback objects, manually
author Tassilo Philipp
date Fri, 24 May 2024 18:16:29 +0200
parents c5a69c454963
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
1 dyncall python bindings
28
edbbd467f50a python binding:
Tassilo Philipp
parents: 24
diff changeset
2 Copyright 2007-2016 Daniel Adler
61
c5a69c454963 - allow use of 'None' with 'Z'
Tassilo Philipp
parents: 60
diff changeset
3 2018-2023 Tassilo Philipp
28
edbbd467f50a python binding:
Tassilo Philipp
parents: 24
diff changeset
4
edbbd467f50a python binding:
Tassilo Philipp
parents: 24
diff changeset
5 Dec 4, 2007: initial
edbbd467f50a python binding:
Tassilo Philipp
parents: 24
diff changeset
6 Mar 22, 2016: update to dyncall 0.9, includes breaking sig char changes
edbbd467f50a python binding:
Tassilo Philipp
parents: 24
diff changeset
7 Apr 19, 2018: update to dyncall 1.0
edbbd467f50a python binding:
Tassilo Philipp
parents: 24
diff changeset
8 Apr 7, 2020: update to dyncall 1.1, Python 3 support, using the Capsule
edbbd467f50a python binding:
Tassilo Philipp
parents: 24
diff changeset
9 API, as well as support for python unicode strings
34
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
10 Apr 11, 2020: support for getting loaded library path
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
11 Apr 12, 2020: breaking change: restrict 'Z' conversions to immutable types
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
12 and 'p' to mutable types (and handles)
37
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
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
80b11152c659 make pydc tests display failed ones
Tassilo Philipp
parents: 54
diff changeset
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
60
8e905c0798c7 - p2Z() helper func
Tassilo Philipp
parents: 59
diff changeset
21 Aug 3, 2022: added p2Z() helper function (e.g. helpful when working with
8e905c0798c7 - p2Z() helper func
Tassilo Philipp
parents: 59
diff changeset
22 string 'p'ointers that eventually need to be free()'d, as no
8e905c0798c7 - p2Z() helper func
Tassilo Philipp
parents: 59
diff changeset
23 implicit 'Z' conversion is taking place)
61
c5a69c454963 - allow use of 'None' with 'Z'
Tassilo Philipp
parents: 60
diff changeset
24 Apr 3, 2023: allowing 'None' for 'Z' params
c5a69c454963 - allow use of 'None' with 'Z'
Tassilo Philipp
parents: 60
diff changeset
25
c5a69c454963 - allow use of 'None' with 'Z'
Tassilo Philipp
parents: 60
diff changeset
26
5
bf5625bb6f05 - brought python binding up to dc v0.9
cslag
parents: 4
diff changeset
27
0
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
28
7
4fd959b3df78 - python binding readme clarifications
cslag
parents: 5
diff changeset
29 BUILD/INSTALLATION
16
a40084782546 - added support for more return values to python binding
cslag
parents: 10
diff changeset
30 ==================
4
4c5019f00f5b - python binding cleanup
cslag
parents: 0
diff changeset
31
4c5019f00f5b - python binding cleanup
cslag
parents: 0
diff changeset
32 1) make sure dyncall is built and libraries/headers are in include paths or
4c5019f00f5b - python binding cleanup
cslag
parents: 0
diff changeset
33 CFLAGS points to them, etc.
4c5019f00f5b - python binding cleanup
cslag
parents: 0
diff changeset
34
10
6493c9ed4b33 - ruby and python binding readme updates
cslag
parents: 7
diff changeset
35 2) Build and install this extension with:
16
a40084782546 - added support for more return values to python binding
cslag
parents: 10
diff changeset
36
a40084782546 - added support for more return values to python binding
cslag
parents: 10
diff changeset
37 python setup.py install
a40084782546 - added support for more return values to python binding
cslag
parents: 10
diff changeset
38
28
edbbd467f50a python binding:
Tassilo Philipp
parents: 24
diff changeset
39 Building a wheel package isn't supported, currently.
4
4c5019f00f5b - python binding cleanup
cslag
parents: 0
diff changeset
40
4c5019f00f5b - python binding cleanup
cslag
parents: 0
diff changeset
41
0
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
42 API
16
a40084782546 - added support for more return values to python binding
cslag
parents: 10
diff changeset
43 ===
0
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
44
54
918dab7a6606 - added callback support (comes with some bigger refactoring)
Tassilo Philipp
parents: 52
diff changeset
45 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
46
37
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
47 libhandle = load(libpath) # if path == None => handle to running process
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
48 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
49 funcptr = find(libhandle, symbolname) # lookup symbol by name
918dab7a6606 - added callback support (comes with some bigger refactoring)
Tassilo Philipp
parents: 52
diff changeset
50 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
51 free(libhandle) # free library
918dab7a6606 - added callback support (comes with some bigger refactoring)
Tassilo Philipp
parents: 52
diff changeset
52
918dab7a6606 - added callback support (comes with some bigger refactoring)
Tassilo Philipp
parents: 52
diff changeset
53 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
54
918dab7a6606 - added callback support (comes with some bigger refactoring)
Tassilo Philipp
parents: 52
diff changeset
55 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
56 free_callback(cbhandle) # release callback object
0
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
57
46
c21d1c2c84e1 - removed pydc.py wrapper overhead (which only called pydcext.so functions, directly, anyways)
Tassilo Philipp
parents: 44
diff changeset
58 Notes:
c21d1c2c84e1 - removed pydc.py wrapper overhead (which only called pydcext.so functions, directly, anyways)
Tassilo Philipp
parents: 44
diff changeset
59 - 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
60 - 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
61 set using the signature
c21d1c2c84e1 - removed pydc.py wrapper overhead (which only called pydcext.so functions, directly, anyways)
Tassilo Philipp
parents: 44
diff changeset
62 - 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
63 platform's default one
37
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
64
7
4fd959b3df78 - python binding readme clarifications
cslag
parents: 5
diff changeset
65
0
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
66 SIGNATURE FORMAT
16
a40084782546 - added support for more return values to python binding
cslag
parents: 10
diff changeset
67 ================
0
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
68
35
75fe1dec0eb4 - added support for signature-based calling convention switch
Tassilo Philipp
parents: 34
diff changeset
69 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
70 a string with the following format (using * as regex-like repetition):
0
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
71
35
75fe1dec0eb4 - added support for signature-based calling convention switch
Tassilo Philipp
parents: 34
diff changeset
72 "x*)y"
0
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
73
35
75fe1dec0eb4 - added support for signature-based calling convention switch
Tassilo Philipp
parents: 34
diff changeset
74 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
75
0
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
76
34
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
77 SIG | FROM PYTHON 2 | FROM PYTHON 3 | C/C++ | TO PYTHON 2 | TO PYTHON 3
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
78 ----+---------------------------------+---------------------------------+---------------------------------+--------------------------------------+---------------------------------------
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
79 'v' | | | void | None (Py_None) (e.g. ret of "...)v") | None (Py_None) (e.g. ret of "...)v")
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
80 'B' | bool (PyBool) | bool (PyBool) # | int/bool | bool (PyBool) | bool (PyBool) @
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
81 'c' | int (PyInt) % | int (PyLong) % | char | int (PyInt) | int (PyLong)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
82 | str (with only a single char) % | str (with only a single char) % | char | int (PyInt) | int (PyLong)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
83 'C' | int (PyInt) % | int (PyLong) % | unsigned char | int (PyInt) | int (PyLong)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
84 | str (with only a single char) % | str (with only a single char) % | unsigned char | int (PyInt) | int (PyLong)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
85 's' | int (PyInt) % | int (PyLong) % | short | int (PyInt) | int (PyLong)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
86 'S' | int (PyInt) % | int (PyLong) % | unsigned short | int (PyInt) | int (PyLong)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
87 'i' | int (PyInt) | int (PyLong) | int | int (PyInt) | int (PyLong)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
88 'I' | int (PyInt) | int (PyLong) | unsigned int | int (PyInt) | int (PyLong)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
89 'j' | int (PyInt) | int (PyLong) | long | int (PyInt) | int (PyLong)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
90 'J' | int (PyInt) | int (PyLong) | unsigned long | int (PyInt) | int (PyLong)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
91 'l' | int (PyInt) | int (PyLongLong) | long long | long (PyLong) | int (PyLong)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
92 | long (PyLong) | - | long long | long (PyLong) | int (PyLong)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
93 'L' | int (PyInt) | int (PyLongLong) | unsigned long long | long (PyLong) | int (PyLong)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
94 | long (PyLong) | - | unsigned long long | long (PyLong) | int (PyLong)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
95 'f' | float (PyFloat) $ | float (PyFloat) $ | float | float (PyFloat) ^ | float (PyFloat) ^
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
96 'd' | float (PyFloat) | float (PyFloat) | double | float (PyFloat) | float (PyFloat)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
97 'p' | bytearray (PyByteArray) & | bytearray (PyByteArray) & | void* | int,long (Py_ssize_t) | int (Py_ssize_t)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
98 | int (PyInt) | int (PyLong) | void* | int,long (Py_ssize_t) | int (Py_ssize_t)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
99 | 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
100 | 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
101 | (PyCObject,PyCapsule) | (PyCObject,PyCapsule) | void* | int,long (Py_ssize_t) | int (Py_ssize_t) @@@ test
52
c5ca08cd3e78 - readme typos
Tassilo Philipp
parents: 50
diff changeset
102 'Z' | str (PyString) ! | str (PyUnicode) ! | const char* (UTF-8 for unicode) | str (PyString) | str (PyUnicode)
c5ca08cd3e78 - readme typos
Tassilo Philipp
parents: 50
diff changeset
103 | unicode (PyUnicode) ! | - | const char* (UTF-8 for unicode) | str (PyString) | str (PyUnicode)
c5ca08cd3e78 - readme typos
Tassilo Philipp
parents: 50
diff changeset
104 | - | bytes (PyBytes) ! | const char* (UTF-8 for unicode) | str (PyString) | str (PyUnicode)
c5ca08cd3e78 - readme typos
Tassilo Philipp
parents: 50
diff changeset
105 | bytearray (PyByteArray) ! | bytearray (PyByteArray) ! | const char* (UTF-8 for unicode) | str (PyString) | str (PyUnicode)
61
c5a69c454963 - allow use of 'None' with 'Z'
Tassilo Philipp
parents: 60
diff changeset
106 | None (Py_None) | None (Py_None) | const char* (always NULL) | None (Py_None) | None (Py_None)
0
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
107
37
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
108 Annotations:
35
75fe1dec0eb4 - added support for signature-based calling convention switch
Tassilo Philipp
parents: 34
diff changeset
109 # converted to 1 if True and 0 otherwise
75fe1dec0eb4 - added support for signature-based calling convention switch
Tassilo Philipp
parents: 34
diff changeset
110 @ converted to False if 0 and True otherwise
75fe1dec0eb4 - added support for signature-based calling convention switch
Tassilo Philipp
parents: 34
diff changeset
111 % range/length checked
75fe1dec0eb4 - added support for signature-based calling convention switch
Tassilo Philipp
parents: 34
diff changeset
112 $ cast to single precision
75fe1dec0eb4 - added support for signature-based calling convention switch
Tassilo Philipp
parents: 34
diff changeset
113 ^ cast to double precision
75fe1dec0eb4 - added support for signature-based calling convention switch
Tassilo Philipp
parents: 34
diff changeset
114 & mutable buffer when passed to C
54
918dab7a6606 - added callback support (comes with some bigger refactoring)
Tassilo Philipp
parents: 52
diff changeset
115 ! 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
116
75fe1dec0eb4 - added support for signature-based calling convention switch
Tassilo Philipp
parents: 34
diff changeset
117
37
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
118 Also supported are specifying calling convention switches using '_'-prefixed
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
119 signature characters:
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
120
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
121 SIG | DESCRIPTION
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
122 ----+-----------------------------------------------------------------------------------------------------------
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
123 '_' | prefix indicating that next signature character specifies calling convention; char is one of the following
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
124 ':' | platform's default calling convention
60
8e905c0798c7 - p2Z() helper func
Tassilo Philipp
parents: 59
diff changeset
125 '*' | platform's default thiscall (C++ methods) calling convention, first argument of a call is the this pointer
37
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
126 'e' | vararg function
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
127 '.' | vararg function's variadic/ellipsis part (...), to be specified before first vararg
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
128 'c' | only on x86: cdecl
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
129 's' | only on x86: stdcall
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
130 'F' | only on x86: fastcall (MS)
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
131 'f' | only on x86: fastcall (GNU)
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
132 '+' | only on x86: thiscall (MS)
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
133 '#' | only on x86: thiscall (GNU)
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
134 'A' | only on ARM: ARM mode
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
135 'a' | only on ARM: THUMB mode
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
136 '$' | syscall
35
75fe1dec0eb4 - added support for signature-based calling convention switch
Tassilo Philipp
parents: 34
diff changeset
137
16
a40084782546 - added support for more return values to python binding
cslag
parents: 10
diff changeset
138
a40084782546 - added support for more return values to python binding
cslag
parents: 10
diff changeset
139 TODO
a40084782546 - added support for more return values to python binding
cslag
parents: 10
diff changeset
140 ====
a40084782546 - added support for more return values to python binding
cslag
parents: 10
diff changeset
141
54
918dab7a6606 - added callback support (comes with some bigger refactoring)
Tassilo Philipp
parents: 52
diff changeset
142 - 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
143 - pydoc "man page"
edf5c85de5ac put pyi next to so for mypy to pick it up, directly
Tassilo Philipp
parents: 46
diff changeset
144 - 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
145 - get into freebsd ports
59
2725de59454a - fixed potentially uninitialized ptr
Tassilo Philipp
parents: 57
diff changeset
146 - releasing GIL when calling into C code (*only* when none of the arguments is a mutable buffer, though)
60
8e905c0798c7 - p2Z() helper func
Tassilo Philipp
parents: 59
diff changeset
147 - support for new dyncall aggregate-by-value interface
5
bf5625bb6f05 - brought python binding up to dc v0.9
cslag
parents: 4
diff changeset
148
35
75fe1dec0eb4 - added support for signature-based calling convention switch
Tassilo Philipp
parents: 34
diff changeset
149
30
baf087cf5971 - fixed two ref counting problems
Tassilo Philipp
parents: 29
diff changeset
150 BUGS
baf087cf5971 - fixed two ref counting problems
Tassilo Philipp
parents: 29
diff changeset
151 ====
baf087cf5971 - fixed two ref counting problems
Tassilo Philipp
parents: 29
diff changeset
152
baf087cf5971 - fixed two ref counting problems
Tassilo Philipp
parents: 29
diff changeset
153 - when using Python 2, the dyncall call vm object is never dcFree'd, as there
baf087cf5971 - fixed two ref counting problems
Tassilo Philipp
parents: 29
diff changeset
154 is no way to call a "freefunc" as introduced with Python 3 module definitions
baf087cf5971 - fixed two ref counting problems
Tassilo Philipp
parents: 29
diff changeset
155 (see PEP 3121 for details)
baf087cf5971 - fixed two ref counting problems
Tassilo Philipp
parents: 29
diff changeset
156