Skip to content

Commit

Permalink
html_doc: Documented class wrapping, DPyObject
Browse files Browse the repository at this point in the history 
git-svn-id: http://svn.dsource.org/projects/pyd/trunk@34 1df65b71-e716-0410-9316-ac55df2b1602
  • Loading branch information
KirkMcDonald authored and KirkMcDonald committed Aug 10, 2006
1 parent f916116 commit 415cf00
Show file tree
Hide file tree
Showing 9 changed files with 154 additions and 51 deletions.
2 changes: 1 addition & 1 deletion html_doc/celerid.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
</head>

<body>
<div class="nav"><a class="nav" href="index.html">Main</a> | <a class="navcur" href="celerid.html">CeleriD</a> | <a class="nav" href="conversion.html">Type conversion</a> | <a class="nav" href="func_wrapping.html">Function wrapping</a> | <a class="nav" href="class_wrapping.html">Class wrapping</a> | <a class="nav" href="except_wrapping.html">Exception wrapping</a></div>
<div class="nav"><a class="nav" href="index.html">Main</a> | <a class="navcur" href="celerid.html">CeleriD</a> | <a class="nav" href="conversion.html">Type conversion</a> | <a class="nav" href="func_wrapping.html">Function wrapping</a> | <a class="nav" href="class_wrapping.html">Class wrapping</a> | <a class="nav" href="except_wrapping.html">Exception wrapping</a> | <a class="nav" href="dpyobject.html">DPyObject</a></div>

<h1>CeleriD</h1>

Expand Down
96 changes: 94 additions & 2 deletions html_doc/class_wrapping.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,103 @@
</head>

<body>
<div class="nav"><a class="nav" href="index.html">Main</a> | <a class="nav" href="celerid.html">CeleriD</a> | <a class="nav" href="conversion.html">Type conversion</a> | <a class="nav" href="func_wrapping.html">Function wrapping</a> | <a class="navcur" href="class_wrapping.html">Class wrapping</a> | <a class="nav" href="except_wrapping.html">Exception wrapping</a></div>
<div class="nav"><a class="nav" href="index.html">Main</a> | <a class="nav" href="celerid.html">CeleriD</a> | <a class="nav" href="conversion.html">Type conversion</a> | <a class="nav" href="func_wrapping.html">Function wrapping</a> | <a class="navcur" href="class_wrapping.html">Class wrapping</a> | <a class="nav" href="except_wrapping.html">Exception wrapping</a> | <a class="nav" href="dpyobject.html">DPyObject</a></div>

<h1>Class wrapping</h1>

<p><i>Coming soon...</i></p>
<p>Exposing D classes to Python is easy! The heart of Pyd's class wrapping features is the <code>wrapped_class</code> template struct:</p>

<p><code>struct wrapped_class(<span class="t_arg">T</span>, char[] <span class="t_arg">classname</span>);</code></p>
<ul>
<li><span class="t_arg">T</span> is the class being wrapped.</li>
<li><span class="t_arg">classname</span> is the name of the class as it will appear in Python.</li>
</ul>

<p>To expose the constructors, methods, and properties of the class, <code>wrapped_class</code> provides a series of template member functions.</p>

<dl>
<dt><code>static void def(alias <span class="t_arg">fn</span>, char[] <span class="t_arg">name</span>, <span class="t_arg">fn_t</span> = typeof(&amp;fn)) ();</code></dt>
<dd>This wraps a method of the class. It functions exactly like the <code>def</code> function used to <a href="func_wrapping.html">wrap regular functions</a>, with one very important difference: There is no support for default arguments. (This is a side-effect of the fact that you cannot call an alias of a method in D, and delegates do not understand default arguments.)</dd>

<dt><code>static void prop(alias <span class="t_arg">fn</span>, char[] <span class="t_arg">name</span>, bool <span class="t_arg">RO</span> = false) ();</code></dt>
<dd>This wraps a property. See the examples below for more details.
<ul>
<li><span class="t_arg">fn</span> is the name of the property. <code>prop</code> will automatically attempt to wrap both the "get" and "set" forms of the property, unless <span class="t_arg">RO</span> is specified.</li>
<li><span class="t_arg">name</span> is the name of the property as it will appear in Python.</li>
<li><span class="t_arg">RO</span> specifies whether this is a <i>read-only</i> property. If true, it will only wrap the "get" form of the property. If false, it will wrap both the "get" and "set" forms. (This is a little hackish, and I will probably try to make this detection more automatic in the future. It also means it cannot support a property that only has a "set" form.)</li>
</ul>
</dd>

