source: project/wiki/eggref/4/pyffi @ 33407

Last change on this file since 33407 was 33407, checked in by Ivan Raikov, 3 years ago

updated pyffi doc

File size: 7.3 KB
Line 
1[[tags:egg]]
2
3== pyffi
4
5An interface to the Python programming language.
6
7[[toc:]]
8
9== Usage
10
11(require-extension pyffi)
12
13== Documentation
14
15
16The {{pyffi}} extension uses the [[http://www.python.org|Python]] C
17interface to invoke Python procedures and methods from within Scheme
18and to convert data objects between their Python and Scheme
19representation.
20
21Currently, {{pyffi}} supports the Python data types listed in the
22table below. All other Python data types are represented as pointers.
23
24<table class="symbol-table"><tr><td>int, float</td><td>numeric types, converted to and from the corresponding Scheme numeric values.</td></tr>
25<tr><td>list</td><td>list type, converted to and from Scheme list value</td></tr>
26<tr><td>str</td><td>string type, converted to and from Scheme string value</td></tr>
27<tr><td>unicode</td><td>Unicode string type, converted to and from Scheme [[utf8]] string</td></tr>
28<tr><td>dict</td><td>dictionary type, converted to and from Scheme alist value</td></tr>
29<tr><td>instance</td><td>class instance type, converted to Scheme alist value</td></tr>
30<tr><td>tuple</td><td>tuple type, converted to and from Scheme vector value</td></tr>
31</table>
32
33
34=== Installation
35
36The setup script of {{pyffi}} attempts to autodetect the location of
37the Python header files and libraries for Python versions 2.3-2.7. The
38autodetection routine checks some standard installation locations for
39Linux, Mac OS X, and Windows. If autodetection fails, you may also
40specify the header and library locations as follows:
41
42 PYTHON_CFLAGS=-I/usr/include/python2.6 PYTHON_LFLAGS=-L/usr/lib PYTHON_LIBS=-lpython2.6 chicken-install pyffi
43
44
45=== Procedures
46
47
48<procedure>(py-start)</procedure>
49
50Initializes the Python interpreter, and creates an evaluation
51environment. This procedure must be called before all other procedures
52in the extension.
53
54
55
56<procedure>(py-stop)</procedure>
57
58Deallocates the memory reserved by the Python interpreter, and frees
59all internal structures of the extension.
60
61
62
63<procedure>(py-import name)</procedure>
64
65Imports Python module {{NAME}}. If the import was unsuccessful, raises
66an exception of type {{'pyerror}}.
67
68
69
70<procedure>(py-eval expr)</procedure>
71
72Evaluates the Python expression contained in the string {{EXPR}} and
73returns the resulting value, either converted to Scheme
74representation, or as a pointer to a Python value.
75
76
77
78<procedure>(py-apply func arg1 ...)</procedure>
79
80Applies the given arguments to the Python object {{FUNC}} and returns
81the resulting value, either converted to Scheme representation, or as
82a pointer to a Python value. The arguments must be either Scheme
83values of types listed in the type conversion table above, or pointers
84to Python values.
85
86
87
88=== Macros
89
90
91<macro>(define-pyfun expr arg1 ...)</macro>
92
93Defines a Scheme procedure named when called, invokes the Python
94procedure of the same name. {{EXPR}} is either a string that contains
95the procedure name, or a pair of the form {{(FORM . NAME)}} where
96{{FORM}} is a Python expression that when evaluated returns a Python
97procedure, and {{NAME}} is a string that contains the name of the
98Scheme procedure. The arguments must be all symbols.
99
100
101
102<macro>(define-pyslot NAME [SCHEME-NAME])</macro>
103
104Defines an accessor/modifier for the Python object attribute
105{{NAME}}. The optional argument {{SCHEME-NAME}} is an alternate name
106for the Scheme procedure. The returned procedure takes in a Python
107object and returns the value of attribute {{NAME}} contained in that
108object. If the object has no such attribute, #f is returned. If a
109value is supplied after the name of the object, the procedure acts as
110a modifier for that slot.
111
112
113
114<macro>(define-pymethod NAME [SCHEME-NAME: NAME] [KW: NAME-LIST])</macro>
115
116Defines an accessor for the Python method {{NAME}}. The optional
117keyword argument {{SCHEME-NAME}} is an alternate name for the Scheme
118procedure. The optional keyword argument {{KW}} is a list of keyword
119argument names for the Python method. The accessor is a procedure of
120the form {{LAMBDA OBJ ARG1 ...}} that takes in a Python object {{OBJ}}
121and invokes the method {{NAME}} contained in that object, with the
122supplied arguments, which must be either Scheme values of types listed
123in the type conversion table above, or pointers to Python values. If
124the object has no such method, #f is returned.
125
126
127
128== Examples
129
130<enscript highlight="scheme">
131(import chicken)
132(require-extension pyffi)
133
134(py-start)
135
136(py-import "h5py")
137(py-import "numpy")
138
139
140(define-pyfun "h5py.File" name mode)
141(define-pymethod "close") ;; File
142(define-pymethod "create_dataset" kw: (dtype)) ;; File
143
144(define-pyslot "shape")
145(define-pyslot "dtype")
146(define-pyslot "name")
147
148(define f (h5py.File "mytestfile.hdf5" "w"))
149
150(define dset (create_dataset f "mydataset"  (vector 100) dtype: "i"))
151
152(print (py-object-from (name dset)))
153(print (py-object-from (shape dset)))
154(print (py-object-type (dtype dset)))
155
156(close f)
157</enscript>
158
159<enscript highlight="scheme">
160 ;;
161 ;; Python-UNO example from pyffi.lisp by Dmitri Hrapof.
162 ;;
163 ;; Before running the following code, you must make sure OpenOffice is
164 ;; running as a server:
165 ;;
166 ;;  soffice "-accept=socket,host=localhost,port=2002;urp;"
167 ;;
168 (require-extension pyffi)
169 
170 (py-start)
171 
172 (py-import "uno")
173 
174 (define-pyfun "uno.getComponentContext")
175 
176 (define-pyslot "ServiceManager")
177 (define-pyslot "Text")
178 
179 ;; Can't yet find out appropriate class, the following is lame
180 (define-pymethod "createInstanceWithContext")
181 (define-pymethod "resolve")
182 (define-pymethod "getCurrentComponent")
183 (define-pymethod "createTextCursor")
184 (define-pymethod "insertString")
185 
186 (define (message-uno str)
187   (let* ((lc (uno.getComponentContext))
188         (resolver (createInstanceWithContext
189                    (ServiceManager lc)
190                    "com.sun.star.bridge.UnoUrlResolver" lc))
191         (ctx (resolve resolver "uno:socket,host=localhost,port=2002;urp;StarOffice.ComponentContext"))
192         (desktop (createInstanceWithContext
193                   (ServiceManager ctx)
194                   "com.sun.star.frame.Desktop" ctx))
195         (model   (getCurrentComponent desktop))
196         (text    (Text model))
197         (cursor  (createTextCursor text)))
198     (insertString text cursor str 0)))
199 
200 
201 (message-uno "Hello, world!")
202</enscript>
203
204== About this egg
205
206
207=== Author
208
209[[/users/ivan-raikov|Ivan Raikov]]
210
211=== Version history
212
213; 3.3 :  added support for keyword arguments in method definitions
214; 3.0 :  using [[bind]] instead of [[easyffi]]
215; 2.18 : setup script updated for Python 2.7 (thanks to Mario Domenech Goulart)
216; 2.17 : Documentation converted to wiki format
217; 2.16 : setup script updated for Python 2.6
218; 2.15 : Changed getattr to not convert return result to Scheme value
219; 2.14 : Eliminated dependency on matchable
220; 2.13 : More fixes in converting Python values to Scheme
221; 2.12 : Fixes in converting Python values to Scheme
222; 2.11 : Ported to Chicken 4
223
224=== License
225
226
227 Copyright 2007-2016 Ivan Raikov. Based on pyffi.lisp by Dmitri Hrapof.
228 
229 This program is free software: you can redistribute it and/or modify
230 it under the terms of the GNU General Public License as published by
231 the Free Software Foundation, either version 3 of the License, or (at
232 your option) any later version.
233 
234 This program is distributed in the hope that it will be useful, but
235 WITHOUT ANY WARRANTY; without even the implied warranty of
236 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
237 General Public License for more details.
238 
239 A full copy of the GPL license can be found at
240 <http://www.gnu.org/licenses/>.
241
Note: See TracBrowser for help on using the repository browser.