]> git.saurik.com Git - wxWidgets.git/blob - wxPython/SWIG/swig.python-2.patch
Some change notes
[wxWidgets.git] / wxPython / SWIG / swig.python-2.patch
1 Index: Doc/Manual/Python.html
2 ===================================================================
3 RCS file: /cvsroot/swig/SWIG/Doc/Manual/Python.html,v
4 retrieving revision 1.18
5 diff -u -4 -r1.18 Python.html
6 --- Doc/Manual/Python.html 2 Sep 2004 20:27:14 -0000 1.18
7 +++ Doc/Manual/Python.html 6 Sep 2004 21:06:11 -0000
8 @@ -86,8 +86,15 @@
9 <li><a href="#Python_nn62">Mapping Python tuples into small arrays</a>
10 <li><a href="#Python_nn63">Mapping sequences to C arrays</a>
11 <li><a href="#Python_nn64">Pointer handling</a>
12 </ul>
13 +<li><a href="#Python_nn65">Docstring Features</a>
14 +<ul>
15 +<li><a href="#Python_nn66">Module docstring</a>
16 +<li><a href="#Python_nn67">%feature("autodoc")</a>
17 +<li><a href="#Python_nn68">%feature("docstring")</a>
18 +</ul>
19 +<li><a href="#Python_nn70">Python Packages</a>
20 </ul>
21 <!-- INDEX -->
22
23
24 @@ -2460,9 +2467,8 @@
25 customization features as covered in later sections.
26
27 <H3><a name="Python_nn42"></a>26.6.2 Adding additional Python code</H3>
28
29 -
30 If writing support code in C isn't enough, it is also possible to write code in
31 Python. This code gets inserted in to the <tt>.py</tt> file created by SWIG. One
32 use of Python code might be to supply a high-level interface to certain functions.
33 For example:
34 @@ -2506,8 +2512,46 @@
35 soon enough. For now, think of this example as an illustration of
36 what can be done without having to rely on any of the more advanced
37 customization features.
38
39 +<p>Sometimes you may want to replace or modify the wrapper function
40 +that SWIG creates in the proxy <tt>.py</tt> file. The Python module
41 +in SWIG provides some features that enable you do do this. First, to
42 +entirely replace a proxy function you can use
43 +<tt>%feature("shadow")</tt>. For example:
44 +
45 +<blockquote>
46 +<pre>
47 +%module example
48 +%rename(bar_id) bar(int,double);
49 +
50 +// Rewrite bar() to allow some nice overloading
51 +
52 +%feature("shadow") Foo::bar(int) %{
53 +def bar(*args):
54 + if len(args) == 3:
55 + return apply(examplec.Foo_bar_id,args)
56 + return apply(examplec.Foo_bar,args)
57 +%}
58 +
59 +class Foo {
60 +public:
61 + int bar(int x);
62 + int bar(int x, double y);
63 +}
64 +</pre>
65 +</blockquote>
66 +
67 +
68 +Often the proxy function created by SWIG is fine, but you simply want
69 +to add code to it without touching the rest of the generated function
70 +body. For these cases SWIG provides the "pythonprepend" and
71 +"pythonappend" features which do exactly as their names suggest. The
72 +"pythonprepend" feature will insert its value at the begining of the
73 +proxy function, and "pythonappend" will insert code at the end of the
74 +proxy, just before the return statement.
75 +
76 +
77 <H3><a name="Python_nn43"></a>26.6.3 Class extension with %extend</H3>
78
79
80 One of the more interesting features of SWIG is that it can extend
81 @@ -3852,6 +3896,197 @@
82 that has a <tt>this</tt> attribute. In addition,
83 <tt>SWIG_NewPointerObj()</tt> can automatically generate a proxy
84 class object (if applicable).
85
86 +
87 +
88 +<H2><a name="Python_nn65"></a>26.10 Docstring Features</H2>
89 +
90 +Usign docstrings in Python code is becoming more and more important
91 +ans more tools are coming on the scene that take advantage of them,
92 +everything from full-blown documentaiton generators to class browsers
93 +and popup call-tips in Python-aware IDEs. Given the way that SWIG
94 +generates the proxy code by default, your users will normally get
95 +something like <tt>"function_name(*args)"</tt> in the popup calltip of
96 +their IDE which is next to useless when the real function prototype
97 +might be something like this:
98 +
99 +<blockquote>
100 +<pre>
101 +bool function_name(int x, int y, Foo* foo=NULL, Bar* bar=NULL);
102 +</pre>
103 +</blockquote>
104 +
105 +The features described in this section make it easy for you to add
106 +docstrings to your modules, functions and methods that can then be
107 +used by the various tools out there to make the programming experience
108 +of your users much simpler.
109 +
110 +
111 +<H3><a name="Python_nn66"></a>26.10.1 Module docstring</H3>
112 +
113 +Python allows a docstring at the begining of the <tt>.py</tt> file
114 +before any other statements, and it is typically used to give a
115 +general description of the entire module. SWIG supports this by
116 +setting an option of the <tt>%module</tt> directive. For example:
117 +
118 +<blockquote>
119 +<pre>
120 +%module(docstring="This is the example module's docstring") example
121 +</pre>
122 +</blockquote>
123 +
124 +When you have more than just a line or so then you can retain the easy
125 +readability of the <tt>%module</tt> directive by using a macro. For
126 +example:
127 +
128 +<blockquote>
129 +<pre>
130 +%define DOCSTRING
131 +"The `XmlResource` class allows program resources defining menus,
132 +layout of controls on a panel, etc. to be loaded from an XML file."
133 +%enddef
134 +
135 +%module(docstring=DOCSTRING) xrc
136 +</pre>
137 +</blockquote>
138 +
139 +
140 +<H3><a name="Python_nn67"></a>26.10.2 %feature("autodoc")</H3>
141 +
142 +As alluded to above SWIG will generate all the function and method
143 +proxy wrappers with just "*args" (or "*args, **kwargs" if the -keyword
144 +option is used) for a parameter list and will then sort out the
145 +individual parameters in the C wrapper code. This is nice and simple
146 +for the wrapper code, but makes it difficult to be programmer and tool
147 +friendly as anyone looking at the <tt>.py</tt> file will not be able
148 +to find out anything about the parameters that the fuctions accept.
149 +
150 +<p>But since SWIG does know everything about the fucntion it is
151 +possible to generate a docstring containing the parameter types, names
152 +and default values. Since many of the doctring tools are adopting a
153 +standard of recognizing if the first thing in the docstring is a
154 +function prototype then using that instead of what they found from
155 +introspeciton, then life is good once more.
156 +
157 +<p>SWIG's Python module provides support for the "autodoc" feature,
158 +which when attached to a node in the parse tree will cause a docstring
159 +to be generated that includes the name of the funciton, parameter
160 +names, default values if any, and return type if any. There are also
161 +three options for autodoc controlled by the value given to the
162 +feature, described below.
163 +
164 +<H4>%feature("autodoc", "0")</H4>
165 +
166 +When the "0" option is given then the types of the parameters will
167 +<em>not</em> be included in the autodoc string. For example, given
168 +this function prototype:
169 +
170 +<blockquote>
171 +<pre>
172 +%feature("autodoc", "0");
173 +bool function_name(int x, int y, Foo* foo=NULL, Bar* bar=NULL);
174 +</pre>
175 +</blockquote>
176 +
177 +Then Python code like this will be generated:
178 +
179 +<blockquote>
180 +<pre>
181 +def function_name(*args, **kwargs):
182 + """function_name(x, y, foo=None, bar=None) -> bool"""
183 + ...
184 +</pre>
185 +</blockquote>
186 +
187 +
188 +<H4>%feature("autodoc", "1")</H4>
189 +
190 +When the "1" option is used then the parameter types <em>will</em> be
191 +used in the autodoc string. In addition, an atempt is made to
192 +simplify the type name such that it makes more sense to the Python
193 +user. Pointer, reference and const info is removed,
194 +<tt>%rename</tt>'s are evaluated, etc. (This is not always
195 +successful, but works most of the time. See the next section for what
196 +to do when it doesn't.) Given the example above, then turning on the
197 +parameter types with the "1" option will result in Python code like
198 +this:
199 +
200 +<blockquote>
201 +<pre>
202 +def function_name(*args, **kwargs):
203 + """function_name(int x, int y, Foo foo=None, Bar bar=None) -> bool"""
204 + ...
205 +</pre>
206 +</blockquote>
207 +
208 +
209 +
210 +<H4>%feature("autodoc", "docstring")</H4>
211 +
212 +Finally, there are times when the automatically generated autodoc
213 +string will make no sense for a Python programmer, particularly when a
214 +typemap is involved. So if you give an explicit value for the autodoc
215 +feature then that string will be used in place of the automatically
216 +generated string. For example:
217 +
218 +<blockquote>
219 +<pre>
220 +%feature("autodoc", "GetPosition() -> (x, y)") GetPosition;
221 +void GetPosition(int* OUTPUT, int* OUTPUT);
222 +</pre>
223 +</blockquote>
224 +
225 +
226 +<H3><a name="Python_nn68"></a>26.10.3 %feature("docstring")</H3>
227 +
228 +In addition to the autodoc strings described above, you can also
229 +attach any arbitrary descriptive text to a node in the parse tree with
230 +the "docstring" feature. When the proxy module is generated then any
231 +docstring associated with classes, function or methods are output.
232 +If an item already has an autodoc string then it is combined with the
233 +docstring and they are output together. If the docstring is all on a
234 +single line then it is output like this::
235 +
236 +<blockquote>
237 +<pre>
238 +"""This is the docstring"""
239 +</pre>
240 +</blockquote>
241 +
242 +Otherwise, to aid readability it is output like this:
243 +
244 +<blockquote>
245 +<pre>
246 +"""
247 +This is a multi-line docstring
248 +with more than one line.
249 +"""
250 +</pre>
251 +</blockquote>
252 +
253 +<H2><a name="Python_nn70"></a>26.11 Python Packages</H2>
254 +
255 +Using the <tt>package</tt> option of the <tt>%module</tt> directive
256 +allows you to specify what Python package that the module will be
257 +living in when installed.
258 +
259 +<blockquote>
260 +<pre>
261 +%module(package="wx") xrc
262 +</pre>
263 +</blockquote>
264 +
265 +This is useful when the <tt>.i</tt> file is <tt>%import</tt>ed by
266 +another <tt>.i</tt> file. By default SWIG will assume that the
267 +importer is able to find the importee with just the module name, but
268 +if they live in separate Python packages then that won't work.
269 +However if the importee specifies what its package is with the
270 +<tt>%module</tt> option then the Python code generated for the
271 +importer will use that package name when importing the other module
272 +and also in base class declarations, etc. if the pacakge name is
273 +different than its own.
274 +
275 +
276 +
277 </body>
278 </html>
279 Index: Source/Modules/python.cxx
280 ===================================================================
281 RCS file: /cvsroot/swig/SWIG/Source/Modules/python.cxx,v
282 retrieving revision 1.50
283 diff -u -4 -r1.50 python.cxx
284 --- Source/Modules/python.cxx 1 Sep 2004 22:25:56 -0000 1.50
285 +++ Source/Modules/python.cxx 6 Sep 2004 21:06:11 -0000
286 @@ -19,8 +19,9 @@
287
288 static String *const_code = 0;
289 static String *shadow_methods = 0;
290 static String *module = 0;
291 +static String *package = 0;
292 static String *mainmodule = 0;
293 static String *interface = 0;
294 static String *global_name = 0;
295 static int shadow = 1;
296 @@ -50,8 +51,18 @@
297 static int have_constructor;
298 static int have_repr;
299 static String *real_classname;
300
301 +/* flags for the make_autodoc function */
302 +enum autodoc_t {
303 + AUTODOC_CLASS,
304 + AUTODOC_CTOR,
305 + AUTODOC_DTOR,
306 + AUTODOC_STATICFUNC,
307 + AUTODOC_FUNC,
308 + AUTODOC_METHOD
309 +};
310 +
311 static const char *usage = (char *)"\
312 Python Options (available with -python)\n\
313 -globals <name> - Set <name> used to access C global variable [default: 'cvar']\n\
314 -interface <lib>- Set the lib name to <lib>\n\
315 @@ -145,19 +156,22 @@
316 *
317 * use %module(directors="1") modulename at the start of the
318 * interface file to enable director generation.
319 */
320 + String* mod_docstring = NULL;
321 {
322 - Node *module = Getattr(n, "module");
323 - if (module) {
324 - Node *options = Getattr(module, "options");
325 + Node *mod = Getattr(n, "module");
326 + if (mod) {
327 + Node *options = Getattr(mod, "options");
328 if (options) {
329 if (Getattr(options, "directors")) {
330 allow_directors();
331 }
332 if (Getattr(options, "dirprot")) {
333 allow_dirprot();
334 }
335 + mod_docstring = Getattr(options, "docstring");
336 + package = Getattr(options, "package");
337 }
338 }
339 }
340
341 @@ -257,8 +271,13 @@
342 Printv(f_shadow,
343 "# This file is compatible with both classic and new-style classes.\n",
344 NIL);
345 }
346 +
347 + if (mod_docstring && Len(mod_docstring)) {
348 + Printv(f_shadow, "\n\"\"\"\n", mod_docstring, "\n\"\"\"\n", NIL);
349 + Delete(mod_docstring); mod_docstring = NULL;
350 + }
351
352 Printf(f_shadow,"\nimport %s\n\n", module);
353
354 if (! modern) {
355 @@ -381,9 +400,28 @@
356 virtual int importDirective(Node *n) {
357 if (shadow) {
358 String *modname = Getattr(n,"module");
359 if (modname) {
360 - Printf(f_shadow,"import %s\n", modname);
361 + Printf(f_shadow,"import ");
362 +
363 + // Find the module node for this imported module. It should be the
364 + // first child but search just in case.
365 + Node* mod = firstChild(n);
366 + while (mod && Strcmp(nodeType(mod), "module") != 0)
367 + mod = nextSibling(mod);
368 +
369 + // Is the imported module in another package? (IOW, does it use the
370 + // %module(package="name") option and it's different than the package
371 + // of this module.)
372 + Node *options = Getattr(mod, "options");
373 + if (options && Getattr(options, "package")) {
374 + String* pkg = Getattr(options, "package");
375 + if (!package || Strcmp(pkg, package) != 0)
376 + Printf(f_shadow, "%s.", Getattr(options, "package"));
377 + }
378 +
379 + // finally, output the name of the imported module
380 + Printf(f_shadow, "%s\n", modname);
381 }
382 }
383 return Language::importDirective(n);
384 }
385 @@ -416,17 +454,25 @@
386 * functions.
387 * ------------------------------------------------------------ */
388
389 void emitFunctionShadowHelper(Node *n, File *f_dest, String *name, int kw) {
390 - if ( ! have_addtofunc(n) ) {
391 - /* If there is no addtofunc directive then just assign from the extension module */
392 + if ( !have_pythonprepend(n) && !have_pythonappend(n) && !have_docstring(n) ) {
393 + /* If there is no pythonappend or docstring directive then just assign from the extension module */
394 Printv(f_dest, "\n", name, " = ", module, ".", name, "\n", NIL);
395 } else {
396 /* Otherwise make a wrapper function to insert the code into */
397 Printv(f_dest, "\ndef ", name, "(*args", (kw ? ", **kwargs" : ""), "):\n", NIL);
398 - Printv(f_dest, tab4, "val = ", funcCallHelper(name, kw), "\n", NIL);
399 - Printv(f_dest, tab4, addtofunc(n), "\n", NIL);
400 - Printv(f_dest, tab4, "return val\n", NIL);
401 + if ( have_docstring(n) )
402 + Printv(f_dest, tab4, docstring(n, AUTODOC_FUNC, tab4), "\n", NIL);
403 + if ( have_pythonprepend(n) )
404 + Printv(f_dest, tab4, pythonprepend(n), "\n", NIL);
405 + if ( have_pythonappend(n) ) {
406 + Printv(f_dest, tab4, "val = ", funcCallHelper(name, kw), "\n", NIL);
407 + Printv(f_dest, tab4, pythonappend(n), "\n", NIL);
408 + Printv(f_dest, tab4, "return val\n", NIL);
409 + } else {
410 + Printv(f_dest, tab4, "return ", funcCallHelper(name, kw), "\n", NIL);
411 + }
412 }
413 }
414
415
416 @@ -440,24 +486,303 @@
417 }
418
419
420 /* ------------------------------------------------------------
421 - * have_addtofunc()
422 - * Check if there is a %addtofunc directive and it has text
423 + * have_docstring()
424 + * Check if there is a docstring directive and it has text,
425 + * or there is an autodoc flag set
426 * ------------------------------------------------------------ */
427
428 - bool have_addtofunc(Node *n) {
429 - String* str = Getattr(n, "feature:addtofunc");
430 + bool have_docstring(Node *n) {
431 + String* str = Getattr(n, "feature:docstring");
432 + return (str != NULL && Len(str) > 0) ||
433 + (Getattr(n,"feature:autodoc") && !Getattr(n, "feature:noautodoc"));
434 + }
435 +
436 + /* ------------------------------------------------------------
437 + * docstring()
438 + * Get the docstring text, stripping off {} if neccessary,
439 + * and enclose in triple double quotes. If autodoc is also
440 + * set then it will build a combined docstring.
441 + * ------------------------------------------------------------ */
442 +
443 + String *docstring(Node *n, autodoc_t ad_type, const String* indent) {
444 + String* str = Getattr(n, "feature:docstring");
445 + bool have_ds = (str != NULL && Len(str) > 0);
446 + bool have_auto = (Getattr(n,"feature:autodoc") && !Getattr(n, "feature:noautodoc"));
447 + char* triple_double = "\"\"\"";
448 + String* autodoc = NULL;
449 + String* doc = NULL;
450 +
451 + if ( have_ds ) {
452 + char* t = Char(str);
453 + if (*t == '{') {
454 + Delitem(str ,0);
455 + Delitem(str,DOH_END);
456 + }
457 + }
458 +
459 + if ( have_auto ) {
460 + autodoc = make_autodoc(n, ad_type);
461 + have_auto = (autodoc != NULL && Len(autodoc) > 0);
462 + }
463 +
464 + // If there is more than one line then make docstrings like this:
465 + //
466 + // """
467 + // This is line1
468 + // And here is line2 followed by the rest of them
469 + // """
470 + //
471 + // otherwise, put it all on a single line
472 + //
473 + if ( have_auto && have_ds ) { // Both autodoc and docstring are present
474 + doc = NewString("");
475 + Printv(doc, triple_double, "\n",
476 + pythoncode(autodoc, indent), "\n",
477 + pythoncode(str, indent),
478 + indent, triple_double, NIL);
479 + }
480 + else if ( !have_auto && have_ds ) { // only docstring
481 + if (Strchr(str, '\n') == NULL) {
482 + doc = NewStringf("%s%s%s", triple_double, str, triple_double);
483 + }
484 + else {
485 + doc = NewString("");
486 + Printv(doc, triple_double, "\n",
487 + pythoncode(str, indent),
488 + indent, triple_double, NIL);
489 + }
490 + }
491 + else if ( have_auto && !have_ds ) { // only autodoc
492 + if (Strchr(autodoc, '\n') == NULL) {
493 + doc = NewStringf("%s%s%s", triple_double, autodoc, triple_double);
494 + }
495 + else {
496 + doc = NewString("");
497 + Printv(doc, triple_double, "\n",
498 + pythoncode(autodoc, indent),
499 + indent, triple_double, NIL);
500 + }
501 + }
502 + else
503 + doc = NewString("");
504 +
505 + // Save the generated strings in the parse tree in case they are used later
506 + // by post processing tools
507 + Setattr(n, "python:docstring", doc);
508 + Setattr(n, "python:autodoc", autodoc);
509 + return doc;
510 + }
511 +
512 +
513 + /* ------------------------------------------------------------
514 + * make_autodoc()
515 + * Build a docstring for the node, using parameter and other
516 + * info in the parse tree. If the value of the autodoc
517 + * attribute is "0" then do not include parameter types, if
518 + * it is "1" (the default) then do. If it has some other
519 + * value then assume it is supplied by the extension writer
520 + * and use it directly.
521 + * ------------------------------------------------------------ */
522 +
523 + String* make_autodoc(Node *n, autodoc_t ad_type) {
524 +
525 + if (ad_type == AUTODOC_CLASS)
526 + return NULL; // No function call to document in this case
527 +
528 + // If the function is overloaded then this funciton is called
529 + // for the last one. Rewind to the first so the docstrings are
530 + // in order.
531 + while ( Getattr(n, "sym:previousSibling") )
532 + n = Getattr(n, "sym:previousSibling");
533 +
534 + String* doc = NewString("");
535 + while (n) {
536 + bool showTypes = false;
537 + bool skipAuto = false;
538 +
539 + // check how should the parameters be rendered?
540 + String* autodoc = Getattr(n, "feature:autodoc");
541 + if (Strcmp(autodoc, "0") == 0)
542 + showTypes = false;
543 + else if (Strcmp(autodoc, "1") == 0)
544 + showTypes = true;
545 + else {
546 + // if not "0" or "1" then autodoc is already the string that should be used
547 + Printf(doc, "%s", autodoc);
548 + skipAuto = true;
549 + }
550 +
551 + if (!skipAuto) {
552 + String* symname = Getattr(n, "sym:name");
553 + SwigType* type = Getattr(n, "type");
554 +
555 + if (type) {
556 + if (Strcmp(type, "void") == 0)
557 + type = NULL;
558 + else {
559 + SwigType* qt = SwigType_typedef_resolve_all(type);
560 + if (SwigType_isenum(qt))
561 + type = NewString("int");
562 + else {
563 + type = SwigType_base(type);
564 + Node* lookup = Swig_symbol_clookup(type, 0);
565 + if (lookup)
566 + type = Getattr(lookup, "sym:name");
567 + }
568 + }
569 + }
570 +
571 + switch ( ad_type ) {
572 + case AUTODOC_CTOR:
573 + if ( Strcmp(class_name, symname) == 0) {
574 + String* paramList = make_autodocParmList(n, showTypes);
575 + if (Len(paramList))
576 + Printf(doc, "__init__(self, %s) -> %s", paramList, class_name);
577 + else
578 + Printf(doc, "__init__(self) -> %s", class_name);
579 + }
580 + else
581 + Printf(doc, "%s(%s) -> %s", symname, make_autodocParmList(n, showTypes), class_name);
582 + break;
583 +
584 + case AUTODOC_DTOR:
585 + Printf(doc, "__del__(self)");
586 + break;
587 +
588 + case AUTODOC_STATICFUNC:
589 + Printf(doc, "%s(%s)", symname, make_autodocParmList(n, showTypes));
590 + if (type) Printf(doc, " -> %s", type);
591 + break;
592 +
593 + case AUTODOC_FUNC:
594 + Printf(doc, "%s(%s)", symname, make_autodocParmList(n, showTypes));
595 + if (type) Printf(doc, " -> %s", type);
596 + break;
597 +
598 + case AUTODOC_METHOD:
599 + String* paramList = make_autodocParmList(n, showTypes);
600 + if (Len(paramList))
601 + Printf(doc, "%s(self, %s)", symname, paramList);
602 + else
603 + Printf(doc, "%s(self)", symname);
604 + if (type) Printf(doc, " -> %s", type);
605 + break;
606 + }
607 + }
608 +
609 + // if it's overloaded then get the next decl and loop around again
610 + n = Getattr(n, "sym:nextSibling");
611 + if (n)
612 + Printf(doc, "\n");
613 + }
614 +
615 + return doc;
616 + }
617 +
618 +
619 + String* make_autodocParmList(Node* n, bool showTypes) {
620 + String* doc = NewString("");
621 + ParmList* plist = Getattr(n,"parms");
622 + Parm* p;
623 + Node* lookup;
624 + int lines = 0;
625 + const int maxwidth = 50;
626 +
627 +
628 + for (p = plist; p; p = nextSibling(p)) {
629 + String* name = Getattr(p, "name");
630 + String* value = Getattr(p, "value");
631 +
632 + if ( Len(doc) ) {
633 + // add a comma to the previous one if any
634 + Printf(doc, ", ");
635 +
636 + // Do we need to wrap a long line?
637 + if ((Len(doc) - lines*maxwidth) > maxwidth) {
638 + Printf(doc, "\n%s", tab4);
639 + lines += 1;
640 + }
641 + }
642 +
643 + // Do the param type too?
644 + if (showTypes) {
645 + SwigType* type = SwigType_base(Getattr(p, "type"));
646 + SwigType* qt = SwigType_typedef_resolve_all(type);
647 + if (SwigType_isenum(qt))
648 + type = NewString("int");
649 + else {
650 + lookup = Swig_symbol_clookup(type, 0);
651 + if (lookup)
652 + type = Getattr(lookup, "sym:name");
653 + }
654 + Printf(doc, "%s ", type);
655 + }
656 +
657 + if (name)
658 + Printf(doc, "%s", name);
659 + else
660 + Printf(doc, "??");
661 +
662 + if (value) {
663 + if (Strcmp(value, "NULL") == 0)
664 + value = NewString("None");
665 + else {
666 + lookup = Swig_symbol_clookup(value, 0);
667 + if (lookup)
668 + value = Getattr(lookup, "sym:name");
669 + }
670 + Printf(doc, "=%s", value);
671 + }
672 + }
673 +
674 + return doc;
675 + }
676 +
677 +
678 + /* ------------------------------------------------------------
679 + * have_pythonprepend()
680 + * Check if there is a %pythonprepend directive and it has text
681 + * ------------------------------------------------------------ */
682 +
683 + bool have_pythonprepend(Node *n) {
684 + String* str = Getattr(n, "feature:pythonprepend");
685 + return (str != NULL && Len(str) > 0);
686 + }
687 +
688 + /* ------------------------------------------------------------
689 + * pythonprepend()
690 + * Get the %pythonprepend code, stripping off {} if neccessary
691 + * ------------------------------------------------------------ */
692 +
693 + String *pythonprepend(Node *n) {
694 + String* str = Getattr(n, "feature:pythonprepend");
695 + char* t = Char(str);
696 + if (*t == '{') {
697 + Delitem(str ,0);
698 + Delitem(str,DOH_END);
699 + }
700 + return str;
701 + }
702 +
703 + /* ------------------------------------------------------------
704 + * have_pythonappend()
705 + * Check if there is a %pythonappend directive and it has text
706 + * ------------------------------------------------------------ */
707 +
708 + bool have_pythonappend(Node *n) {
709 + String* str = Getattr(n, "feature:pythonappend");
710 return (str != NULL && Len(str) > 0);
711 }
712
713 /* ------------------------------------------------------------
714 - * addtofunc()
715 - * Get the %addtofunc code, stripping off {} if neccessary
716 + * pythonappend()
717 + * Get the %pythonappend code, stripping off {} if neccessary
718 * ------------------------------------------------------------ */
719
720 - String *addtofunc(Node *n) {
721 - String* str = Getattr(n, "feature:addtofunc");
722 + String *pythonappend(Node *n) {
723 + String* str = Getattr(n, "feature:pythonappend");
724 char* t = Char(str);
725 if (*t == '{') {
726 Delitem(str ,0);
727 Delitem(str,DOH_END);
728 @@ -1686,9 +2011,18 @@
729 mod = Getattr(n,"module");
730 if (mod) {
731 String *modname = Getattr(mod,"name");
732 if (Strcmp(modname,mainmodule) != 0) {
733 - importname = NewStringf("%s.%s", modname, Getattr(n,"sym:name"));
734 + // check if the module has a package option
735 + String* pkg = NULL;
736 + Node *options = Getattr(mod, "options");
737 + if (options && Getattr(options, "package"))
738 + pkg = Getattr(options, "package");
739 +
740 + if (!package || Strcmp(pkg, package) != 0)
741 + importname = NewStringf("%s.%s.%s", pkg, modname, Getattr(n,"sym:name"));
742 + else
743 + importname = NewStringf("%s.%s", modname, Getattr(n,"sym:name"));
744 } else {
745 importname = NewString(Getattr(n,"sym:name"));
746 }
747 Setattr(n,"python:proxy",importname);
748 @@ -1760,9 +2094,11 @@
749 Printf(f_shadow, modern ? "(object)" : "(_object)");
750 }
751 }
752 Printf(f_shadow,":\n");
753 -
754 + if ( Getattr(n, "feature:docstring") ) // don't use have_docstring in this case because autodoc doesn't apply
755 + Printv(f_shadow, tab4, docstring(n, AUTODOC_CLASS, tab4), "\n", NIL);
756 +
757 if (!modern) {
758 Printv(f_shadow,tab4,"__swig_setmethods__ = {}\n",NIL);
759 if (Len(base_class)) {
760 Printf(f_shadow,"%sfor _s in [%s]: __swig_setmethods__.update(_s.__swig_setmethods__)\n",tab4,base_class);
761 @@ -1906,16 +2242,24 @@
762 Delete(pyaction);
763 Printv(f_shadow,pycode,"\n",NIL);
764 } else {
765
766 - Printv(f_shadow, tab4, "def ", symname, "(*args", (allow_kwargs ? ", **kwargs" : ""), "): ", NIL);
767 - if ( have_addtofunc(n) ) {
768 - Printv(f_shadow, "\n", NIL);
769 - Printv(f_shadow, tab8, "val = ", funcCallHelper(Swig_name_member(class_name,symname), allow_kwargs), "\n", NIL);
770 - Printv(f_shadow, tab8, addtofunc(n), "\n", NIL);
771 - Printv(f_shadow, tab8, "return val\n", NIL);
772 + Printv(f_shadow, tab4, "def ", symname, "(*args", (allow_kwargs ? ", **kwargs" : ""), "):", NIL);
773 + if ( !have_pythonprepend(n) && !have_pythonappend(n) && !have_docstring(n)) {
774 + Printv(f_shadow, " return ", funcCallHelper(Swig_name_member(class_name,symname), allow_kwargs), "\n", NIL);
775 } else {
776 - Printv(f_shadow, "return ", funcCallHelper(Swig_name_member(class_name,symname), allow_kwargs), "\n", NIL);
777 + Printv(f_shadow, "\n", NIL);
778 + if ( have_docstring(n) )
779 + Printv(f_shadow, tab8, docstring(n, AUTODOC_METHOD, tab8), "\n", NIL);
780 + if ( have_pythonprepend(n) )
781 + Printv(f_shadow, tab8, pythonprepend(n), "\n", NIL);
782 + if ( have_pythonappend(n) ) {
783 + Printv(f_shadow, tab8, "val = ", funcCallHelper(Swig_name_member(class_name,symname), allow_kwargs), "\n", NIL);
784 + Printv(f_shadow, tab8, pythonappend(n), "\n", NIL);
785 + Printv(f_shadow, tab8, "return val\n\n", NIL);
786 + } else {
787 + Printv(f_shadow, tab8, "return ", funcCallHelper(Swig_name_member(class_name,symname), allow_kwargs), "\n\n", NIL);
788 + }
789 }
790 }
791
792 }
793 @@ -1930,14 +2274,22 @@
794 virtual int staticmemberfunctionHandler(Node *n) {
795 String *symname = Getattr(n,"sym:name");
796 Language::staticmemberfunctionHandler(n);
797 if (shadow) {
798 - if ( !classic && have_addtofunc(n) ) {
799 + if ( !classic && (have_pythonprepend(n) || have_pythonappend(n) || have_docstring(n)) ) {
800 int kw = (check_kwargs(n) && !Getattr(n,"sym:overloaded")) ? 1 : 0;
801 Printv(f_shadow, tab4, "def ", symname, "(*args", (kw ? ", **kwargs" : ""), "):\n", NIL);
802 - Printv(f_shadow, tab8, "val = ", funcCallHelper(Swig_name_member(class_name, symname), kw), "\n", NIL);
803 - Printv(f_shadow, tab8, addtofunc(n), "\n", NIL);
804 - Printv(f_shadow, tab8, "return val\n", NIL);
805 + if ( have_docstring(n) )
806 + Printv(f_shadow, tab8, docstring(n, AUTODOC_STATICFUNC, tab8), "\n", NIL);
807 + if ( have_pythonprepend(n) )
808 + Printv(f_shadow, tab8, pythonprepend(n), "\n", NIL);
809 + if ( have_pythonappend(n) ) {
810 + Printv(f_shadow, tab8, "val = ", funcCallHelper(Swig_name_member(class_name, symname), kw), "\n", NIL);
811 + Printv(f_shadow, tab8, pythonappend(n), "\n", NIL);
812 + Printv(f_shadow, tab8, "return val\n\n", NIL);
813 + } else {
814 + Printv(f_shadow, tab8, "return ", funcCallHelper(Swig_name_member(class_name, symname), kw), "\n\n", NIL);
815 + }
816 Printv(f_shadow, tab4, modern ? "" : "if _newclass:", symname,
817 " = staticmethod(", symname, ")\n", NIL);
818
819 if (!modern) {
820 @@ -2022,8 +2374,12 @@
821 }
822
823 Printv(f_shadow, tab4, "def __init__(self, *args",
824 (allow_kwargs ? ", **kwargs" : ""), "):\n", NIL);
825 + if ( have_docstring(n) )
826 + Printv(f_shadow, tab8, docstring(n, AUTODOC_CTOR, tab8), "\n", NIL);
827 + if ( have_pythonprepend(n) )
828 + Printv(f_shadow, tab8, pythonprepend(n), "\n", NIL);
829 Printv(f_shadow, pass_self, NIL);
830 if (!modern) {
831 Printv(f_shadow, tab8, "_swig_setattr(self, ", rclassname, ", 'this', ",
832 funcCallHelper(Swig_name_construct(symname), allow_kwargs), ")\n", NIL);
833 @@ -2036,10 +2392,10 @@
834 Printv(f_shadow, tab8, "self.this = newobj.this\n", NIL);
835 Printv(f_shadow, tab8, "self.thisown = 1\n", NIL);
836 Printv(f_shadow, tab8, "del newobj.thisown\n", NIL);
837 }
838 - if ( have_addtofunc(n) )
839 - Printv(f_shadow, tab8, addtofunc(n), "\n", NIL);
840 + if ( have_pythonappend(n) )
841 + Printv(f_shadow, tab8, pythonappend(n), "\n\n", NIL);
842 Delete(pass_self);
843 }
844 have_constructor = 1;
845 } else {
846 @@ -2055,13 +2411,17 @@
847 } else {
848
849 Printv(f_shadow_stubs, "\ndef ", symname, "(*args",
850 (allow_kwargs ? ", **kwargs" : ""), "):\n", NIL);
851 + if ( have_docstring(n) )
852 + Printv(f_shadow_stubs, tab4, docstring(n, AUTODOC_CTOR, tab4), "\n", NIL);
853 + if ( have_pythonprepend(n) )
854 + Printv(f_shadow_stubs, tab4, pythonprepend(n), "\n", NIL);
855 Printv(f_shadow_stubs, tab4, "val = ",
856 funcCallHelper(Swig_name_construct(symname), allow_kwargs), "\n", NIL);
857 Printv(f_shadow_stubs, tab4, "val.thisown = 1\n", NIL);
858 - if ( have_addtofunc(n) )
859 - Printv(f_shadow_stubs, tab4, addtofunc(n), "\n", NIL);
860 + if ( have_pythonappend(n) )
861 + Printv(f_shadow_stubs, tab4, pythonappend(n), "\n", NIL);
862 Printv(f_shadow_stubs, tab4, "return val\n", NIL);
863 }
864 }
865 }
866 @@ -2088,13 +2448,18 @@
867 Delete(pyaction);
868 Printv(f_shadow,pycode,"\n", NIL);
869 } else {
870 Printv(f_shadow, tab4, "def __del__(self, destroy=", module, ".", Swig_name_destroy(symname), "):\n", NIL);
871 - if ( have_addtofunc(n) )
872 - Printv(f_shadow, tab8, addtofunc(n), "\n", NIL);
873 + if ( have_docstring(n) )
874 + Printv(f_shadow, tab8, docstring(n, AUTODOC_DTOR, tab8), "\n", NIL);
875 + if ( have_pythonprepend(n) )
876 + Printv(f_shadow, tab8, pythonprepend(n), "\n", NIL);
877 Printv(f_shadow, tab8, "try:\n", NIL);
878 - Printv(f_shadow, tab4, tab8, "if self.thisown: destroy(self)\n", NIL);
879 + Printv(f_shadow, tab8, tab4, "if self.thisown: destroy(self)\n", NIL);
880 Printv(f_shadow, tab8, "except: pass\n", NIL);
881 + if ( have_pythonappend(n) )
882 + Printv(f_shadow, tab8, pythonappend(n), "\n", NIL);
883 + Printv(f_shadow, "\n", NIL);
884 }
885 }
886 return SWIG_OK;
887 }