<dt><code>static void init(<span class="t_arg">C1</span>, <span class="t_arg">C2</span>, <span class="t_arg">C3</span>, ..., <span class="t_arg">C<i>n</i></span>) ();</code></dt>
<dd>This allows you to expose anywhere from zero to 10 of the class's constructors to Python. If the class provides a zero-argument constructor, there is no need to specify it; it is always available. Each of <span class="t_arg">C<i>n</i></span> should be an instance of the <code>pyd.tuples.tuple</code> template (not an instance of the tuple struct <em>itself</em>, but an instance of the <em>template</em>), which in turn supports up to 10 arguments. Each tuple should correspond to a constructor. There is an additional limitation at this time: No two constructors may have the same number of arguments. Pyd will always attempt to call the first constructor with the right number of arguments. If you wish to support a constructor with default arguments, you must specify each possible constructor call as a different template argument to this function. The examples show a few uses of the <code>init</code> function.</dd>
</dl>

<p>Once you have called all of the member functions of <code>wrapped_class</code> that you wish to, you must issue a call to <code>finalize_class</code>.</p>

<p><code>void finalize_class(<span class="t_arg">CLS</span>) (<span class="t_arg">CLS</span> <span class="arg">cls</span>);</code></p>

<p>This does some final initialization of the class and then registers it with Python. Unlike calls to <a href="func_wrapping.html"><code>def</code></a>, calls to <code>finalize_class</code> must occur <em>after</em> calling <code>module_init</code>. The <span class="arg">cls</span> function argument should be an instance of <code>wrapped_class</code>.</p>

<p>If you ever wish to check whether a given class has been wrapped, Pyd helpfully registers all wrapped classes with the <code>is_wrapped</code> template, which is just a templated <code>bool</code>:</p>

<p><code>template is_wrapped(<span class="t_arg">T</span>);</code></p>

<p>If you have a class <code>Foo</code>, you can check whether it is wrapped by simply checking whether <code>is_wrapped!(Foo)</code> is true. It is important to note that this is <em>not</em> a <code>const bool</code>, it is a <em>runtime</em> check.</p>

<h3>Examples</h3>

<p>Suppose we have the following simple class:</p>

<pre class="code"><span class="keyword">import</span> std.stdio;

<span class="keyword">class</span> Foo {
<span class="keyword">int</span> m_i;

<span class="keyword">this</span>() { m_i = <span class="number">0</span>; }
<span class="keyword">this</span>(<span class="keyword">int</span> j) { m_i = j; }

<span class="keyword">int</span> i() { <span class="keyword">return</span> m_i; }
<span class="keyword">void</span> i(<span class="keyword">int</span> j) { m_i = j; }

<span class="keyword">void</span> foo(<span class="keyword">char</span>[] s) {
writefln(s, m_i);
}
}</pre>

<p>We would expose this class to Python by putting this code in our init function after the call to <code>module_init</code>:</p>

<pre class="code"><span class="comment">// Make an instance of wrapped_class</span>
wrapped_class!(Foo, <span class="string">"Foo"</span>) f;
<span class="comment">// Wrap the "foo" method</span>
f.def!(Foo.foo, <span class="string">"foo"</span>);
<span class="comment">// Wrap the "i" property</span>
f.prop!(Foo.i, <span class="string">"i"</span>);
<span class="comment">// Wrap the constructor.</span>
f.init!(tuple!(<span class="keyword">int</span>));
finalize_class(f);</pre>

<p>Now we can use this type from within Python like any other type.</p>

<pre class="code">&gt;&gt;&gt; from testmodule import Foo
&gt;&gt;&gt; f = Foo()
&gt;&gt;&gt; f.i
0
&gt;&gt;&gt; f.i = 20
&gt;&gt;&gt; f.foo("Hello! i is ")
Hello! i is 20
&gt;&gt;&gt; g = Foo(30)
&gt;&gt;&gt; g.i
30
&gt;&gt;&gt; # We can even subclass our D type
&gt;&gt;&gt; class MyFoo(Foo):
... def bar(self):
... print "Hey, i+3 is", self.i + 3
...
&gt;&gt;&gt; h = MyFoo(3)
&gt;&gt;&gt; h.bar()
Hey, i+3 is 6
&gt;&gt;&gt; </pre>

</body>
</html>

2 changes: 1 addition & 1 deletion html_doc/conversion.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
</head>

