Planet

navi

home

PPS

about

screenshots

download

development

forum

Context Navigation

source: downloads/boost_1_34_1/libs/python/doc/v2/class.html @ 45

Last change on this file since 45 was 29, checked in by landauf, 17 years ago
updated boost from 1_33_1 to 1_34_1
File size: 29.5 KB

Line
1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
3	<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
4	<!-- Software License, Version 1.0. (See accompanying -->
5	<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
6	<html>
7	<head>
8	<meta name="generator" content=
9	"HTML Tidy for Cygwin (vers 1st September 2004), see www.w3.org">
10	<meta http-equiv="Content-Type" content="text/html; charset=iso-latin-1-dos">
11	<link rel="stylesheet" type="text/css" href="../boost.css">
12
13	<title>Boost.Python - <boost/python/class.hpp>,
14	<boost/python/class_fwd.hpp></title>
15	</head>
16
17	<body link="#0000FF" vlink="#800080">
18	<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
19	"header">
20	<tr>
21	<td valign="top" width="300">
22	<h3><a href="../../../../index.htm"><img height="86" width="277" alt=
23	"C++ Boost" src="../../../../boost.png" border="0"></a></h3>
24	</td>
25
26	<td valign="top">
27	<h1 align="center"><a href="../index.html">Boost.Python</a></h1>
28
29	<h2 align="center">Headers <boost/python/class.hpp>,
30	<boost/python/class_fwd.hpp></h2>
31	</td>
32	</tr>
33	</table>
34	<hr>
35
36	<h2>Contents</h2>
37
38	<dl class="page-index">
39	<dt><a href="#introduction">Introduction</a></dt>
40
41	<dt><a href="#classes">Classes</a></dt>
42
43	<dd>
44	<dl class="page-index">
45	<dt><a href="#class_-spec">Class template
46	<code>class_</code></a></dt>
47
48	<dd>
49	<dl class="page-index">
50	<dt><a href="#class_-spec-synopsis">Class <code>class_</code>
51	synopsis</a></dt>
52
53	<dt><a href="#class_-spec-ctors">Class <code>class_</code>
54	constructors</a></dt>
55
56	<dt><a href="#class_-spec-modifiers">Class <code>class_</code>
57	modifier functions</a></dt>
58	</dl>
59	</dd>
60
61	<dt><a href="#bases-spec">Class template <code>bases</code></a></dt>
62
63	<dd>
64	<dl class="page-index">
65	<dt><a href="#bases-spec-synopsis">Class template
66	<code>bases</code> synopsis</a></dt>
67	</dl>
68	</dd>
69	</dl>
70	</dd>
71
72	<dt><a href="#examples">Example(s)</a></dt>
73	</dl>
74	<hr>
75
76	<h2><a name="introduction" id="introduction"></a>Introduction</h2>
77
78	<p><code><boost/python/class.hpp></code> defines the interface
79	through which users expose their C++ classes to Python. It declares the
80	<code>class_</code> class template, which is parameterized on the class
81	type being exposed. It also exposes the <code>init</code>,
82	<code>optional</code> and <code>bases</code> utility class templates, which
83	are used in conjunction with <code>class_</code>.</p>
84
85	<p><code><boost/python/class_fwd.hpp></code> contains a forward
86	declaration of the <code>class_</code> class template.</p>
87
88	<h2><a name="classes" id="classes"></a>Classes</h2>
89
90	<h3><a name="class_-spec" id="class_-spec"></a>Class template
91	<code>class_<T, <font color="#007F00">Bases, HeldType,
92	NonCopyable</font>></code></h3>
93
94	<p>Creates a Python class associated with the C++ type passed as its first
95	parameter. Although it has four template parameters, only the first one is
96	required. The three optional arguments can actually be supplied
97	<font color="#007F00"><b>in any order</b></font>; Boost.Python determines
98	the role of the argument from its type.<br>
99	<br></p>
100
101	<table border="1" summary="class_ template parameters">
102	<tr>
103	<th>Template Parameter</th>
104
105	<th>Requirements</th>
106
107	<th>Semantics</th>
108
109	<th>Default</th>
110	</tr>
111
112	<tr>
113	<td><code>T</code></td>
114
115	<td>A class type.</td>
116
117	<td>The class being wrapped</td>
118	</tr>
119
120	<tr>
121	<td><code><font color="#007F00">Bases</font></code></td>
122
123	<td>A specialization of <a href=
124	"#bases-spec"><code>bases<</code>...<code>></code></a> which
125	specifies previously-exposed C++ base classes of <code>T</code><a href=
126	"#footnote_1">[1]</a>.</td>
127
128	<td>Registers <code>from_python</code> conversions from wrapped
129	<code>T</code> instances to each of its exposed direct and indirect
130	bases. For each polymorphic base <code>B</code>, registers conversions
131	from indirectly-held wrapped <code>B</code> instances to
132	<code>T</code>.</td>
133
134	<td><code><a href="#bases-spec">bases<></a></code></td>
135	</tr>
136
137	<tr>
138	<td><code><font color="#007F00">HeldType</font></code></td>
139
140	<td>Must be <code>T</code>, a class derived from <code>T</code>, or a
141	<a href="Dereferenceable.html">Dereferenceable</a> type for which
142	<code><a href=
143	"pointee.html#pointee-spec">pointee</a><HeldType>::type</code> is
144	<code>T</code> or a class derived from <code>T</code>.</td>
145
146	<td>Specifies the type that is actually embedded in a Python object
147	wrapping a <code>T</code> instance when <code>T</code>'s constructor is
148	called or when a <code>T</code> or <code>T*</code> is converted to
149	Python without the use of <a href=
150	"http://www.boost.org/libs/python/doc/v2/callbacks.html#argument_handling">
151	<code>ptr</code></a>, <a href=
152	"http://www.boost.org/libs/python/doc/v2/callbacks.html#argument_handling">
153	<code>ref</code></a>, or <a href="CallPolicies.html">Call Policies</a>
154	such as <code><a href=
155	"return_internal_reference.html">return_internal_reference</a></code>.
156	More details <a href="#HeldType">below</a>.</td>
157
158	<td><code>T</code></td>
159	</tr>
160
161	<tr>
162	<td><code><font color="#007F00">NonCopyable</font></code></td>
163
164	<td>If supplied, must be <a href=
165	"../../../utility/utility.htm#Class_noncopyable">boost::noncopyable</a>.</td>
166
167	<td>Suppresses automatic registration of <code>to_python</code>
168	conversions which copy <code>T</code> instances. Required when
169	<code>T</code> has no publicly-accessible copy constructor.</td>
170
171	<td>An unspecified type other than
172	<code>boost::noncopyable</code>.</td>
173	</tr>
174	</table>
175
176	<h4><a name="HeldType" id="HeldType">HeldType Semantics</a></h4>
177
178	<ol>
179	<li>If <code>HeldType</code> is derived from T, its exposed
180	constructor(s) must accept an initial <code>PyObject*</code> argument
181	which refers back to the Python object that contains the
182	<code>HeldType</code> instance, as shown in <a href=
183	"call_method.html#examples">this example</a>. This argument is not
184	included in the <em><a href=
185	"init.html#init-expressions">init-expression</a></em> passed to <a href=
186	"#class_-spec-modifiers"><code>def(init_expr)</code></a>, below, nor is
187	it passed explicitly by users when Python instances of <code>T</code> are
188	created. This idiom allows C++ virtual functions which will be overridden
189	in Python to access the Python object so the Python method can be
190	invoked. Boost.Python automatically registers additional converters which
191	allow wrapped instances of <code>T</code> to be passed to wrapped C++
192	functions expecting <code>HeldType</code> arguments.</li>
193
194	<li>Because Boost.Python will always allow wrapped instances of
195	<code>T</code> to be passed in place of <code>HeldType</code> arguments,
196	specifying a smart pointer for <code>HeldType</code> allows users to pass
197	Python <code>T</code> instances where a smart pointer-to-<code>T</code>
198	is expected. Smart pointers such as <code>std::auto_ptr<></code> or
199	<code><a href=
200	"../../../smart_ptr/shared_ptr.htm">boost::shared_ptr<></a></code>
201	which contain a nested type <code>element_type</code> designating the
202	referent type are automatically supported; additional smart pointer types
203	can be supported by specializing <a href=
204	"pointee.html#pointee-spec">pointee<HeldType></a>.</li>
205
206	<li>As in case 1 above, when <code>HeldType</code> is a smart pointer to
207	a class derived from <code>T</code>, the initial <code>PyObject*</code>
208	argument must be supplied by all of <code>HeldType</code>'s exposed
209	constructors.</li>
210
211	<li>Except in cases 1 and 3, users may optionally specify that T itself
212	gets initialized with a similar initial <code>PyObject*</code> argument
213	by specializing <a href=
214	"has_back_reference.html#has_back_reference-spec">has_back_reference<T></a>.</li>
215	</ol>
216
217	<h4><a name="class_-spec-synopsis" id="class_-spec-synopsis"></a>Class
218	template <code>class_</code> synopsis</h4>
219	<pre>
220	namespace boost { namespace python
221	{
222	template <class T
223	<font color="#007F00"> , class Bases = bases<>
224	, class HeldType = T
225	, class NonCopyable = <i>unspecified</i>
226	>
227	</font> class class_ : public <a href="object.html#object-spec">object</a>
228	{
229	// Constructors with default __init__
230	class_(char const* name);
231	class_(char const* name, char const* docstring);
232
233	// Constructors, specifying non-default __init__
234	template <class Init>
235	class_(char const* name, Init);
236	template <class Init>
237	class_(char const* name, char const* docstring, Init);
238
239	// Exposing additional __init__ functions
240	template <class Init>
241	class_& def(Init);
242
243	// defining methods
244	template <class F>
245	class_& def(char const* name, F f);
246	template <class Fn, class A1>
247	class_& def(char const* name, Fn fn, A1 const&);
248	template <class Fn, class A1, class A2>
249	class_& def(char const* name, Fn fn, A1 const&, A2 const&);
250	template <class Fn, class A1, class A2, class A3>
251	class_& def(char const* name, Fn fn, A1 const&, A2 const&, A3 const&);
252
253	// declaring method as static
254	class_& staticmethod(char const* name);
255
256	// exposing operators
257	template <<i>unspecified</i>>
258	class_& def(<a href=
259	"operators.html#operator_-spec">detail::operator_</a><unspecified>);
260
261	// Raw attribute modification
262	template <class U>
263	class_& setattr(char const* name, U const&);
264
265	// exposing data members
266	template <class D>
267	class_& def_readonly(char const* name, D T::*pm);
268
269	template <class D>
270	class_& def_readwrite(char const* name, D T::*pm);
271
272	// exposing static data members
273	template <class D>
274	class_& def_readonly(char const* name, D const& d);
275	template <class D>
276	class_& def_readwrite(char const* name, D& d);
277
278	// property creation
279	template <class Get>
280	void add_property(char const* name, Get const& fget, char const* doc=0);
281	template <class Get, class Set>
282	void add_property(
283	char const* name, Get const& fget, Set const& fset, char const* doc=0);
284
285	template <class Get>
286	void add_static_property(char const* name, Get const& fget);
287	template <class Get, class Set>
288	void add_static_property(char const* name, Get const& fget, Set const& fset);
289
290	// pickle support
291	template <typename PickleSuite>
292	self& def_pickle(PickleSuite const&);
293	self& enable_pickling();
294	};
295	}}
296	</pre>
297
298	<h4><a name="class_-spec-ctors" id="class_-spec-ctors"></a>Class template
299	<code>class_</code> constructors</h4>
300	<pre>
301	class_(char const* name);
302	class_(char const* name, char const* docstring);
303	template <class Init>
304	class_(char const* name, Init init_spec);
305	template <class Init>
306	class_(char const* name, char const* docstring, Init init_spec);
307	</pre>
308
309	<dl class="function-semantics">
310	<dt><b>Requires:</b> <code>name</code> is an <a href=
311	"definitions.html#ntbs">ntbs</a> which conforms to Python's <a href=
312	"http://www.python.org/doc/current/ref/identifiers.html">identifier
313	naming rules</a>. If <code>docstring</code> is supplied, it must be an
314	<a href="definitions.html#ntbs">ntbs</a>. If <code>init_spec</code> is
315	supplied, it must be either the special enumeration constant
316	<code>no_init</code> or an <a href=
317	"init.html#init-expressions">init-expression</a> compatible with
318	<code>T</code>.</dt>
319
320	<dt><b>Effects:</b> Constructs a <code>class_</code> object holding a
321	Boost.Python extension class named <code>name</code>. The
322	<code>name</code>d attribute of the <a href=
323	"scope.html#introduction">current scope</a> is bound to the new extension
324	class.</dt>
325
326	<dd>
327	<ul>
328	<li>If supplied, the value of <code>docstring</code> is bound to the
329	<code>__doc__</code> attribute of the extension class.</li>
330
331	<li>If <code>init_spec</code> is <code>no_init</code>, a special
332	<code>__init__</code> function is generated which always raises a
333	Python exception. Otherwise, <code>this->def(init_spec)</code> is
334	called.</li>
335
336	<li>If <code>init_spec</code> is not supplied,
337	<code>this->def(init<>())</code> is called.</li>
338	</ul>
339	</dd>
340
341	<dt><b>Rationale:</b>Allowing the user to specify constructor arguments
342	in the <code>class_<></code> constructor helps her to avoid the
343	common run-time errors which result from invoking wrapped member
344	functions without having exposed an <code>__init__</code> function which
345	creates the requisite <code>T</code> instance. Types which are not
346	default-constructible will cause a compile-time error unless
347	<code>Init</code> is supplied. The user must always supply
348	<code>name</code> as there is currently no portable method to derive the
349	text of the class name from its type.</dt>
350	</dl>
351
352	<h4><a name="class_-spec-modifiers" id="class_-spec-modifiers"></a>Class
353	template <code>class_</code> modifier functions</h4>
354	<pre>
355	template <class Init>
356	class_& def(Init init_expr);
357	</pre>
358
359	<dl class="function-semantics">
360	<dt><b>Requires:</b> <code>init_expr</code> is the result of an <a href=
361	"init.html#init-expressions">init-expression</a> compatible with
362	<code>T</code>.</dt>
363
364	<dt><b>Effects:</b> For each <a href="init.html#init-expressions">valid
365	prefix</a> <em>P</em> of <code>Init</code>, adds an
366	<code>__init__(</code>...<code>)</code> function overload to the
367	extension class accepting <em>P</em> as arguments. Each overload
368	generated constructs an object of <code>HeldType</code> according to the
369	semantics described <a href="#HeldType">above</a>, using a copy of
370	<code>init_expr</code>'s <a href="CallPolicies.html">call policies</a>.
371	If the longest <a href="init.html#init-expressions">valid prefix</a> of
372	<code>Init</code> contains <em>N</em> types and <code>init_expr</code>
373	holds <em>M</em> keywords, an initial sequence of the keywords are used
374	for all but the first <em>N</em> - <em>M</em> arguments of each
375	overload.</dt>
376
377	<dt><b>Returns:</b> <code>*this</code></dt>
378
379	<dt><b>Rationale:</b> Allows users to easily expose a class' constructor
380	to Python.</dt>
381	</dl><br>
382	<pre>
383	template <class F>
384	class_& def(char const* name, Fn fn);
385	template <class Fn, class A1>
386	class_& def(char const* name, Fn fn, A1 const& a1);
387	template <class Fn, class A1, class A2>
388	class_& def(char const* name, Fn fn, A1 const& a1, A2 const& a2);
389	template <class Fn, class A1, class A2, class A3>
390	class_& def(char const* name, Fn fn, A1 const& a1, A2 const& a2, A3 const& a3);
391	</pre>
392
393	<dl class="function-semantics">
394	<dt><b>Requires:</b> <code>name</code> is an <a href=
395	"definitions.html#ntbs">ntbs</a> which conforms to Python's <a href=
396	"http://www.python.org/doc/current/ref/identifiers.html">identifier
397	naming rules</a>.</dt>
398
399	<dd>
400	<ul>
401	<li>If <code>a1</code> is the result of an <a href=
402	"overloads.html#overload-dispatch-expression"><em>overload-dispatch-expression</em></a>,
403	only the second form is allowed and fn must be a pointer to function
404	or pointer to member function whose <a href="definitions.html#arity">
405	arity</a> is the same as A1's <a href=
406	"overloads.html#overload-dispatch-expression"><em>maximum
407	arity</em></a>.
408
409	<dl>
410	<dt><b>Effects:</b> For each prefix <em>P</em> of
411	<code>Fn</code>'s sequence of argument types, beginning with the
412	one whose length is <code>A1</code>'s <a href=
413	"overloads.html#overload-dispatch-expression"><em>minimum
414	arity</em></a>, adds a
415	<code><em>name</em>(</code>...<code>)</code> method overload to
416	the extension class. Each overload generated invokes
417	<code>a1</code>'s call-expression with <em>P</em>, using a copy
418	of <code>a1</code>'s <a href="CallPolicies.html">call
419	policies</a>. If the longest valid prefix of <code>A1</code>
420	contains <em>N</em> types and <code>a1</code> holds <em>M</em>
421	keywords, an initial sequence of the keywords are used for all
422	but the first <em>N</em> - <em>M</em> arguments of each
423	overload.<br></dt>
424	</dl>
425	</li>
426
427	<li>Otherwise, a single method overload is built around fn, which
428	must not be null:
429
430	<ul>
431	<li>If fn is a function pointer, its first argument must be of
432	the form <code>U</code>, <code>U <em>cv</em>&</code>, <code>U
433	<em>cv</em></code>, or <code>U <em>cv</em> const&</code>,
434	where <code>T</code> is convertible to <code>U</code>, and
435	<code>a1</code>-<code>a3</code>, if supplied, may be selected in
436	any order from the table below.</li>
437
438	<li>Otherwise, if fn is a member function pointer, its target
439	must be <code>T</code> or one of its public base classes, and
440	<code>a1</code>-<code>a3</code>, if supplied, may be selected in
441	any order from the table below.</li>
442
443	<li>Otherwise, <code>Fn</code> must be [derived from]
444	<code><a href="object.html#object-spec">object</a></code>, and
445	<code>a1-a2</code>, if supplied, may be selcted in any order from
446	the first two rows of the table below. To be useful,
447	<code>fn</code> should be <a href=
448	"http://www.python.org/doc/current/lib/built-in-funcs.html#l2h-6">
449	callable</a>.</li>
450	</ul>
451
452	<table border="1" summary="def() optional arguments">
453	<tr>
454	<th>Memnonic Name</th>
455
456	<th>Requirements/Type properties</th>
457
458	<th>Effects</th>
459	</tr>
460
461	<tr>
462	<td>docstring</td>
463
464	<td>Any <a href="definitions.html#ntbs">ntbs</a>.</td>
465
466	<td>Value will be bound to the <code>__doc__</code> attribute
467	of the resulting method overload. If an earlier overload
468	supplied a docstring, two newline characters and the new
469	docstring are appended to it.</td>
470	</tr>
471
472	<tr>
473	<td>policies</td>
474
475	<td>A model of <a href=
476	"CallPolicies.html">CallPolicies</a></td>
477
478	<td>A copy will be used as the call policies of the resulting
479	method overload.</td>
480	</tr>
481
482	<tr>
483	<td>keywords</td>
484
485	<td>The result of a <a href=
486	"args.html#keyword-expression"><em>keyword-expression</em></a>
487	specifying no more arguments than the <a href=
488	"definitions.html#arity">arity</a> of <code>fn</code>.</td>
489
490	<td>A copy will be used as the call policies of the resulting
491	method overload.</td>
492	</tr>
493	</table>
494	</li>
495	</ul>
496	</dd>
497
498	<dt><b>Returns:</b> <code>*this</code></dt>
499	</dl>
500	<pre>
501	class_& staticmethod(char const* name);
502	</pre>
503
504	<dl class="function-semantics">
505	<dt><b>Requires:</b> <code>name</code> is an <a href=
506	"definitions.html#ntbs">ntbs</a> which conforms to Python's <a href=
507	"http://www.python.org/doc/current/ref/identifiers.html">identifier
508	naming rules</a>, and corresponds to a method whose overloads have all
509	been defined.</dt>
510
511	<dt><b>Effects:</b> Replaces the existing named attribute <i>x</i> with
512	the result of invoking <code>staticmethod(</code><i>x</i><code>)</code>
513	in Python. Specifies that the corresponding method is static and
514	therefore no object instance will be passed to it. This is equivalent to
515	the Python statement:</dt>
516
517	<dd>
518	<pre>
519	setattr(self, name, staticmethod(getattr(self, name)))
520	</pre>
521	</dd>
522
523	<dt><b>Note:</b> Attempting to invoke <code>def(name,...)</code> after
524	invoking <code>staticmethod(name)</code> will <a href=
525	"definitions.html#raise">raise</a> a RuntimeError.</dt>
526
527	<dt><b>Returns:</b> <code>*this</code></dt>
528	</dl><br>
529	<pre>
530	template <<i>unspecified</i>>
531	class_& def(<a href=
532	"operators.html#operator_-spec">detail::operator_</a><unspecified>);
533	</pre>
534
535	<dl class="function-semantics">
536	<dt><b>Effects:</b> Adds a Python <a href=
537	"http://www.python.org/doc/ref/specialnames.html">special method</a> as
538	described <a href="operators.html">here</a>.</dt>
539
540	<dt><b>Returns:</b> <code>*this</code></dt>
541	</dl>
542	<pre>
543	template <class U>
544	class_& setattr(char const* name, U const& u);
545	</pre>
546
547	<dl class="function-semantics">
548	<dt><b>Requires:</b> <code>name</code> is an <a href=
549	"definitions.html#ntbs">ntbs</a> which conforms to Python's <a href=
550	"http://www.python.org/doc/current/ref/identifiers.html">identifier
551	naming rules</a>.</dt>
552
553	<dt><b>Effects:</b> Converts u to Python and adds it to the attribute
554	dictionary of the extension class:</dt>
555
556	<dd>
557	<blockquote>
558	<code><a href=
559	"http://www.python.org/doc/current/api/object.html#l2h-166">PyObject_SetAttrString</a>(this->ptr(),
560	name, <a href=
561	"object.html#object-spec-ctors">object</a>(u).ptr());</code>
562	</blockquote>
563	</dd>
564
565	<dt><b>Returns:</b> <code>*this</code></dt>
566	</dl><br>
567	<pre>
568	template <class Get>
569	void add_property(char const* name, Get const& fget, char const* doc=0);
570	template <class Get, class Set>
571	void add_property(
572	char const* name, Get const& fget, Set const& fset, char const* doc=0);
573	</pre>
574
575	<dl class="function-semantics">
576	<dt><b>Requires:</b> <code>name</code> is an <a href=
577	"definitions.html#ntbs">ntbs</a> which conform to Python's <a href=
578	"http://www.python.org/doc/current/ref/identifiers.html">identifier
579	naming rules</a>.</dt>
580
581	<dt><b>Effects:</b> Creates a new Python <a href=
582	"http://www.python.org/2.2.2/descrintro.html#property"><code>property</code></a>
583	class instance, passing <code><a href=
584	"object.html#object-spec-ctors">object</a>(fget)</code> (and
585	<code><a href="object.html#object-spec-ctors">object</a>(fset)</code> in
586	the second form) with an (optional) docstring <code>doc</code> to its
587	constructor, then adds that property to the Python class object under
588	construction with the given attribute <code>name</code>.</dt>
589
590	<dt><b>Returns:</b> <code>*this</code></dt>
591
592	<dt><b>Rationale:</b> Allows users to easily expose functions that can be
593	invoked from Python with attribute access syntax.</dt>
594	</dl><br>
595	<pre>
596	template <class Get>
597	void add_static_property(char const* name, Get const& fget);
598	template <class Get, class Set>
599	void add_static_property(char const* name, Get const& fget, Set const& fset);
600	</pre>
601
602	<dl class="function-semantics">
603	<dt><b>Requires:</b> <code>name</code> is an <a href=
604	"definitions.html#ntbs">ntbs</a> which conforms to Python's <a href=
605	"http://www.python.org/doc/current/ref/identifiers.html">identifier
606	naming rules</a>.</dt>
607
608	<dt><b>Effects:</b> Creates a Boost.Python.StaticProperty object, passing
609	<code><a href="object.html#object-spec-ctors">object</a>(fget)</code>
610	(and <code><a href=
611	"object.html#object-spec-ctors">object</a>(fset)</code> in the second
612	form) to its constructor, then adds that property to the Python class
613	under construction with the given attribute <code>name</code>.
614	StaticProperty is a special subclass of Python's <a href=
615	"http://www.python.org/2.2.2/descrintro.html#property"><code>property</code></a>
616	class which can be called without an initial <code>self</code>
617	argument.</dt>
618
619	<dt><b>Returns:</b> <code>*this</code></dt>
620
621	<dt><b>Rationale:</b> Allows users to easily expose functions that can be
622	invoked from Python with static attribute access syntax.</dt>
623	</dl><br>
624	<pre>
625	template <class D>
626	class_& def_readonly(char const* name, D T::pm, char const doc=0);
627	template <class D>
628	class_& def_readonly(char const* name, D const& d);
629	</pre>
630
631	<dl class="function-semantics">
632	<dt><b>Requires:</b> <code>name</code> is an <a href=
633	"definitions.html#ntbs">ntbs</a> which conforms to Python's <a href=
634	"http://www.python.org/doc/current/ref/identifiers.html">identifier
635	naming rules</a>. <code>doc</code> is also an ntbs.</dt>
636
637	<dt><b>Effects:</b></dt>
638
639	<dd>
640	<pre>
641	this->add_property(name, <a href=
642	"data_members.html#make_getter-spec">make_getter</a>(pm), doc);
643	</pre>and
644	<pre>
645	this->add_static_property(name, <a href=
646	"data_members.html#make_getter-spec">make_getter</a>(d));
647	</pre>respectively.<br>
648	<br>
649	</dd>
650
651	<dt><b>Returns:</b> <code>*this</code></dt>
652
653	<dt><b>Rationale:</b> Allows users to easily expose a class' data member
654	or free variable such that it can be inspected from Python with a natural
655	syntax.</dt>
656	</dl>
657	<pre>
658	template <class D>
659	class_& def_readwrite(char const* name, D T::pm, char const doc=0);
660	template <class D>
661	class_& def_readwrite(char const* name, D& d);
662	</pre>
663
664	<dl class="function-semantics">
665	<dt><b>Effects:</b></dt>
666
667	<dd>
668	<pre>
669	this->add_property(name, <a href=
670	"data_members.html#make_getter-spec">make_getter</a>(pm), <a href=
671	"data_members.html#make_setter-spec">make_setter</a>(pm), doc);
672	</pre>and
673	<pre>
674	this->add_static_property(name, <a href=
675	"data_members.html#make_getter-spec">make_getter</a>(d), <a href=
676	"data_members.html#make_setter-spec">make_setter</a>(d));
677	</pre>respectively.<br>
678	<br>
679	</dd>
680
681	<dt><b>Returns:</b> <code>*this</code></dt>
682
683	<dt><b>Rationale:</b> Allows users to easily expose a class' data or free
684	variable member such that it can be inspected and set from Python with a
685	natural syntax.</dt>
686	</dl>
687	<pre>
688	template <typename PickleSuite>
689	class_& def_pickle(PickleSuite const&);
690	</pre>
691
692	<dl class="function-semantics">
693	<dt><b>Requires:</b> PickleSuite must be publically derived from <a href=
694	"pickle.html"><code>pickle_suite</code></a>.</dt>
695
696	<dt><b>Effects:</b> Defines a legal combination of the special attributes
697	and methods: <code>__getinitargs__</code>, <code>__getstate__</code>,
698	<code>__setstate__</code>, <code>__getstate_manages_dict__</code>,
699	<code>__safe_for_unpickling__</code>, <code>__reduce__</code></dt>
700
701	<dt><b>Returns:</b> <code>*this</code></dt>
702
703	<dt><b>Rationale:</b> Provides an <a href="pickle.html">easy to use
704	high-level interface</a> for establishing complete pickle support for the
705	wrapped class. The user is protected by compile-time consistency
706	checks.</dt>
707	</dl><br>
708	<pre>
709	class_& enable_pickling();
710	</pre>
711
712	<dl class="function-semantics">
713	<dt><b>Effects:</b> Defines the <code>__reduce__</code> method and the
714	<code>__safe_for_unpickling__</code> attribute.</dt>
715
716	<dt><b>Returns:</b> <code>*this</code></dt>
717
718	<dt><b>Rationale:</b> Light-weight alternative to
719	<code>def_pickle()</code>. Enables implementation of <a href=
720	"pickle.html">pickle support</a> from Python.</dt>
721	</dl><br>
722
723	<h3><a name="bases-spec" id="bases-spec"></a>Class template
724	<code>bases<T1, T2,</code>...<code>TN></code></h3>
725
726	<p>An <a href="../../../mpl/doc/refmanual/forward-sequence.html">MPL
727	sequence</a> which can be used in
728	<code>class_<</code>...<code>></code> instantiations indicate a list
729	of base classes.</p>
730
731	<h4><a name="bases-spec-synopsis" id="bases-spec-synopsis"></a>Class
732	template <code>bases</code> synopsis</h4>
733	<pre>
734	namespace boost { namespace python
735	{
736	template <T1 = <i>unspecified</i>,...T<i>n</i> = <i>unspecified</i>>
737	struct bases
738	{};
739	}}
740	</pre>
741
742	<h2><a name="examples" id="examples"></a>Example(s)</h2>
743
744	<p>Given a C++ class declaration:</p>
745	<pre>
746	class Foo : public Bar, public Baz
747	{
748	public:
749	Foo(int x, char const* y);
750	Foo(double);
751
752	std::string const& name() { return m_name; }
753	void name(char const*);
754
755	double value; // public data
756	private:
757	...
758	};
759	</pre>A corresponding Boost.Python extension class can be created with:
760	<pre>
761	using namespace boost::python;
762
763	class_<Foo,bases<Bar,Baz> >("Foo",
764	"This is Foo's docstring."
765	"It describes our Foo extension class",
766
767	init<int,char const*>(args("x","y"), "__init__ docstring")
768	)
769	.def(init<double>())
770	.def("get_name", &Foo::get_name, return_internal_reference<>())
771	.def("set_name", &Foo::set_name)
772	.def_readwrite("value", &Foo::value)
773	;
774	</pre>
775	<hr>
776	<a name="footnote_1" id="footnote_1">[1]</a> By "previously-exposed" we
777	mean that the for each <code>B</code> in <code>bases</code>, an instance of
778	<code>class_<B<font color="#007F00">, ...</font>></code> must have
779	already been constructed.
780	<pre>
781	class_<Base>("Base");
782	class_<Derived, bases<Base> >("Derived");
783	</pre>Revised
784	<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
785	1 November, 2005 <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
786
787	<p><i>© Copyright <a href="../../../../people/dave_abrahams.htm">Dave
788	Abrahams</a> 2002.</i></p>
789	</body>
790	</html>

Note: See TracBrowser for help on using the repository browser.

Download in other formats: