Mercurial > pub > dyncall > bindings

annotate python/pydc/README.txt @ 55:2e8a56976bf8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
fixed missing () making branch always be entered
author Tassilo Philipp
date Tue, 02 Feb 2021 20:56:54 +0100
parents 918dab7a6606
children 80b11152c659
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
edbbd467f50a python binding:
Tassilo Philipp
parents: 24
diff changeset
3 2018-2020 Tassilo Philipp
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
54
918dab7a6606 - added callback support (comes with some bigger refactoring)
Tassilo Philipp
parents: 52
diff changeset
18 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
19 allow CPython's Py{CObject,Capsule} to be used as 'p'ointers
5
bf5625bb6f05 - brought python binding up to dc v0.9
cslag
parents: 4
diff changeset
20
0
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
21
7
4fd959b3df78 - python binding readme clarifications
cslag
parents: 5
diff changeset
22 BUILD/INSTALLATION
16
a40084782546 - added support for more return values to python binding
cslag
parents: 10
diff changeset
23 ==================
4
4c5019f00f5b - python binding cleanup
cslag
parents: 0
diff changeset
24
4c5019f00f5b - python binding cleanup
cslag
parents: 0
diff changeset
25 1) make sure dyncall is built and libraries/headers are in include paths or
4c5019f00f5b - python binding cleanup
cslag
parents: 0
diff changeset
26 CFLAGS points to them, etc.
4c5019f00f5b - python binding cleanup
cslag
parents: 0
diff changeset
27
10
6493c9ed4b33 - ruby and python binding readme updates
cslag
parents: 7
diff changeset
28 2) Build and install this extension with:
16
a40084782546 - added support for more return values to python binding
cslag
parents: 10
diff changeset
29
a40084782546 - added support for more return values to python binding
cslag
parents: 10
diff changeset
30 python setup.py install
a40084782546 - added support for more return values to python binding
cslag
parents: 10
diff changeset
31
28
edbbd467f50a python binding:
Tassilo Philipp
parents: 24
diff changeset
32 Building a wheel package isn't supported, currently.
4
4c5019f00f5b - python binding cleanup
cslag
parents: 0
diff changeset
33
4c5019f00f5b - python binding cleanup
cslag
parents: 0
diff changeset
34
0
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
35 API
16
a40084782546 - added support for more return values to python binding
cslag
parents: 10
diff changeset
36 ===
0
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
37
54
918dab7a6606 - added callback support (comes with some bigger refactoring)
Tassilo Philipp
parents: 52
diff changeset
38 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
39
37
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
40 libhandle = load(libpath) # if path == None => handle to running process
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
41 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
42 funcptr = find(libhandle, symbolname) # lookup symbol by name
918dab7a6606 - added callback support (comes with some bigger refactoring)
Tassilo Philipp
parents: 52
diff changeset
43 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
44 free(libhandle) # free library
918dab7a6606 - added callback support (comes with some bigger refactoring)
Tassilo Philipp
parents: 52
diff changeset
45
918dab7a6606 - added callback support (comes with some bigger refactoring)
Tassilo Philipp
parents: 52
diff changeset
46 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
47
918dab7a6606 - added callback support (comes with some bigger refactoring)
Tassilo Philipp
parents: 52
diff changeset
48 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
49 free_callback(cbhandle) # release callback object
0
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
50
46
c21d1c2c84e1 - removed pydc.py wrapper overhead (which only called pydcext.so functions, directly, anyways)
Tassilo Philipp
parents: 44
diff changeset
51 Notes:
c21d1c2c84e1 - removed pydc.py wrapper overhead (which only called pydcext.so functions, directly, anyways)
Tassilo Philipp
parents: 44
diff changeset
52 - 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
53 - 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
54 set using the signature
c21d1c2c84e1 - removed pydc.py wrapper overhead (which only called pydcext.so functions, directly, anyways)
Tassilo Philipp
parents: 44
diff changeset
55 - 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
56 platform's default one
37
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
57
7
4fd959b3df78 - python binding readme clarifications
cslag
parents: 5
diff changeset
58
0
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
59 SIGNATURE FORMAT
16
a40084782546 - added support for more return values to python binding
cslag
parents: 10
diff changeset
60 ================
0
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
61
35
75fe1dec0eb4 - added support for signature-based calling convention switch
Tassilo Philipp
parents: 34
diff changeset
62 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
63 a string with the following format (using * as regex-like repetition):
0
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
64
35
75fe1dec0eb4 - added support for signature-based calling convention switch
Tassilo Philipp
parents: 34
diff changeset
65 "x*)y"
0
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
66
35
75fe1dec0eb4 - added support for signature-based calling convention switch
Tassilo Philipp
parents: 34
diff changeset
67 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
68
0
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
69
34
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
70 SIG | FROM PYTHON 2 | FROM PYTHON 3 | C/C++ | TO PYTHON 2 | TO PYTHON 3
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
71 ----+---------------------------------+---------------------------------+---------------------------------+--------------------------------------+---------------------------------------
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
72 '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
73 'B' | bool (PyBool) | bool (PyBool) # | int/bool | bool (PyBool) | bool (PyBool) @
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
74 'c' | int (PyInt) % | int (PyLong) % | char | int (PyInt) | int (PyLong)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
75 | 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
76 'C' | int (PyInt) % | int (PyLong) % | unsigned char | int (PyInt) | int (PyLong)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
77 | 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
78 's' | int (PyInt) % | int (PyLong) % | short | int (PyInt) | int (PyLong)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
79 'S' | int (PyInt) % | int (PyLong) % | unsigned short | int (PyInt) | int (PyLong)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
80 'i' | int (PyInt) | int (PyLong) | int | int (PyInt) | int (PyLong)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
81 'I' | int (PyInt) | int (PyLong) | unsigned int | int (PyInt) | int (PyLong)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
82 'j' | int (PyInt) | int (PyLong) | long | int (PyInt) | int (PyLong)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
83 'J' | int (PyInt) | int (PyLong) | unsigned long | int (PyInt) | int (PyLong)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
84 'l' | int (PyInt) | int (PyLongLong) | long long | long (PyLong) | int (PyLong)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
85 | long (PyLong) | - | long long | long (PyLong) | int (PyLong)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
86 'L' | int (PyInt) | int (PyLongLong) | unsigned long long | long (PyLong) | int (PyLong)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
87 | long (PyLong) | - | unsigned long long | long (PyLong) | int (PyLong)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
88 'f' | float (PyFloat) $ | float (PyFloat) $ | float | float (PyFloat) ^ | float (PyFloat) ^
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
89 'd' | float (PyFloat) | float (PyFloat) | double | float (PyFloat) | float (PyFloat)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
90 'p' | bytearray (PyByteArray) & | bytearray (PyByteArray) & | void* | int,long (Py_ssize_t) | int (Py_ssize_t)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
91 | int (PyInt) | int (PyLong) | void* | int,long (Py_ssize_t) | int (Py_ssize_t)
2682a627168c - breaking changes:
Tassilo Philipp
parents: 30
diff changeset
92 | 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
93 | 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
94 | (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
95 'Z' | str (PyString) ! | str (PyUnicode) ! | const char* (UTF-8 for unicode) | str (PyString) | str (PyUnicode)
c5ca08cd3e78 - readme typos
Tassilo Philipp
parents: 50
diff changeset
96 | unicode (PyUnicode) ! | - | const char* (UTF-8 for unicode) | str (PyString) | str (PyUnicode)
c5ca08cd3e78 - readme typos
Tassilo Philipp
parents: 50
diff changeset
97 | - | bytes (PyBytes) ! | const char* (UTF-8 for unicode) | str (PyString) | str (PyUnicode)
c5ca08cd3e78 - readme typos
Tassilo Philipp
parents: 50
diff changeset
98 | bytearray (PyByteArray) ! | bytearray (PyByteArray) ! | const char* (UTF-8 for unicode) | str (PyString) | str (PyUnicode)
0
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
99
37
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
100 Annotations:
35
75fe1dec0eb4 - added support for signature-based calling convention switch
Tassilo Philipp
parents: 34
diff changeset
101 # converted to 1 if True and 0 otherwise
75fe1dec0eb4 - added support for signature-based calling convention switch
Tassilo Philipp
parents: 34
diff changeset
102 @ converted to False if 0 and True otherwise
75fe1dec0eb4 - added support for signature-based calling convention switch
Tassilo Philipp
parents: 34
diff changeset
103 % range/length checked
75fe1dec0eb4 - added support for signature-based calling convention switch
Tassilo Philipp
parents: 34
diff changeset
104 $ cast to single precision
75fe1dec0eb4 - added support for signature-based calling convention switch
Tassilo Philipp
parents: 34
diff changeset
105 ^ cast to double precision
75fe1dec0eb4 - added support for signature-based calling convention switch
Tassilo Philipp
parents: 34
diff changeset
106 & mutable buffer when passed to C
54
918dab7a6606 - added callback support (comes with some bigger refactoring)
Tassilo Philipp
parents: 52
diff changeset
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
35
75fe1dec0eb4 - added support for signature-based calling convention switch
Tassilo Philipp
parents: 34
diff changeset
108
75fe1dec0eb4 - added support for signature-based calling convention switch
Tassilo Philipp
parents: 34
diff changeset
109
37
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
110 Also supported are specifying calling convention switches using '_'-prefixed
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
111 signature characters:
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
112
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
113 SIG | DESCRIPTION
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
114 ----+-----------------------------------------------------------------------------------------------------------
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
115 '_' | prefix indicating that next signature character specifies calling convention; char is one of the following
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
116 ':' | platform's default calling convention
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
117 'e' | vararg function
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
118 '.' | vararg function's variadic/ellipsis part (...), to be specified before first vararg
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
119 'c' | only on x86: cdecl
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
120 's' | only on x86: stdcall
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
121 'F' | only on x86: fastcall (MS)
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
122 'f' | only on x86: fastcall (GNU)
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
123 '+' | only on x86: thiscall (MS)
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
124 '#' | only on x86: thiscall (GNU)
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
125 'A' | only on ARM: ARM mode
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
126 'a' | only on ARM: THUMB mode
8c8f848131c6 - version bump
Tassilo Philipp
parents: 35
diff changeset
127 '$' | syscall
35
75fe1dec0eb4 - added support for signature-based calling convention switch
Tassilo Philipp
parents: 34
diff changeset
128
16
a40084782546 - added support for more return values to python binding
cslag
parents: 10
diff changeset
129
a40084782546 - added support for more return values to python binding
cslag
parents: 10
diff changeset
130 TODO
a40084782546 - added support for more return values to python binding
cslag
parents: 10
diff changeset
131 ====
a40084782546 - added support for more return values to python binding
cslag
parents: 10
diff changeset
132
54
918dab7a6606 - added callback support (comes with some bigger refactoring)
Tassilo Philipp
parents: 52
diff changeset
133 - 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
134 - pydoc "man page"
edf5c85de5ac put pyi next to so for mypy to pick it up, directly
Tassilo Philipp
parents: 46
diff changeset
135 - 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
136 - get into freebsd ports
5
bf5625bb6f05 - brought python binding up to dc v0.9
cslag
parents: 4
diff changeset
137
35
75fe1dec0eb4 - added support for signature-based calling convention switch
Tassilo Philipp
parents: 34
diff changeset
138
30
baf087cf5971 - fixed two ref counting problems
Tassilo Philipp
parents: 29
diff changeset
139 BUGS
baf087cf5971 - fixed two ref counting problems
Tassilo Philipp
parents: 29
diff changeset
140 ====
baf087cf5971 - fixed two ref counting problems
Tassilo Philipp
parents: 29
diff changeset
141
baf087cf5971 - fixed two ref counting problems
Tassilo Philipp
parents: 29
diff changeset
142 - 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
143 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
144 (see PEP 3121 for details)
baf087cf5971 - fixed two ref counting problems
Tassilo Philipp
parents: 29
diff changeset
145