<body>
<div class="nav"><a class="nav" href="index.html">Main</a> | <a class="nav" href="celerid.html">CeleriD</a> | <a class="navcur" href="conversion.html">Type conversion</a> | <a class="nav" href="func_wrapping.html">Function wrapping</a> | <a class="nav" href="class_wrapping.html">Class wrapping</a> | <a class="nav" href="except_wrapping.html">Exception wrapping</a></div>
<div class="nav"><a class="nav" href="index.html">Main</a> | <a class="nav" href="celerid.html">CeleriD</a> | <a class="navcur" href="conversion.html">Type conversion</a> | <a class="nav" href="func_wrapping.html">Function wrapping</a> | <a class="nav" href="class_wrapping.html">Class wrapping</a> | <a class="nav" href="except_wrapping.html">Exception wrapping</a> | <a class="nav" href="dpyobject.html">DPyObject</a></div>

<h1>Type conversion</h1>

Expand Down
77 changes: 36 additions & 41 deletions html_doc/dpyobject.html
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,18 @@
<html><head>
<META http-equiv="content-type" content="text/html; charset=utf-8">
<title>pyd.dpyobject</title>
</head><body>
<h1>pyd.dpyobject</h1>
<!-- Generated by Ddoc from pyd\dpyobject.d -->
<br><br>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<link href="pyd.css" rel="stylesheet" type="text/css">
<title>pyd.dpyobject</title>
</head>

<body>
<div class="nav"><a class="nav" href="index.html">Main</a> | <a class="nav" href="celerid.html">CeleriD</a> | <a class="nav" href="conversion.html">Type conversion</a> | <a class="nav" href="func_wrapping.html">Function wrapping</a> | <a class="nav" href="class_wrapping.html">Class wrapping</a> | <a class="nav" href="except_wrapping.html">Exception wrapping</a> | <a class="navcur" href="dpyobject.html">DPyObject</a></div>

<h1>pyd.dpyobject</h1>
<!-- Generated by Ddoc from pyd\dpyobject.d -->
<p>The DPyObject class wraps a PyObject*, using the D garbage collector to handle the reference count so that you don't have to. It also overloads quite a lot of operators, and tries to make using Python objects in D code as much like using them in Python as possible. However, it is incomplete (the function and method call methods in particular need work, and there are a number of helper functions that need to be written), and remains a work in progress.</p>

<dl><dt><big>class <u>DPyObject</u>;
</big></dt>
<dd>Wrapper class for a Python/C API PyObject.
Expand All @@ -14,10 +22,7 @@ <h1>pyd.dpyobject</h1>

<br><br>
<b>Authors:</b><br>
<a href="mailto:[email protected]">Kirk McDonald</a>
<br><br>
<b>Date:</b><br>
June 18, 2006
Kirk McDonald
<br><br>
<b>See Also:</b><br>
<a href="http://docs.python.org/api/api.html">The Python/C API</a>
Expand All @@ -29,35 +34,23 @@ <h1>pyd.dpyobject</h1>
<dd>Wrap around a passed PyObject*.
<br><br>
<b>Params:</b><br>
<table><tr><td>PyObject * <i>o</i></td>
<td>The PyObject to wrap.</td></tr>
<tr><td>bool <i>borrowed</i></td>
<td>Whether <i>o</i> is a borrowed reference. Instances
<table>
<tr><td>PyObject * <i>o</i></td> <td>The PyObject to wrap.</td></tr>
<tr><td>bool <i>borrowed</i></td> <td>Whether <i>o</i> is a borrowed reference. Instances
of DPyObject always own their references.
Therefore, Py_INCREF will be called if <i>borrowed</i> is
<font color=blue><b>true</b></font>.</td></tr>
</table><br>
true.</td></tr>
</table><br /></dd>

</dd>
<dt><big>this();
</big></dt>
<dd>The default constructor constructs an instance of the Py_None DPyObject.
<br><br>
<dt><big>this();</big></dt>
<dd>The default constructor constructs an instance of the Py_None DPyObject.<br /><br /></dd>

</dd>
<dt><big>PyObject * <u>ptr</u>();
</big></dt>
<dd>Returns a borrowed reference to the PyObject.

<br><br>
<dt><big>PyObject * <u>ptr</u>();</big></dt>
<dd>Returns a borrowed reference to the PyObject.<br><br></dd>

</dd>
<dt><big>bool <u>hasattr</u>(char[] <i>attr_name</i>);
</big></dt>
<dd>Same as hasattr(this, <i>attr_name</i>) in Python.
<br><br>
<dt><big>bool <u>hasattr</u>(char[] <i>attr_name</i>);</big></dt>
<dd>Same as hasattr(this, <i>attr_name</i>) in Python.<br><br></dd>

