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

Last change on this file since 26328 was 26328, checked in by Ivan Raikov, 8 years ago

pyffi version history update

File size: 6.5 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])</macro>
115
116Defines an accessor for the Python method {{NAME}}. The optional
117argument {{SCHEME-NAME}} is an alternate name for the Scheme
118procedure. The accessor is a procedure of the form {{LAMBDA OBJ ARG1
119...}} that takes in a Python object {{OBJ}} and invokes the method
120{{NAME}} contained in that object, with the supplied arguments, which
121must be either Scheme values of types listed in the type conversion
122table above, or pointers to Python values. If the object has no such
123method, #f is returned.
124
125
126
127== Examples
128
129
130 ;;
131 ;; Python-UNO example from pyffi.lisp by Dmitri Hrapof.
132 ;;
133 ;; Before running the following code, you must make sure OpenOffice is
134 ;; running as a server:
135 ;;
136 ;;  soffice "-accept=socket,host=localhost,port=2002;urp;"
137 ;;
138 (require-extension pyffi)
139 
140 (py-start)
141 
142 (py-import "uno")
143 
144 (define-pyfun "uno.getComponentContext")
145 
146 (define-pyslot "ServiceManager")
147 (define-pyslot "Text")
148 
149 ;; Can't yet find out appropriate class, the following is lame
150 (define-pymethod "createInstanceWithContext")
151 (define-pymethod "resolve")
152 (define-pymethod "getCurrentComponent")
153 (define-pymethod "createTextCursor")
154 (define-pymethod "insertString")
155 
156 (define (message-uno str)
157   (let* ((lc (uno.getComponentContext))
158         (resolver (createInstanceWithContext
159                    (ServiceManager lc)
160                    "com.sun.star.bridge.UnoUrlResolver" lc))
161         (ctx (resolve resolver "uno:socket,host=localhost,port=2002;urp;StarOffice.ComponentContext"))
162         (desktop (createInstanceWithContext
163                   (ServiceManager ctx)
164                   "com.sun.star.frame.Desktop" ctx))
165         (model   (getCurrentComponent desktop))
166         (text    (Text model))
167         (cursor  (createTextCursor text)))
168     (insertString text cursor str 0)))
169 
170 
171 (message-uno "Hello, world!")
172 
173
174== About this egg
175
176
177=== Author
178
179[[/users/ivan-raikov|Ivan Raikov]]
180
181=== Version history
182
183; 3.0 :  using [[bind]] instead of [[easyffi]]
184; 2.18 : setup script updated for Python 2.7 (thanks to Mario Domenech Goulart)
185; 2.17 : Documentation converted to wiki format
186; 2.16 : setup script updated for Python 2.6
187; 2.15 : Changed getattr to not convert return result to Scheme value
188; 2.14 : Eliminated dependency on matchable
189; 2.13 : More fixes in converting Python values to Scheme
190; 2.12 : Fixes in converting Python values to Scheme
191; 2.11 : Ported to Chicken 4
192
193=== License
194
195
196 Copyright 2007-2012 Ivan Raikov. Based on pyffi.lisp by Dmitri Hrapof.
197 
198 This program is free software: you can redistribute it and/or modify
199 it under the terms of the GNU General Public License as published by
200 the Free Software Foundation, either version 3 of the License, or (at
201 your option) any later version.
202 
203 This program is distributed in the hope that it will be useful, but
204 WITHOUT ANY WARRANTY; without even the implied warranty of
205 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
206 General Public License for more details.
207 
208 A full copy of the GPL license can be found at
209 <http://www.gnu.org/licenses/>.
210
Note: See TracBrowser for help on using the repository browser.