</dd>
<dt><big>bool <u>hasattr</u>(DPyObject <i>attr_name</i>);
</big></dt>
<dd>Same as hasattr(this, <i>attr_name</i>) in Python.
Expand Down Expand Up @@ -160,9 +153,9 @@ <h1>pyd.dpyobject</h1>
<br><br>

</dd>
<dt><big>DPyObject <u>opCall</u>(DPyObject <i>args</i> = cast(DPyObject)null);
<dt><big>DPyObject <u>opCall</u>(DPyObject <i>args</i> = null);
</big></dt>
<dd>Calls the DPyObject.
<dd>Calls the DPyObject. <strong>(Note: The opCall functions will be changing in the future to something more useful.)</strong>
<br><br>
<b>Params:</b><br>
<table><tr><td>DPyObject <i>args</i></td>
Expand Down Expand Up @@ -192,7 +185,7 @@ <h1>pyd.dpyobject</h1>
<br><br>

</dd>
<dt><big>DPyObject <u>method</u>(char[] <i>name</i>, DPyObject <i>args</i> = cast(DPyObject)null);
<dt><big>DPyObject <u>method</u>(char[] <i>name</i>, DPyObject <i>args</i> = null);
</big></dt>
<dd><br><br>
</dd>
Expand Down Expand Up @@ -397,7 +390,7 @@ <h1>pyd.dpyobject</h1>
</big></dt>
<dd><br><br>
</dd>
<dt><big>DPyObject <u>pow</u>(DPyObject <i>o1</i>, DPyObject <i>o2</i> = cast(DPyObject)null);
<dt><big>DPyObject <u>pow</u>(DPyObject <i>o1</i>, DPyObject <i>o2</i> = null);
</big></dt>
<dd><br><br>
</dd>
Expand Down Expand Up @@ -467,7 +460,7 @@ <h1>pyd.dpyobject</h1>
</big></dt>
<dd><br><br>
</dd>
<dt><big>DPyObject <u>powAssign</u>(DPyObject <i>o1</i>, DPyObject <i>o2</i> = cast(DPyObject)null);
<dt><big>DPyObject <u>powAssign</u>(DPyObject <i>o1</i>, DPyObject <i>o2</i> = null);
</big></dt>
<dd><br><br>
</dd>
Expand Down Expand Up @@ -591,5 +584,7 @@ <h1>pyd.dpyobject</h1>
</dd>
</dl>

<hr><small>Page generated by <a href="http://www.digitalmars.com/d/ddoc.html">Ddoc</a>. </small>
</body></html>
<hr />
<small>Page generated by <a href="http://www.digitalmars.com/d/ddoc.html">Ddoc</a>.</small>
</body>
</html>
2 changes: 1 addition & 1 deletion html_doc/except_wrapping.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
</head>

<body>
<div class="nav"><a class="nav" href="index.html">Main</a> | <a class="nav" href="celerid.html">CeleriD</a> | <a class="nav" href="conversion.html">Type conversion</a> | <a class="nav" href="func_wrapping.html">Function wrapping</a> | <a class="nav" href="class_wrapping.html">Class wrapping</a> | <a class="navcur" href="except_wrapping.html">Exception wrapping</a></div>
<div class="nav"><a class="nav" href="index.html">Main</a> | <a class="nav" href="celerid.html">CeleriD</a> | <a class="nav" href="conversion.html">Type conversion</a> | <a class="nav" href="func_wrapping.html">Function wrapping</a> | <a class="nav" href="class_wrapping.html">Class wrapping</a> | <a class="navcur" href="except_wrapping.html">Exception wrapping</a> | <a class="nav" href="dpyobject.html">DPyObject</a></div>

<h1>Exception wrapping</h1>

Expand Down
4 changes: 2 additions & 2 deletions html_doc/func_wrapping.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
</head>

<body>
<div class="nav"><a class="nav" href="index.html">Main</a> | <a class="nav" href="celerid.html">CeleriD</a> | <a class="nav" href="conversion.html">Type conversion</a> | <a class="navcur" href="func_wrapping.html">Function wrapping</a> | <a class="nav" href="class_wrapping.html">Class wrapping</a> | <a class="nav" href="except_wrapping.html">Exception wrapping</a></div>
<div class="nav"><a class="nav" href="index.html">Main</a> | <a class="nav" href="celerid.html">CeleriD</a> | <a class="nav" href="conversion.html">Type conversion</a> | <a class="navcur" href="func_wrapping.html">Function wrapping</a> | <a class="nav" href="class_wrapping.html">Class wrapping</a> | <a class="nav" href="except_wrapping.html">Exception wrapping</a> | <a class="nav" href="dpyobject.html">DPyObject</a></div>

<h1>Function wrapping</h1>

Expand All @@ -21,7 +21,7 @@ <h1>Function wrapping</h1>
<li><span class="t_arg">MIN_ARGS</span> is the minimum number of arguments this function can accept. It is used when a function has default arguments. The <code>MIN_ARGS</code> template can derive the correct number automatically, so you typically won't specify this manually.</li>
</ul>

<p>Any function whose return type and arguments are <a href="conversion.html">convertable</a> can be wrapped by <code>def</code>. <code>def</code> also provides support for wrapping overloaded functions as well as functions with default arguments. Here are some examples:</p>
<p>All calls to <code>def</code> must occur <em>before</em> calling <code>module_init</code>. Any function whose return type and arguments are <a href="conversion.html">convertable</a> can be wrapped by <code>def</code>. <code>def</code> also provides support for wrapping overloaded functions as well as functions with default arguments. Here are some examples:</p>

<pre class="code"><span class="keyword">import</span> pyd.pyd;
<span class="keyword">import</span> std.stdio;
Expand Down
2 changes: 1 addition & 1 deletion html_doc/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
</head>

<body>
<div class="nav"><a class="navcur" href="index.html">Main</a> | <a class="nav" href="celerid.html">CeleriD</a> | <a class="nav" href="conversion.html">Type conversion</a> | <a class="nav" href="func_wrapping.html">Function wrapping</a> | <a class="nav" href="class_wrapping.html">Class wrapping</a> | <a class="nav" href="except_wrapping.html">Exception wrapping</a></div>
<div class="nav"><a class="navcur" href="index.html">Main</a> | <a class="nav" href="celerid.html">CeleriD</a> | <a class="nav" href="conversion.html">Type conversion</a> | <a class="nav" href="func_wrapping.html">Function wrapping</a> | <a class="nav" href="class_wrapping.html">Class wrapping</a> | <a class="nav" href="except_wrapping.html">Exception wrapping</a> | <a class="nav" href="dpyobject.html">DPyObject</a></div>

<h1>Pyd</h1>
<p>Pyd is a library for D that wraps the raw <a href="http://docs.python.org/api/api.html">Python/C API</a> with a cleaner, simpler interface. It makes exposing raw D functions and classes to Python almost trivially simple. It bears certain similarities to <a href="http://www.boost.org/libs/python/doc/">Boost.Python</a>, and indeed Boost.Python is a major influence on Pyd.</p>
Expand Down
2 changes: 1 addition & 1 deletion infrastructure/build_wiki_ddoc.bat
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
C:\dmd\dmd\bin\dmd.exe -o- -Ddpyd\wiki_doc pyd\class_wrap.d pyd\ctor_wrap.d pyd\def.d pyd\dg_convert.d pyd\exception.d pyd\ftype.d pyd\make_object.d pyd\dpyobject.d pyd\pyd.d -Ipython\headers
C:\dmd\dmd\bin\dmd.exe -o- -Ddpyd\wiki_doc pyd\class_wrap.d pyd\ctor_wrap.d pyd\def.d pyd\dg_convert.d pyd\dpyobject.d pyd\exception.d pyd\ftype.d pyd\make_object.d pyd\op_wrap.d pyd\pyd.d pyd\tuples.d -Ipython\headers

pause
18 changes: 17 additions & 1 deletion infrastructure/pyd/wiki_doc/wiki_doc/wikidoc.ddoc
View file
Original file line number Diff line number Diff line change
@@ -1,2 +1,18 @@
DDOC = <h1>$(TITLE)</h1>
DDOC = <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<link href="pyd.css" rel="stylesheet" type="text/css">
<title>$(TITLE)</title>
</head>

<body>
<div class="nav"><a class="nav" href="index.html">Main</a> | <a class="nav" href="celerid.html">CeleriD</a> | <a class="nav" href="conversion.html">Type conversion</a> | <a class="nav" href="func_wrapping.html">Function wrapping</a> | <a class="nav" href="class_wrapping.html">Class wrapping</a> | <a class="nav" href="except_wrapping.html">Exception wrapping</a></div>

<h1>$(TITLE)</h1>

$(BODY)
</body>
</html>


0 comments on commit 415cf00

Please sign in to comment.