1
2
3<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
4  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5
6
7<html xmlns="http://www.w3.org/1999/xhtml">
8  <head>
9    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
10    
11    <title>An introduction to PyObjC &mdash; PyObjC-Core 2.5.0b1 documentation</title>
12    
13    <link rel="stylesheet" href="_static/default.css" type="text/css" />
14    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
15    
16    <script type="text/javascript">
17      var DOCUMENTATION_OPTIONS = {
18        URL_ROOT:    '',
19        VERSION:     '2.5.0b1',
20        COLLAPSE_INDEX: false,
21        FILE_SUFFIX: '.html',
22        HAS_SOURCE:  true
23      };
24    </script>
25    <script type="text/javascript" src="_static/jquery.js"></script>
26    <script type="text/javascript" src="_static/underscore.js"></script>
27    <script type="text/javascript" src="_static/doctools.js"></script>
28    <link rel="top" title="PyObjC-Core 2.5.0b1 documentation" href="index.html" />
29    <link rel="next" title="PyObjC Tutorials" href="tutorials/index.html" />
30    <link rel="prev" title="Welcome to PyObjC-Core’s documentation!" href="index.html" /> 
31  </head>
32  <body>
33    <div class="related">
34      <h3>Navigation</h3>
35      <ul>
36        <li class="right" style="margin-right: 10px">
37          <a href="genindex.html" title="General Index"
38             accesskey="I">index</a></li>
39        <li class="right" >
40          <a href="py-modindex.html" title="Python Module Index"
41             >modules</a> |</li>
42        <li class="right" >
43          <a href="tutorials/index.html" title="PyObjC Tutorials"
44             accesskey="N">next</a> |</li>
45        <li class="right" >
46          <a href="index.html" title="Welcome to PyObjC-Core’s documentation!"
47             accesskey="P">previous</a> |</li>
48        <li><a href="index.html">PyObjC-Core 2.5.0b1 documentation</a> &raquo;</li> 
49      </ul>
50    </div>  
51
52    <div class="document">
53      <div class="documentwrapper">
54        <div class="bodywrapper">
55          <div class="body">
56            
57  <div class="section" id="an-introduction-to-pyobjc">
58<h1>An introduction to PyObjC<a class="headerlink" href="#an-introduction-to-pyobjc" title="Permalink to this headline">¶</a></h1>
59<div class="section" id="preface">
60<h2>Preface<a class="headerlink" href="#preface" title="Permalink to this headline">¶</a></h2>
61<p>PyObjC is a bridge between Python and Objective-C.  It allows Python
62scripts to use and extend existing Objective-C class libraries;
63most importantly the <a class="reference external" href="https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/CocoaFundamentals/Introduction/Introduction.html#//apple_ref/doc/uid/TP40002974">Cocoa libraries</a> by <a class="reference external" href="http://www.apple.com/">Apple</a>.</p>
64<p>This document describes how to use Objective-C class libraries from Python
65scripts and how to interpret the documentation of those libraries from the
66point of view of a Python programmer.</p>
67</div>
68<div class="section" id="first-steps">
69<h2>First Steps<a class="headerlink" href="#first-steps" title="Permalink to this headline">¶</a></h2>
70<p>When dealing with the Objective-C runtime, there are certain patterns
71you need to learn when writing Python code.  If you&#8217;re not already an
72Objective-C programmer, some of them will seem strange or even
73&#8220;un-pythonic&#8221; at first.  However, you will get used to it, and the way
74that PyObjC works is quite compliant with the <span class="target" id="index-0"></span><a class="pep reference external" href="http://www.python.org/dev/peps/pep-0020"><strong>PEP 20</strong></a> (the Zen of Python,
75<tt class="docutils literal"><span class="pre">import</span> <span class="pre">this</span></tt>).  In fact, Ronald is Dutch ;)</p>
76<p>With no further ado, here are the three most important things you
77<em>must</em> know before embarking on any PyObjC voyage:</p>
78<div class="section" id="underscores-and-lots-of-them">
79<h3>Underscores, and lots of them<a class="headerlink" href="#underscores-and-lots-of-them" title="Permalink to this headline">¶</a></h3>
80<p>Objective-C objects communicate with each other by sending messages.
81The syntax for messages is somewhere in-between Python&#8217;s positional and
82keyword arguments.  Specificlaly, Objective-C message dispatch uses
83positional arguments, but parts of the message name (called &#8220;selector&#8221;
84in Objective-C terminology) are interleaved with the arguments.</p>
85<p>An Objective-C message looks like this:</p>
86<blockquote>
87<div><div class="highlight-objective-c"><div class="highlight"><pre><span class="p">[</span><span class="n">someObject</span> <span class="nl">doSomething:</span><span class="n">arg1</span> <span class="nl">withSomethingElse:</span><span class="n">arg2</span><span class="p">];</span>
88</pre></div>
89</div>
90</div></blockquote>
91<p>The selector (message name) for the above snippet is this (note the colons):</p>
92<blockquote>
93<div><div class="highlight-objective-c"><div class="highlight"><pre><span class="nl">doSomething:withSomethingElse:</span>
94</pre></div>
95</div>
96</div></blockquote>
97<p>In order to have a lossless and unambiguous translation between Objective-C
98messages and Python methods, the Python method name equivalent is simply
99the selector with colons replaced by underscores.  Since each colon in an
100Objective-C selector is a placeholder for an argument, the number of
101underscores in the PyObjC-ified method name is the number of arguments
102that should be given.</p>
103<p>The PyObjC translation of the above selector is (note the underscores):</p>
104<blockquote>
105<div><div class="highlight-python"><div class="highlight"><pre><span class="n">doSomething_withSomethingElse_</span>
106</pre></div>
107</div>
108</div></blockquote>
109<p>The message dispatch, translated to PyObjC, looks like this:</p>
110<blockquote>
111<div><div class="highlight-python"><div class="highlight"><pre><span class="n">someObject</span><span class="o">.</span><span class="n">doSomething_withSomethingElse_</span><span class="p">(</span><span class="n">arg1</span><span class="p">,</span> <span class="n">arg2</span><span class="p">)</span>
112</pre></div>
113</div>
114</div></blockquote>
115<p><em>Methods that take one argument will have a trailing underscore</em>.</p>
116<p>It may take a little while to get used to, but PyObjC does not ever
117rename selectors.  The trailing underscore will seem strange at first,
118especially for cases like this:</p>
119<blockquote>
120<div><div class="highlight-python"><div class="highlight"><pre><span class="c"># note the trailing underscore</span>
121<span class="n">someObject</span><span class="o">.</span><span class="n">setValue_</span><span class="p">(</span><span class="n">aValue</span><span class="p">)</span>
122</pre></div>
123</div>
124</div></blockquote>
125<p>There are a few additional rules regarding message dispatch, see the
126<a class="reference internal" href="#overview-of-the-bridge">Overview of the bridge</a> for the complete rundown.</p>
127</div>
128<div class="section" id="two-phase-instantiation">
129<h3>Two-phase instantiation<a class="headerlink" href="#two-phase-instantiation" title="Permalink to this headline">¶</a></h3>
130<p>Objective-C, being a low-level runtime, separates the two concepts required
131to instantiate an object.</p>
132<dl class="docutils">
133<dt>allocation:</dt>
134<dd>Reserve a chunk of memory large enough to hold the new object, and make
135sure that all of its declared instance variables are set to &#8220;zero&#8221;
136(this means nil pointers to objects, 0 for integers, etc.).</dd>
137<dt>initialization:</dt>
138<dd>Fill in the blank slate allocated by the allocation phase.</dd>
139</dl>
140<p>In Objective-C, the convention is for allocation to be performed by a class
141method called <tt class="docutils literal"><span class="pre">alloc</span></tt>, and initialization is done with method
142<em>beginning with</em> the word <tt class="docutils literal"><span class="pre">init</span></tt>.  For example, here is the syntax for
143instantiating an <tt class="docutils literal"><span class="pre">NSObject</span></tt>:</p>
144<blockquote>
145<div><div class="highlight-python"><div class="highlight"><pre><span class="n">myObject</span> <span class="o">=</span> <span class="n">NSObject</span><span class="o">.</span><span class="n">alloc</span><span class="p">()</span><span class="o">.</span><span class="n">init</span><span class="p">()</span>
146</pre></div>
147</div>
148</div></blockquote>
149<p>And here is an example for creating an <tt class="docutils literal"><span class="pre">NSData</span></tt> instance given a few bytes:</p>
150<blockquote>
151<div><div class="highlight-python"><div class="highlight"><pre><span class="n">myData</span> <span class="o">=</span> <span class="n">NSData</span><span class="o">.</span><span class="n">alloc</span><span class="p">()</span><span class="o">.</span><span class="n">initWithBytes_length_</span><span class="p">(</span><span class="s">&#39;the bytes&#39;</span><span class="p">,</span> <span class="mi">9</span><span class="p">)</span>
152</pre></div>
153</div>
154</div></blockquote>
155<p>You must also follow this convention when subclassing Objective-C classes.
156When initializing, an object must always (directly or indirectly) call the
157designated initializer of its <tt class="docutils literal"><span class="pre">super</span></tt>.  The designated initializer is the
158&#8220;most basic&#8221; initializer through which all initialization eventually ends up.
159The designated initializer for <tt class="docutils literal"><span class="pre">NSObject</span></tt> is <tt class="docutils literal"><span class="pre">init</span></tt>.  To find the
160designated initializer for other classes, consult the documentation for that
161class.  Here is an example of an <tt class="docutils literal"><span class="pre">NSObject</span></tt> subclass with a customized
162initialization phase:</p>
163<blockquote>
164<div><div class="highlight-python"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
165 2
166 3
167 4
168 5
169 6
170 7
171 8
172 9
17310
17411
17512
17613
17714
17815
17916
18017
18118
18219
18320
18421
18522
18623
18724
18825
18926
19027
19128
19229
19330
19431
19532
19633</pre></div></td><td class="code"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyClass</span><span class="p">(</span><span class="n">NSObject</span><span class="p">):</span>
197
198   <span class="k">def</span> <span class="nf">init</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
199       <span class="sd">&quot;&quot;&quot;</span>
200<span class="sd">       Designated initializer for MyClass</span>
201<span class="sd">       &quot;&quot;&quot;</span>
202       <span class="c"># ALWAYS call the super&#39;s designated initializer.</span>
203       <span class="c"># Also, make sure to re-bind &quot;self&quot; just in case it</span>
204       <span class="c"># returns something else, or even None!</span>
205       <span class="bp">self</span> <span class="o">=</span> <span class="nb">super</span><span class="p">(</span><span class="n">MyClass</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">init</span><span class="p">()</span>
206       <span class="k">if</span> <span class="bp">self</span> <span class="ow">is</span> <span class="bp">None</span><span class="p">:</span> <span class="k">return</span> <span class="bp">None</span>
207
208       <span class="bp">self</span><span class="o">.</span><span class="n">myVariable</span> <span class="o">=</span> <span class="mi">10</span>
209
210       <span class="c"># Unlike Python&#39;s __init__, initializers MUST return self,</span>
211       <span class="c"># because they are allowed to return any object!</span>
212       <span class="k">return</span> <span class="bp">self</span>
213
214
215<span class="k">class</span> <span class="nc">MyOtherClass</span><span class="p">(</span><span class="n">MyClass</span><span class="p">):</span>
216
217   <span class="k">def</span> <span class="nf">initWithOtherVariable_</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">otherVariable</span><span class="p">):</span>
218       <span class="sd">&quot;&quot;&quot;</span>
219<span class="sd">       Designated initializer for MyOtherClass</span>
220<span class="sd">       &quot;&quot;&quot;</span>
221       <span class="bp">self</span> <span class="o">=</span> <span class="nb">super</span><span class="p">(</span><span class="n">MyOtherClass</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">init</span><span class="p">()</span>
222       <span class="k">if</span> <span class="bp">self</span> <span class="ow">is</span> <span class="bp">None</span><span class="p">:</span> <span class="k">return</span> <span class="bp">None</span>
223
224       <span class="bp">self</span><span class="o">.</span><span class="n">otherVariable</span> <span class="o">=</span> <span class="n">otherVariable</span>
225       <span class="k">return</span> <span class="bp">self</span>
226
227<span class="n">myInstance</span> <span class="o">=</span> <span class="n">MyClass</span><span class="o">.</span><span class="n">alloc</span><span class="p">()</span><span class="o">.</span><span class="n">init</span><span class="p">()</span>
228<span class="n">myOtherInstance</span> <span class="o">=</span> <span class="n">MyOtherClass</span><span class="o">.</span><span class="n">alloc</span><span class="p">()</span><span class="o">.</span><span class="n">initWithOtherVariable_</span><span class="p">(</span><span class="mi">20</span><span class="p">)</span>
229</pre></div>
230</td></tr></table></div>
231</div></blockquote>
232<p>Many Objective-C classes provide class methods that perform two-phase
233instantiation for you in one step.  Several examples of this are:</p>
234<blockquote>
235<div><div class="highlight-python"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
236 2
237 3
238 4
239 5
240 6
241 7
242 8
243 9
24410
24511
24612
24713
24814
24915
25016
25117</pre></div></td><td class="code"><div class="highlight"><pre><span class="c"># This is equivalent to:</span>
252<span class="c">#</span>
253<span class="c">#   myObject = NSObject.alloc().init()</span>
254<span class="c">#</span>
255<span class="n">myObject</span> <span class="o">=</span> <span class="n">NSObject</span><span class="o">.</span><span class="n">new</span><span class="p">()</span>
256
257<span class="c"># This is equivalent to:</span>
258<span class="c">#</span>
259<span class="c">#   myDict = NSDictionary.alloc().init()</span>
260<span class="c">#</span>
261<span class="n">myDict</span> <span class="o">=</span> <span class="n">NSDictionary</span><span class="o">.</span><span class="n">dictionary</span><span class="p">()</span>
262
263<span class="c"># This is equivalent to:</span>
264<span class="c">#</span>
265<span class="c">#   myString = NSString.alloc().initWithString_(u&#39;my string&#39;)</span>
266<span class="c">#</span>
267<span class="n">myString</span> <span class="o">=</span> <span class="n">NSString</span><span class="o">.</span><span class="n">stringWithString_</span><span class="p">(</span><span class="s">u&#39;my string&#39;</span><span class="p">)</span>
268</pre></div>
269</td></tr></table></div>
270</div></blockquote>
271</div>
272<div class="section" id="objective-c-uses-accessors-everywhere">
273<h3>Objective-C uses accessors everywhere<a class="headerlink" href="#objective-c-uses-accessors-everywhere" title="Permalink to this headline">¶</a></h3>
274<p>Unlike Python, Objective-C convention says to use accessors rather than
275directly accessing instance variables of other objects.  This means
276that in order to access an instance variable <tt class="docutils literal"><span class="pre">value</span></tt> of an object
277<tt class="docutils literal"><span class="pre">valueContainer</span></tt> you will have to use the following syntax:</p>
278<blockquote>
279<div><div class="highlight-python"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
280 2
281 3
282 4
283 5
284 6
285 7
286 8
287 9
28810
28911</pre></div></td><td class="code"><div class="highlight"><pre><span class="c"># Getting</span>
290<span class="c">#</span>
291<span class="c"># notice the method call</span>
292<span class="c">#</span>
293<span class="n">myValue</span> <span class="o">=</span> <span class="n">valueContainer</span><span class="o">.</span><span class="n">value</span><span class="p">()</span>
294
295<span class="c"># Setting</span>
296<span class="c">#</span>
297<span class="c"># notice the naming convention and trailing underscore</span>
298<span class="c">#</span>
299<span class="n">valueContainer</span><span class="o">.</span><span class="n">setValue_</span><span class="p">(</span><span class="n">myNewValue</span><span class="p">)</span>
300</pre></div>
301</td></tr></table></div>
302</div></blockquote>
303<p>When writing your own classes from Python, this is a bit harder since
304Python only has one namespace for all attributes, even methods.  If you
305choose to implement accessors from Python, then you will have to name
306the instance variable something else:</p>
307<blockquote>
308<div><div class="highlight-python"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
309 2
310 3
311 4
312 5
313 6
314 7
315 8
316 9
31710
31811
31912
32013
32114
32215
32316</pre></div></td><td class="code"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyValueHolder</span><span class="p">(</span><span class="n">NSObject</span><span class="p">):</span>
324
325    <span class="k">def</span> <span class="nf">initWithValue_</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>
326        <span class="bp">self</span> <span class="o">=</span> <span class="nb">super</span><span class="p">(</span><span class="n">MyValueHolder</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">init</span><span class="p">()</span>
327        <span class="c"># It&#39;s recommended not to use typical Python convention here,</span>
328        <span class="c"># as instance variables prefixed with underscores are reserved</span>
329        <span class="c"># by the Objective-C runtime.  It still works if you use</span>
330        <span class="c"># underscores, however.</span>
331        <span class="bp">self</span><span class="o">.</span><span class="n">ivar_value</span> <span class="o">=</span> <span class="n">value</span>
332        <span class="k">return</span> <span class="bp">self</span>
333
334    <span class="k">def</span> <span class="nf">value</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
335        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">ivar_value</span>
336
337    <span class="k">def</span> <span class="nf">setValue_</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>
338        <span class="bp">self</span><span class="o">.</span><span class="n">ivar_value</span> <span class="o">=</span> <span class="n">value</span>
339</pre></div>
340</td></tr></table></div>
341</div></blockquote>
342<p>It&#8217;s also possible to use <a class="reference external" href="https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/KeyValueCoding/Articles/KeyValueCoding.html">Key-Value Coding</a> in some cases, which eliminates
343the need for writing most accessors, but only in scenarios where the rest of
344the code is using it.</p>
345</div>
346</div>
347<div class="section" id="objective-c-for-pyobjc-users">
348<h2>Objective-C for PyObjC users<a class="headerlink" href="#objective-c-for-pyobjc-users" title="Permalink to this headline">¶</a></h2>
349<p>It is recommended that you take the time to understand a little bit about
350Objective-C before jumping into PyObjC development.  The class libraries
351that you will be using from Cocoa are not documented in Python, and their
352documentation will be confusing without a grasp on the semantics and syntax
353of Objective-C.</p>
354<p>Objective-C is an object-oriented programming language implemented as a
355superset of C that borrows heavily in concept and syntax from Smalltalk.
356of C and borrows heavily from Smalltalk.  It features single inheritance with
357dynamic dispatch and (in theory) multiple root classes.  This is basically the
358same as Python with single inheritance.</p>
359<p>An important difference between Python and Objective-C is that the latter is
360not a pure object-oriented language.  Some values are not objects, but values
361of plain C types, such as <tt class="docutils literal"><span class="pre">int</span></tt> and <tt class="docutils literal"><span class="pre">double</span></tt>.  These basic C types can
362be used as the types of arguments and the return value of methods.</p>
363<p>Object allocation and initialization are explicit and separate actions in
364Objective-C.  The former is done by the class-method <tt class="docutils literal"><span class="pre">alloc</span></tt>, while the
365latter is done by instance methods whose name customarily starts with <tt class="docutils literal"><span class="pre">init</span></tt>.</p>
366<p>Objective-C code looks just like plain C code, with some easily recognizable
367Smalltalk-like extensions for the object-oriented parts of the language.  An
368example class declaration (usually found in <tt class="docutils literal"><span class="pre">.h</span></tt> files) and implementation
369(usually found in <tt class="docutils literal"><span class="pre">.m</span></tt> files) are listed below.  Class declarations are easily
370recognized as blocks of code between <tt class="docutils literal"><span class="pre">&#64;interface</span></tt> and <tt class="docutils literal"><span class="pre">&#64;end</span></tt>, and similarly
371the implementation is between <tt class="docutils literal"><span class="pre">&#64;implementation</span></tt> and <tt class="docutils literal"><span class="pre">&#64;end</span></tt>.  An expression
372enclosed in brackets in Objective-C is called a message, and is the equivalent
373to an instance method invocation in Python.  For example, this Objective-C
374code:</p>
375<blockquote>
376<div><div class="highlight-objective-c"><div class="highlight"><pre><span class="p">[</span><span class="n">aMutableArray</span> <span class="nl">addObject:</span><span class="s">@&quot;constant string&quot;</span><span class="p">];</span>
377</pre></div>
378</div>
379</div></blockquote>
380<p>Is equivalent in intent to the following in Python:</p>
381<blockquote>
382<div><div class="highlight-python"><div class="highlight"><pre><span class="n">aList</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s">u&quot;constant string&quot;</span><span class="p">)</span>
383</pre></div>
384</div>
385</div></blockquote>
386<p>Objective-C messages have three components: a target, a selector, and zero or
387more arguments.  The target, <tt class="docutils literal"><span class="pre">aMutableArray</span></tt>, is the object or class
388receiving the message.  The selector, <tt class="docutils literal"><span class="pre">addObject:</span></tt> uniquely identifies the
389kind of message that is being sent.  Finally, the arguments,
390<tt class="docutils literal"><span class="pre">&#64;&quot;constant</span> <span class="pre">string&quot;</span></tt> are used by the implementation of the method upon
391receipt of the message.  The syntax of Objective-C message dispatch is
392deceptively similar to keyword arguments in Python, but they are actually
393quite different.  Objective-C messages can not have default arguments, and all
394arguments are passed in a specific order.  The components of a selector may not
395be reordered.  Syntactically, one argument must be interleaved at every colon in
396the selector.  The message:</p>
397<blockquote>
398<div><div class="highlight-objective-c"><div class="highlight"><pre><span class="p">[</span><span class="n">anArray</span> <span class="nl">indexOfObject:</span><span class="n">someObject</span> <span class="nl">inRange:</span><span class="n">someRange</span><span class="p">]</span>
399</pre></div>
400</div>
401</div></blockquote>
402<dl class="docutils">
403<dt>Target:</dt>
404<dd><tt class="docutils literal"><span class="pre">anArray</span></tt></dd>
405<dt>Selector:</dt>
406<dd><tt class="docutils literal"><span class="pre">indexOfObject:inRange:</span></tt></dd>
407<dt>Arguments:</dt>
408<dd><tt class="docutils literal"><span class="pre">someObject</span></tt>, <tt class="docutils literal"><span class="pre">someRange</span></tt></dd>
409</dl>
410<p>As documented later, the straightforward translation of such a message to
411Python is:</p>
412<blockquote>
413<div><div class="highlight-python"><div class="highlight"><pre><span class="n">anArray</span><span class="o">.</span><span class="n">indexOfObject_inRange_</span><span class="p">(</span><span class="n">someObject</span><span class="p">,</span> <span class="n">someRange</span><span class="p">)</span>
414</pre></div>
415</div>
416</div></blockquote>
417<p>This may be awkward and &#8220;unpythonic&#8221; at first, however this syntax is necessary
418to preserve the semantics of Objective-C message dispatch.</p>
419<p>A class declaration:</p>
420<blockquote>
421<div><div class="highlight-objective-c"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
422 2
423 3
424 4
425 5
426 6
427 7
428 8
429 9
43010
43111
43212
43313
43414
43515
43616
43717
43818
43919</pre></div></td><td class="code"><div class="highlight"><pre><span class="k">@interface</span> <span class="nc">MyClass</span> : <span class="nc">MySuperClass</span>
440<span class="p">{</span>
441    <span class="kt">id</span>  <span class="n">anInstanceVariable</span><span class="p">;</span>
442    <span class="kt">int</span> <span class="n">anotherInstanceVariable</span><span class="p">;</span>
443<span class="p">}</span>
444
445<span class="c1">// A class method that returns an initialized instance of this class.</span>
446<span class="c1">// Similar to an implementation of __call__ on the metaclass.</span>
447<span class="o">+</span><span class="nl">instanceWithObject:</span><span class="p">(</span><span class="kt">id</span><span class="p">)</span><span class="n">anObject</span> <span class="nl">andInteger:</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span><span class="n">anInteger</span><span class="p">;</span>
448
449<span class="c1">// An instance method, the designated initializer for MyClass.</span>
450<span class="c1">// Similar to an implementation of __new__ on MyClass.</span>
451<span class="k">-</span><span class="nf">initWithObject:</span><span class="p">(</span><span class="kt">id</span><span class="p">)</span><span class="nv">anObject</span> <span class="nf">andInteger:</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span><span class="nv">anInteger</span><span class="p">;</span>
452
453<span class="c1">// An accessor, instance variables (attributes) are in a separate</span>
454<span class="c1">// namespace and are considered &quot;private&quot; in Objective-C.  Conventionally,</span>
455<span class="c1">// there is nothing similar to this in Python.</span>
456<span class="k">-</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span><span class="nf">anotherInstanceVariable</span><span class="p">;</span>
457<span class="k">@end</span>
458</pre></div>
459</td></tr></table></div>
460</div></blockquote>
461<p>A class implementation:</p>
462<blockquote>
463<div><div class="highlight-objective-c"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
464 2
465 3
466 4
467 5
468 6
469 7
470 8
471 9
47210
47311
47412
47513
47614
47715
47816
47917
48018
48119
48220
48321
48422
48523
48624
48725
48826
48927
49028
49129
49230
49331
49432
49533
49634
49735
49836
49937
50038
50139
50240
50341
50442
50543
50644
50745
50846
50947
51048
51149
51250
51351
51452
51553
51654
51755
51856
51957
52058
52159
52260
52361
52462
52563
52664
52765
52866
52967
53068
53169
53270
53371
53472
53573
53674
53775
53876
53977
54078
54179
54280
54381
54482
54583
54684
54785
54886
54987
55088
55189</pre></div></td><td class="code"><div class="highlight"><pre><span class="k">@implementation</span> <span class="nc">MyClass</span>
552
553<span class="c1">// Note that a type is not declared for the return value.  Undeclared types</span>
554<span class="c1">// are assumed to be &quot;id&quot;, which means any kind of instance.</span>
555<span class="k">+</span><span class="nf">instanceWithObject:</span><span class="p">(</span><span class="kt">id</span><span class="p">)</span><span class="nv">anObject</span> <span class="nf">andInteger:</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span><span class="nv">anInteger</span>
556<span class="p">{</span>
557    <span class="c1">// 1. Create an instance of MyClass.</span>
558    <span class="c1">// 2. Initialize it with its designated initializer</span>
559    <span class="c1">//    &quot;initWithObject:andInteger:&quot;.</span>
560    <span class="c1">// 3. Autorelease it, so that it does not leak memory.</span>
561    <span class="c1">// 4. Return the new instance.</span>
562    <span class="c1">//</span>
563    <span class="c1">// NOTE:</span>
564    <span class="c1">//   By convention,initializers (such as +new, -init, -copy)</span>
565    <span class="c1">//   are the only methods that should return retained objects.</span>
566    <span class="c1">//</span>
567    <span class="c1">// NOTE:</span>
568    <span class="c1">//   Since this is a class method, &quot;self&quot; refers to the class!</span>
569    <span class="c1">//</span>
570    <span class="c1">// Very roughly similar to:</span>
571    <span class="c1">//   return self.__new__(anObject, anInteger)</span>
572    <span class="k">return</span> <span class="p">[[[</span><span class="n">self</span> <span class="n">alloc</span><span class="p">]</span> <span class="nl">initWithObject:</span><span class="n">anObject</span> <span class="nl">andInteger:</span><span class="n">anInteger</span><span class="p">]</span> <span class="n">autorelease</span><span class="p">];</span>
573<span class="p">}</span>
574
575<span class="c1">// Note that a type is not declared for the return value.  Undeclared types</span>
576<span class="c1">// are assumed to be &quot;id&quot;, which means any kind of instance.</span>
577<span class="k">-</span><span class="nf">initWithObject:</span><span class="p">(</span><span class="kt">id</span><span class="p">)</span><span class="nv">anObject</span> <span class="nf">andInteger:</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span><span class="nv">anInteger</span>
578<span class="p">{</span>
579    <span class="c1">// Call the designated initializer of the superclass.</span>
580    <span class="c1">// Similar to:</span>
581    <span class="c1">//     self = super(MyClass, self).__new__()</span>
582    <span class="n">self</span> <span class="o">=</span> <span class="p">[</span><span class="n">super</span> <span class="n">init</span><span class="p">];</span>
583
584    <span class="c1">// Bail if initialization of the superclass failed.</span>
585    <span class="c1">// Similar to:</span>
586    <span class="c1">//     if self is None:</span>
587    <span class="c1">//         return None</span>
588    <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">self</span><span class="p">)</span> <span class="p">{</span>
589        <span class="k">return</span> <span class="nb">nil</span><span class="p">;</span>
590    <span class="p">}</span>
591
592    <span class="c1">// Set the instance variable (attribute).  The argument must be</span>
593    <span class="c1">// retained, since it will persist as long as the instance does.</span>
594    <span class="c1">// Similar to:</span>
595    <span class="c1">//     # Reference counting is automatic in Python</span>
596    <span class="c1">//     self.anInstanceVariable = anObject</span>
597    <span class="n">anInstanceVariable</span> <span class="o">=</span> <span class="p">[</span><span class="n">anObject</span> <span class="n">retain</span><span class="p">];</span>
598
599    <span class="c1">// Set the other instance variable.  Note that since anInteger is</span>
600    <span class="c1">// a primitive &quot;C&quot; type, not an object, no reference counting takes</span>
601    <span class="c1">// place.</span>
602    <span class="c1">// Similar to:</span>
603    <span class="c1">//     # Everything is an object in Python</span>
604    <span class="c1">//     self.anotherInstanceVariable = anInteger</span>
605    <span class="n">anotherInstanceVariable</span> <span class="o">=</span> <span class="n">anInteger</span><span class="p">;</span>
606
607    <span class="c1">// Like __new__ in Python, initializers in Objective-C must</span>
608    <span class="c1">// explicitly return self.  Note that this is different from</span>
609    <span class="c1">// __init__.</span>
610    <span class="c1">// Similar to:</span>
611    <span class="c1">//     return self</span>
612    <span class="k">return</span> <span class="n">self</span><span class="p">;</span>
613<span class="p">}</span>
614
615
616<span class="c1">// an accessor, instance variables (attributes) are in a separate</span>
617<span class="c1">// namespace and are considered &quot;private&quot;</span>
618<span class="k">-</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span><span class="nf">anotherInstanceVariable</span>
619<span class="p">{</span>
620    <span class="k">return</span> <span class="n">anotherInstanceVariable</span><span class="p">;</span>
621<span class="p">}</span>
622
623<span class="c1">// Since objects were retained as instance variables on this object,</span>
624<span class="c1">// they must be freed when the object is.  This is similar to an</span>
625<span class="c1">// implementation of __del__ in Python.  Since Objective-C has no</span>
626<span class="c1">// cyclic garbage collection, this isn&#39;t discouraged like it is in</span>
627<span class="c1">// Python.</span>
628<span class="k">-</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="nf">dealloc</span>
629<span class="p">{</span>
630    <span class="c1">// Very roughly similar to:</span>
631    <span class="c1">//     del self.instanceVariable</span>
632    <span class="p">[</span><span class="n">instanceVariable</span> <span class="n">release</span><span class="p">];</span>
633
634    <span class="c1">// Very roughly similar to:</span>
635    <span class="c1">//     super(MyClass, self).__del__()</span>
636    <span class="p">[</span><span class="n">super</span> <span class="n">dealloc</span><span class="p">];</span>
637<span class="p">}</span>
638
639<span class="k">@end</span>
640</pre></div>
641</td></tr></table></div>
642</div></blockquote>
643<p>Objective-C also features exceptions, but they are typically only used for
644disaster recovery, not error handling, so you will not encounter them very
645often.  Read <a class="reference external" href="http://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/index.html">The Objective-C Programming Language</a> if you want to
646know more about exceptions in Objective-C.</p>
647<p>One thing to keep in mind when translating Objective-C snippets to Python is
648that any message can be sent to <tt class="docutils literal"><span class="pre">nil</span></tt>, and the return value of that message
649will be <tt class="docutils literal"><span class="pre">nil</span></tt>.  PyObjC translates <tt class="docutils literal"><span class="pre">nil</span></tt> to <tt class="docutils literal"><span class="pre">None</span></tt> when crossing the
650bridge, so any such attempt will raise an <tt class="docutils literal"><span class="pre">AttributeError</span></tt>.</p>
651<p>For more information about Objective-C see:</p>
652<ul class="simple">
653<li><a class="reference external" href="http://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/index.html">The Objective-C Programming Language</a> at <a class="reference external" href="http://www.apple.com/">Apple</a>.</li>
654</ul>
655</div>
656<div class="section" id="overview-of-the-bridge">
657<h2>Overview of the bridge<a class="headerlink" href="#overview-of-the-bridge" title="Permalink to this headline">¶</a></h2>
658<div class="section" id="classes">
659<h3>Classes<a class="headerlink" href="#classes" title="Permalink to this headline">¶</a></h3>
660<p>Objective-C classes are visible as (new-style) Python classes and can be
661subclassed just like normal Python classes.  All the usual introspection
662mechanisms work as well, as do <tt class="docutils literal"><span class="pre">__slots__</span></tt> and descriptors.  The major
663differences between normal Python classes and Objective-C classes are the way
664that instances are created and initialized, and the fact that Objective-C
665selectors look strange when translated to Python methods.</p>
666<p>Multiple inheritance may be used when subclassing an Objective-C class, so
667long as the Objective-C class is the first base class and there is only one
668Objective-C base class.  The Objective-C runtime does not support multiple
669inheritance.  These mix-in classes should not contain different
670implementations for Objective-C methods.  To achieve this behavior, Categories
671should be used instead.</p>
672<p>Another thing to keep in mind is that the names of Objective-C classes must
673be globally unique per process, including across Python modules.  That is,
674it is <em>not</em> possible to have two Python modules that define a class with the
675same name.  It is conventional to choose class names with a short prefix that
676uniquely identify your project or company.  For example, Apple uses <tt class="docutils literal"><span class="pre">NS</span></tt>
677as the prefix for all classes in the <a class="reference external" href="https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/CocoaFundamentals/Introduction/Introduction.html#//apple_ref/doc/uid/TP40002974">Cocoa libraries</a>.  Note that the <tt class="docutils literal"><span class="pre">NS</span></tt>
678prefix made much more sense when it was called NeXTstep, but persists to this
679day for compatibility reasons.</p>
680<p>As described in <a class="reference internal" href="#objective-c-for-pyobjc-users">Objective-C for PyObjC users</a> the creation of Objective-C
681objects is a two-stage process.  To initialize objects, first call a
682class method to allocate the memory (typically <tt class="docutils literal"><span class="pre">alloc</span></tt>), and then call an
683initializer (typically starts with <tt class="docutils literal"><span class="pre">init</span></tt>).  Some classes have class methods
684which perform this behind the scenes, especially classes that create cached,
685immutable, or singleton instances.</p>
686</div>
687<div class="section" id="messages-and-functions">
688<h3>Messages and Functions<a class="headerlink" href="#messages-and-functions" title="Permalink to this headline">¶</a></h3>
689<p>Objective-C methods are bridged to Python methods.  Because Objective-C
690message dispatch syntax can not be translated directly to Python, a few
691simple translations must take place.  The rules for these translations are:</p>
692<ol class="arabic">
693<li><p class="first">Replace all colons in the selector with underscores:</p>
694<blockquote>
695<div><ul class="simple">
696<li><tt class="docutils literal"><span class="pre">someMethod:withFoo:andBar:</span></tt> translates to <tt class="docutils literal"><span class="pre">someMethod_withFoo_andBar_</span></tt></li>
697</ul>
698</div></blockquote>
699</li>
700<li><p class="first">If the result <tt class="docutils literal"><span class="pre">class</span></tt> or <tt class="docutils literal"><span class="pre">raise</span></tt> (Python keywords), append two underscores:</p>
701<blockquote>
702<div><ul class="simple">
703<li><tt class="docutils literal"><span class="pre">class</span></tt> translates to <tt class="docutils literal"><span class="pre">class__</span></tt></li>
704<li><tt class="docutils literal"><span class="pre">raise</span></tt> translates to <tt class="docutils literal"><span class="pre">raise__</span></tt></li>
705</ul>
706</div></blockquote>
707</li>
708<li><p class="first">Use this translated selector as a normal Python method.
709The arguments must be passed in the same order, and the number of
710arguments passed will normally be equal to the number of underscores
711in the method name; exceptions to this rule and the behavior of &#8220;result&#8221;
712are mentioned below.</p>
713<div class="highlight-objective-c"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1</pre></div></td><td class="code"><div class="highlight"><pre><span class="n">result</span> <span class="o">=</span> <span class="p">[</span><span class="n">someObject</span> <span class="nl">someMethod:</span><span class="n">firstArg</span> <span class="nl">withFoo:</span><span class="n">foo</span> <span class="nl">andBar:</span><span class="n">bar</span><span class="p">];</span>
714</pre></div>
715</td></tr></table></div>
716<p>translates to</p>
717<div class="highlight-python"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1</pre></div></td><td class="code"><div class="highlight"><pre><span class="n">result</span> <span class="o">=</span> <span class="n">someObject</span><span class="o">.</span><span class="n">someMethod_withFoo_andBar_</span><span class="p">(</span><span class="n">firstArg</span><span class="p">,</span> <span class="n">foo</span><span class="p">,</span> <span class="n">bar</span><span class="p">)</span>
718</pre></div>
719</td></tr></table></div>
720</li>
721</ol>
722<p>Note that it is currently not possible to support methods with a variable
723number of arguments from Python.  These selectors must be wrapped by
724custom Objective-C code in order to be accessible by Python.</p>
725<p>Wrapped/bridged methods (and functions) have the same number of arguments
726as the corresponding Objective-C method or function, unless otherwise noted
727in the documentation (<a class="reference external" href="api-notes-macosx.html">Notes on supported APIs and classes on Mac OS X</a> for
728Cocoa on Mac OS X).</p>
729<p>Most methods or functions that take or return pointers to values will be an
730exception to this rule if it is callable from Python at all.  In Objective-C
731terminology, there are three kinds of pointers that can be used in a method:</p>
732<dl class="docutils">
733<dt><tt class="docutils literal"><span class="pre">in</span></tt>:</dt>
734<dd><p class="first">Used to pass data by reference to the function.  This is not a special
735case from Python.</p>
736<p class="last">Instead of a regular value you may also pass in the value <tt class="docutils literal"><span class="pre">objc.NULL</span></tt>,
737when you do that the Objective-C method will receive a NULL pointer instead
738of a pointer to your value.</p>
739</dd>
740<dt><tt class="docutils literal"><span class="pre">out</span></tt>:</dt>
741<dd><p class="first">Used to pass data from the function (e.g. an additional return value).</p>
742<p class="last">Pass in either <tt class="docutils literal"><span class="pre">None</span></tt> or <tt class="docutils literal"><span class="pre">objc.NULL</span></tt> for output arguments.
743to the method. If the value is <tt class="docutils literal"><span class="pre">objc.NULL</span></tt> the Objective-C code will
744receive a NULL pointer for this argument, otherwise it will receive a
745valid pointer.</p>
746</dd>
747<dt><tt class="docutils literal"><span class="pre">inout</span></tt>:</dt>
748<dd><p class="first">A combination of in and out (a value is passed by reference, and mutated
749upon return).  Unlike <tt class="docutils literal"><span class="pre">out</span></tt>, these arguments remain in the argument list,
750and thus do not have an effect on the number of arguments a method expects.
751See below for notes on how <tt class="docutils literal"><span class="pre">inout</span></tt> arguments change the return value.</p>
752<p class="last">Instead of a regular value you may also pass in the value <tt class="docutils literal"><span class="pre">objc.NULL</span></tt>,
753when you do that the Objective-C method will receive a NULL pointer instead
754of a pointer to your value.</p>
755</dd>
756</dl>
757<p>In order to determine what the return value of such an exceptional message will
758look like, you must &#8220;make a list&#8221; of the return values with the following rules:</p>
759<ol class="arabic simple">
760<li>If the return type of the method or function is not <tt class="docutils literal"><span class="pre">void</span></tt>, add it to the
761list.</li>
762<li>For each argument in the method or function, add it to the list if it is
763<tt class="docutils literal"><span class="pre">out</span></tt> or <tt class="docutils literal"><span class="pre">inout</span></tt>. When <tt class="docutils literal"><span class="pre">objc.NULL</span></tt> was used as the argument value it
764will also be used as the result value.</li>
765</ol>
766<p>After creating this list, you will have one of three cases:</p>
767<dl class="docutils">
768<dt>Empty:</dt>
769<dd>The return value of this call will always be <tt class="docutils literal"><span class="pre">None</span></tt>.</dd>
770<dt>One element:</dt>
771<dd>The return value of this call will correspond to the one element of the list.</dd>
772<dt>More than one element:</dt>
773<dd>The return value of this call will be a tuple in the same order as the list.</dd>
774</dl>
775<p>The rules for pass by reference arguments may look quite complicated, but
776it turns out this is very straightforward when working with them.</p>
777<p>As an example of a method with two output arguments, <tt class="docutils literal"><span class="pre">NSMatrix</span></tt> implements a
778selector named <tt class="docutils literal"><span class="pre">getNumberOfRows:columns:</span></tt> with the following signature:</p>
779<blockquote>
780<div><div class="highlight-objective-c"><div class="highlight"><pre><span class="k">-</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="nf">getNumberOfRows:</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span><span class="p">)</span><span class="nv">rowCount</span> <span class="nf">columns:</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span><span class="p">)</span><span class="nv">columnCount</span>
781</pre></div>
782</div>
783</div></blockquote>
784<p>This method is used from Python like this:</p>
785<blockquote>
786<div><div class="highlight-python"><div class="highlight"><pre><span class="n">rowCount</span><span class="p">,</span> <span class="n">columnCount</span> <span class="o">=</span> <span class="n">matrix</span><span class="o">.</span><span class="n">getNumberOfRows_columns_</span><span class="p">(</span><span class="bp">None</span><span class="p">,</span> <span class="bp">None</span><span class="p">)</span>
787</pre></div>
788</div>
789</div></blockquote>
790<p>When a function or method has an array of values and the length of that array
791as arguments, <tt class="docutils literal"><span class="pre">None</span></tt> may be passed as the length to specify that the length
792of the given sequence should be used.</p>
793<p>Python&#8217;s <tt class="docutils literal"><span class="pre">array.array</span></tt> type may be used to represent a C array if the
794typestr and size match what is expected by the selector.  Numeric, numarray,
795and other third party array types are not supported at the moment.</p>
796<p>When defining methods in an Objective-C subclass, the bridge must provide
797type signatures for each method to the Objective-C runtime.  The default
798type signature is for all arguments as well as the return value to be objects (just
799like with normal Python methods).  If there is no return statement in the implementation,
800then the return value will be void.  The bridge will automatically pick a better
801signature when it has more information available.  Specifically, a method overrides
802an existing method, the bridge will assume you want to use the same
803method signature.  Furthermore, if the method is implemented in an (informal)
804protocol known to the bridge it will use the signature from the corresponding
805method in that signature.</p>
806<p>The end result is that it is rarely necessary to explicitly add information about
807the signature of methods.  For the two most common cases where this is necessary,
808we have provided convenience decorators (used like <tt class="docutils literal"><span class="pre">staticmethod</span></tt> or
809<tt class="docutils literal"><span class="pre">classmethod</span></tt>):</p>
810<dl class="docutils">
811<dt><tt class="docutils literal"><span class="pre">objc.accessor</span></tt>:</dt>
812<dd>Use this to wrap a <a class="reference external" href="https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/KeyValueCoding/Articles/KeyValueCoding.html">Key-Value Coding</a> or <a class="reference external" href="https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/KeyValueObserving/KeyValueObserving.html">Key-Value Observing</a> compliant
813accessor.</dd>
814<dt><tt class="docutils literal"><span class="pre">PyObjCTools.AppHelper.endSheetMethod</span></tt>:</dt>
815<dd>Use this to wrap the implementation of a sheet&#8217;s &#8220;didEndSelector&#8221; callback.</dd>
816</dl>
817<p>For complete control of the mapping to Objective-C you can use the function
818<tt class="docutils literal"><span class="pre">objc.selector</span></tt> to create custom descriptors.  See the documentation of the
819<tt class="docutils literal"><span class="pre">objc</span></tt> module for the arguments you can use with this function.  It is
820normally used like this:</p>
821<blockquote>
822<div><div class="highlight-python"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
8232
8243
8254
8265
8276
8287</pre></div></td><td class="code"><div class="highlight"><pre>    <span class="k">class</span> <span class="nc">MyObject</span><span class="p">(</span><span class="n">NSObject</span><span class="p">):</span>
829
830            <span class="c"># -(void)someMethod:(float)arg</span>
831            <span class="k">def</span> <span class="nf">someMethod_</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">arg</span><span class="p">):</span>
832                    <span class="k">pass</span>
833
834            <span class="n">someMethod_</span> <span class="o">=</span> <span class="n">objc</span><span class="o">.</span><span class="n">selector</span><span class="p">(</span><span class="n">someMethod_</span><span class="p">,</span> <span class="n">signature</span><span class="o">=</span><span class="s">&#39;v@:f&#39;</span><span class="p">)</span>
835</pre></div>
836</td></tr></table></div>
837</div></blockquote>
838<p>In Python 2.4 or later there is a decorator for this purpose:</p>
839<blockquote>
840<div><div class="highlight-python"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
8412
8423
8434
8445</pre></div></td><td class="code"><div class="highlight"><pre>    <span class="k">class</span> <span class="nc">MyObject</span><span class="p">(</span><span class="n">NSObject</span><span class="p">):</span>
845
846            <span class="nd">@objc.signature</span><span class="p">(</span><span class="s">&#39;v@:f&#39;</span><span class="p">)</span>
847            <span class="k">def</span> <span class="nf">someMethod_</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">arg</span><span class="p">):</span>
848                    <span class="k">pass</span>
849</pre></div>
850</td></tr></table></div>
851</div></blockquote>
852</div>
853<div class="section" id="reference-counting">
854<h3>Reference counting<a class="headerlink" href="#reference-counting" title="Permalink to this headline">¶</a></h3>
855<p>The <a class="reference external" href="https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/CocoaFundamentals/Introduction/Introduction.html#//apple_ref/doc/uid/TP40002974">Cocoa libraries</a>, and most (if not all) other class libraries for
856Objective-C use explicit reference counting to manage memory.  The methods
857<tt class="docutils literal"><span class="pre">retain</span></tt>, <tt class="docutils literal"><span class="pre">release</span></tt> and <tt class="docutils literal"><span class="pre">autorelease</span></tt> are used to manage these
858reference counts.  You won&#8217;t have to manage reference counts in Python, the
859bridge does all that work for you (but see <a class="reference external" href="api-notes-macosx.html">Notes on supported APIs and classes
860on Mac OS X</a> for some advanced issues).</p>
861<p>The only reasons reference counts are mentioned at all are to tell you about
862ignoring them, and more importantly to introduce you to some issues w.r.t.
863reference counting.</p>
864<p>It turns out that Cocoa uses a primitive form of <a class="reference external" href="http://docs.python.org/library/weakref.html#weakref" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">weak</span> <span class="pre">references</span></tt></a>.  Those
865are not true <a class="reference external" href="http://docs.python.org/library/weakref.html#weakref" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">weak</span> <span class="pre">references</span></tt></a> as in Python, but use-cases where an object
866stores a reference to another object without increasing the reference count
867for that other object.  The bridge cannot solve the issues this introduces
868for you, which means that you get hard crashes when you&#8217;re not careful when
869dealing with those <a class="reference external" href="http://docs.python.org/library/weakref.html#weakref" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">weak</span> <span class="pre">references</span></tt></a>.</p>
870<p>The basic rule to deal with weak references is: make sure objects stays
871alive as long as someone might have a weak reference to them.  Due to the way
872the bridge works, this means that you must make sure that you don&#8217;t create
873weak references from Objective-C to a plain Python object.  The Python
874object stays alive, but the proxy object as seen by the Objective-C code is
875actually an autoreleased object that will be cleaned up unless the Objective-C
876code increases its reference count.</p>
877<p>The document <a class="reference external" href="api-notes-macosx.html">Notes on supported APIs and classes on Mac OS X</a> contains
878information about classes that work with weak references.  The most important
879are notification centers and <tt class="docutils literal"><span class="pre">NSOutlineView</span></tt>, to be exact: the outline view
880stores weak references to the objects return by the method
881<tt class="docutils literal"><span class="pre">outlineView:child:ofItem:</span></tt> of its data source.  The easiest way to avoid
882crashes with outline views is to make sure that you model for the view uses
883subclasses of <tt class="docutils literal"><span class="pre">NSObject</span></tt> to represent the nodes in the outline view.</p>
884<p>Another gotcha is that <tt class="docutils literal"><span class="pre">obj.setDelegate_()</span></tt> often does <em>not</em> retain the
885delegate, so a reference should be maintained elsewhere.</p>
886</div>
887<div class="section" id="protocols">
888<h3>Protocols<a class="headerlink" href="#protocols" title="Permalink to this headline">¶</a></h3>
889<p>Cocoa defines a number of formal and informal protocols that specify methods
890that should be implemented by a class if it is to be used in a specific role,
891such as the data source for an <tt class="docutils literal"><span class="pre">NSTableView</span></tt>.</p>
892<p>Those protocols are represented by instances of <tt class="docutils literal"><span class="pre">objc.informal_protocol</span></tt>,
893and <tt class="docutils literal"><span class="pre">objc.formal_protocol</span></tt>.  The only ones that have to care about these
894objects are the maintainers of wrappers around Objective-C frameworks: they
895have to keep these protocol wrappers up-to-date.</p>
896<p>PyObjC will automatically use the information in the <tt class="docutils literal"><span class="pre">informal_protocol</span></tt>
897objects to add the right method signatures to methods, and to warn about
898classes that partially implement a protocol.</p>
899<p>See <a class="reference external" href="protocols.html">PyObjC protocol support</a> for more information.</p>
900</div>
901<div class="section" id="cocoa-bindings">
902<h3>Cocoa Bindings<a class="headerlink" href="#cocoa-bindings" title="Permalink to this headline">¶</a></h3>
903<p>In Mac OS X 10.3 Apple introduced <a class="reference external" href="https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/CocoaBindings/CocoaBindings.html">Cocoa Bindings</a>, a method to make it easier
904to create and use <em>Controller</em> objects using <a class="reference external" href="https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/KeyValueObserving/KeyValueObserving.html">Key-Value Observing</a> and
905<a class="reference external" href="https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/KeyValueCoding/Articles/KeyValueCoding.html">Key-Value Coding</a>.  In order to create accessors compatible with this, you
906must use <tt class="docutils literal"><span class="pre">objc.accessor</span></tt> to create an appropriate selector descriptor.</p>
907<p>PyObjC automaticly emits the right <a class="reference external" href="https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/KeyValueObserving/KeyValueObserving.html">Key-Value Observing</a> notifications when
908you set attributes on an Objective-C class. This is however not supported for
909pure python objects. You should therefore use <tt class="docutils literal"><span class="pre">NSMutableArray</span></tt> instances
910instead of Python lists for instance variables that will be observed and contain
911a sequence of values (and simularly for <tt class="docutils literal"><span class="pre">NSMutableDictionary</span></tt> instead of
912<tt class="docutils literal"><span class="pre">dict</span></tt>).</p>
913<p>NOTE: Key-Value Observing is not supported for &#8220;pure&#8221; python objects, that
914is instances of classes that don&#8217;t inherit from <tt class="docutils literal"><span class="pre">NSObject</span></tt>. Adding such
915support is not possible adding a KVO-like interface to the Python interpreter.</p>
916</div>
917<div class="section" id="categories">
918<h3>Categories<a class="headerlink" href="#categories" title="Permalink to this headline">¶</a></h3>
919<p>Objective-C has a mechanism for modularize a class definition, it is possible
920to add methods to an existing class in a separate compilation unit and even
921a separate library.  This mechanism is named categories and is used to enhance
922existing classes, for splitting classes in several parts and to document
923informal protocols.</p>
924<p>An example of a category definition:</p>
925<blockquote>
926<div><div class="highlight-objective-c"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
9272
9283</pre></div></td><td class="code"><div class="highlight"><pre>    <span class="k">@interface</span> <span class="nc">NSObject</span> <span class="nl">(MyCategory)</span>
929    <span class="o">-</span> <span class="p">(</span><span class="n">NSSize</span><span class="p">)</span><span class="n">objectFootprint</span><span class="p">;</span>
930    <span class="k">@end</span>
931</pre></div>
932</td></tr></table></div>
933</div></blockquote>
934<p>This declares an additional category on <tt class="docutils literal"><span class="pre">NSObject</span></tt>.  This category contains
935a single method.</p>
936<p>The function <tt class="docutils literal"><span class="pre">objc.classAddMethods</span></tt> can be used to get the same effect in
937Python:</p>
938<blockquote>
939<div><div class="highlight-python"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
9402
9413
9424</pre></div></td><td class="code"><div class="highlight"><pre>    <span class="k">def</span> <span class="nf">objectFootprint</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
943            <span class="k">pass</span>
944
945    <span class="n">objc</span><span class="o">.</span><span class="n">classAddMethods</span><span class="p">(</span><span class="n">NSObject</span><span class="p">,</span> <span class="p">[</span><span class="n">objectFootprint</span><span class="p">])</span>
946</pre></div>
947</td></tr></table></div>
948</div></blockquote>
949<p>This is not very clear, PyObjC therefore also provides the following
950mechanism, implemented on top of <tt class="docutils literal"><span class="pre">objc.classAddMethods</span></tt>:</p>
951<blockquote>
952<div><div class="highlight-python"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
9532
9543</pre></div></td><td class="code"><div class="highlight"><pre>    <span class="k">class</span> <span class="nc">NSObject</span><span class="p">(</span><span class="n">objc</span><span class="o">.</span><span class="n">Category</span><span class="p">(</span><span class="n">NSObject</span><span class="p">)):</span>
955            <span class="k">def</span> <span class="nf">objectFootprint</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
956                    <span class="k">pass</span>
957</pre></div>
958</td></tr></table></div>
959</div></blockquote>
960<p>To make it clear that <tt class="docutils literal"><span class="pre">objc.Category</span></tt> performs a special task the name in
961the class definition must be the same as the <tt class="docutils literal"><span class="pre">__name__</span></tt> of the argument
962to <tt class="docutils literal"><span class="pre">objc.Category</span></tt>.</p>
963</div>
964</div>
965<div class="section" id="accessing-python-objects-from-objective-c">
966<h2>Accessing Python objects from Objective-C<a class="headerlink" href="#accessing-python-objects-from-objective-c" title="Permalink to this headline">¶</a></h2>
967<p>All Python objects can be accessed from Objective-C through proxy objects.
968Whenever a Python object crosses the line from Python to Objective-C a proxy
969object is created (of class <tt class="docutils literal"><span class="pre">OC_PythonObject</span></tt>, a subclass of <tt class="docutils literal"><span class="pre">NSProxy</span></tt>).
970This proxy object will forward all method calls from Objective-C to Python, and
971will return the results back to Objective-C.</p>
972<p>See the section &#8216;Method protocol&#8217; for a description of how PyObjC translates
973between Python and Objective-C method calls.</p>
974<p>A number of Python types/classes are treated specially:</p>
975<ul class="simple">
976<li>Python numbers (<tt class="docutils literal"><span class="pre">int</span></tt>, <tt class="docutils literal"><span class="pre">float</span></tt>, <tt class="docutils literal"><span class="pre">long</span></tt>) are translated into
977<tt class="docutils literal"><span class="pre">NSNumber</span></tt> instances.  Their identity is not preserved across the bridge.</li>
978<li>Python <tt class="docutils literal"><span class="pre">str</span></tt> is proxied using <tt class="docutils literal"><span class="pre">OC_PythonString</span></tt>, a subclass of
979<tt class="docutils literal"><span class="pre">NSString</span></tt>.  A Python <tt class="docutils literal"><span class="pre">str</span></tt> may be used anywhere a <tt class="docutils literal"><span class="pre">NSString</span></tt> is
980expected, but <tt class="docutils literal"><span class="pre">unicode</span></tt> should be used whenever possible.
981<tt class="docutils literal"><span class="pre">OC_PythonString</span></tt> will use the default encoding of <tt class="docutils literal"><span class="pre">NSString</span></tt>, which is
982normally MacRoman but could be something else.</li>
983<li>Python <tt class="docutils literal"><span class="pre">unicode</span></tt> is proxied using <tt class="docutils literal"><span class="pre">OC_PythonUnicode</span></tt>, a subclass of
984<tt class="docutils literal"><span class="pre">NSString</span></tt>.  A Python <tt class="docutils literal"><span class="pre">unicode</span></tt> may be used anywhere a <tt class="docutils literal"><span class="pre">NSString</span></tt>
985is expected.</li>
986<li>Python <tt class="docutils literal"><span class="pre">dict</span></tt> is proxied using <tt class="docutils literal"><span class="pre">OC_PythonDictionary</span></tt>, a subclass of
987<tt class="docutils literal"><span class="pre">NSMutableDictionary</span></tt>.  A Python <tt class="docutils literal"><span class="pre">dict</span></tt> may be used anywhere
988an <tt class="docutils literal"><span class="pre">NSDictionary</span></tt> is expected.</li>
989<li>Python <tt class="docutils literal"><span class="pre">list</span></tt> and <tt class="docutils literal"><span class="pre">tuple</span></tt> are proxied using <tt class="docutils literal"><span class="pre">OC_PythonArray</span></tt>, a
990subclass of <tt class="docutils literal"><span class="pre">NSMutableArray</span></tt>.  Python <tt class="docutils literal"><span class="pre">list</span></tt> or <tt class="docutils literal"><span class="pre">tuple</span></tt> objects
991may be used anywhere an <tt class="docutils literal"><span class="pre">NSArray</span></tt> is expected.</li>
992<li>Python objects that implement the Python buffer API, except for <tt class="docutils literal"><span class="pre">str</span></tt>
993and <tt class="docutils literal"><span class="pre">unicode</span></tt>, are proxied using <tt class="docutils literal"><span class="pre">OC_PythonData</span></tt>, a <tt class="docutils literal"><span class="pre">NSData</span></tt> subclass.
994Objects that implement the Python buffer API such as <tt class="docutils literal"><span class="pre">buffer</span></tt>,
995<tt class="docutils literal"><span class="pre">array.array</span></tt>, <tt class="docutils literal"><span class="pre">mmap.mmap</span></tt>, etc. may be used anywhere a <tt class="docutils literal"><span class="pre">NSData</span></tt> is
996expected.</li>
997</ul>
998<p>These special cases allow for more transparent bridging between Python and
999Objective-C.</p>
1000</div>
1001<div class="section" id="cocoa-for-python-programmers">
1002<h2>Cocoa for Python programmers<a class="headerlink" href="#cocoa-for-python-programmers" title="Permalink to this headline">¶</a></h2>
1003<p>Cocoa frameworks are mapped onto Python packages with the same name; that is
1004the classes, constants and functions from the AppKit framework are available
1005after you import <tt class="docutils literal"><span class="pre">AppKit</span></tt> in your Python script.</p>
1006<p>These helper modules contain <em>only</em> functions, constants and classes that
1007wrap items in the corresponding framework.  All utility functions and classes
1008are located in the <tt class="docutils literal"><span class="pre">PyObjCTools</span></tt> package and <tt class="docutils literal"><span class="pre">objc</span></tt> module.  Note that it
1009is possible to use <tt class="docutils literal"><span class="pre">pydoc</span></tt> (or the <tt class="docutils literal"><span class="pre">help()</span></tt>) function with the framework
1010wrappers, but that this is not very useful for the entire module due to the
1011size of these modules.</p>
1012<p>This makes it easier to find documentation for an item: if you import it
1013from the wrapper module for an Objective-C framework the documentation for
1014that item can be found in the documentation for the framework; otherwise the
1015item is documented in the PyObjC documentation.</p>
1016<p>The module <tt class="docutils literal"><span class="pre">PyObjCTools.NibClassBuilder</span></tt> can be used to make working with
1017NIB files more convenient.  This module can be used to extract information
1018about classes from NIB files, both as a standalone tool generating source code
1019and during runtime.  See the online documentation for this module for more
1020information.</p>
1021<p>PyObjC includes a number of examples that show how to use Cocoa from
1022Python.  The <a class="reference external" href="/Examples/00ReadMe.html">PyObjC Example index</a> contains an overview of those examples.</p>
1023<p>More information on Cocoa programming can be found at:</p>
1024<ul class="simple">
1025<li><a class="reference external" href="https://developer.apple.com/library/mac/navigation/index.html#section=Frameworks&amp;topic=Cocoa%20Layer">Cocoa documentation at the Apple developer website</a></li>
1026<li><a class="reference external" href="https://developer.apple.com/library/mac/navigation/index.html#section=Resource%20Types&amp;topic=Sample%20Code">Cocoa examples at the Apple developer website</a></li>
1027<li>Your local bookstore or library</li>
1028</ul>
1029</div>
1030<div class="section" id="notes-on-specific-tasks">
1031<h2>Notes on specific tasks<a class="headerlink" href="#notes-on-specific-tasks" title="Permalink to this headline">¶</a></h2>
1032<div class="section" id="working-with-threads">
1033<h3>Working with threads<a class="headerlink" href="#working-with-threads" title="Permalink to this headline">¶</a></h3>
1034<p>Most of Cocoa, and thus PyObjC, requires an <tt class="docutils literal"><span class="pre">NSAutoreleasePool</span></tt> in order to function
1035properly.  PyObjC does this automatically on the first thread it is imported from,
1036but other threads will require explicit <tt class="docutils literal"><span class="pre">NSAutoreleasePool</span></tt> management.  The following
1037practice for working with <tt class="docutils literal"><span class="pre">NSAutoreleasePool</span></tt> is recommended:</p>
1038<blockquote>
1039<div><div class="highlight-python"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
10402
10413</pre></div></td><td class="code"><div class="highlight"><pre>    <span class="n">pool</span> <span class="o">=</span> <span class="n">NSAutoreleasePool</span><span class="o">.</span><span class="n">alloc</span><span class="p">()</span><span class="o">.</span><span class="n">init</span><span class="p">()</span>
1042    <span class="o">...</span>
1043    <span class="k">del</span> <span class="n">pool</span>
1044</pre></div>
1045</td></tr></table></div>
1046</div></blockquote>
1047<p>Typically this will be done at the beginning and end of the thread.  It is important
1048to use <tt class="docutils literal"><span class="pre">del</span></tt> before rebinding the <tt class="docutils literal"><span class="pre">pool</span></tt> local to another <tt class="docutils literal"><span class="pre">NSAutoreleasePool</span></tt>
1049instance, otherwise it will not have the intended effect.</p>
1050<p>For long running threads and tight loops, it can also be useful to use this pattern
1051in the body of the loop in order to optimize memory usage.  For example, <tt class="docutils literal"><span class="pre">NSRunLoop</span></tt>
1052will be create a new <tt class="docutils literal"><span class="pre">NSAutoreleasePool</span></tt> at the beginning of each run loop iteration
1053and release it at the end.</p>
1054</div>
1055<div class="section" id="finalizers">
1056<h3>Finalizers<a class="headerlink" href="#finalizers" title="Permalink to this headline">¶</a></h3>
1057<p>In normal Python, there are two methods for writing finalizers: implementing
1058<tt class="docutils literal"><span class="pre">__del__</span></tt>, and using <tt class="docutils literal"><span class="pre">weakref.ref</span></tt> callbacks.  Generally, <tt class="docutils literal"><span class="pre">__del___</span></tt> is
1059discouraged as it does not allow the object to participate in cyclic garbage
1060collection and create uncollectible garbage if not implemented properly.
1061<tt class="docutils literal"><span class="pre">weakref.ref</span></tt> callbacks avoid this restriction as they do not provide a real
1062reference to the object.</p>
1063<p>In Objective-C, there is no cyclic garbage collection, so all Objective-C
1064objects (including subclasses from Python) are already subject to these
1065restrictions.  When subclassing an Objective-C class, you may implement
1066<tt class="docutils literal"><span class="pre">dealloc</span></tt> or <tt class="docutils literal"><span class="pre">__del__</span></tt>.  If you implement <tt class="docutils literal"><span class="pre">dealloc</span></tt>, ensure that
1067you call the super <tt class="docutils literal"><span class="pre">dealloc</span></tt> at the end.  If you implement both
1068<tt class="docutils literal"><span class="pre">__del__</span></tt> and <tt class="docutils literal"><span class="pre">dealloc</span></tt>, the order in which they are called is
1069undefined.</p>
1070<p>It is not currently possible to create a <tt class="docutils literal"><span class="pre">weakref.ref</span></tt> for any Objective-C
1071object.  It is probably technically possible to do, but tricky, so it
1072may eventually be implemented in a future version of PyObjC (especially
1073if a future Objective-C runtime supports it).</p>
1074</div>
1075<div class="section" id="copying">
1076<h3>Copying<a class="headerlink" href="#copying" title="Permalink to this headline">¶</a></h3>
1077<p>It is possible for a Python subclass of an Objective-C class to implement
1078the <tt class="docutils literal"><span class="pre">NSCopying</span></tt> protocol.  Some care must be taken when the superclass
1079already implements the protocol.</p>
1080<p>Some <tt class="docutils literal"><span class="pre">NSCopying</span></tt> compliant Objective-C classes copy the template object
1081manually.  In those cases the Python subclass must also copy the additional
1082ivars manually.</p>
1083<p>Other <tt class="docutils literal"><span class="pre">NSCopying</span></tt> compliant Objective-C classes use a convenience function
1084that creates a shallow copy of the object and all of its ivars.  In those
1085cases the Python subclass will not have to explicitly copy all of the ivars.
1086However, the ivars in the copy will refer to the same objects as the original,
1087and will thus share some state.  As with shallow copies in Python, if any of
1088the ivars refer to mutable objects (<tt class="docutils literal"><span class="pre">list</span></tt>, <tt class="docutils literal"><span class="pre">dict</span></tt>, etc.) it may be
1089desirable to explicitly make shallow or deep copies of the mutable ivars.</p>
1090<p>NOTE: PyObjC might introduce a helper class when you inherit from a class
1091that implements <tt class="docutils literal"><span class="pre">NSCopying</span></tt> as an internal implementation detail.
1092External code should not rely on the existance of this class.</p>
1093<p>NOTE2: <tt class="docutils literal"><span class="pre">SomeClass.copyWithZone_</span></tt> should not be implemented unless a
1094superclass already implements <tt class="docutils literal"><span class="pre">copyWithZone:</span></tt>, or else the behavior
1095will be undefined (memory corruption, crashes, etc.).</p>
1096</div>
1097</div>
1098<div class="section" id="building-applications">
1099<h2>Building applications<a class="headerlink" href="#building-applications" title="Permalink to this headline">¶</a></h2>
1100<p>There are two different recommended ways to build applications with PyObjC.</p>
1101<div class="section" id="py2app-setup-py">
1102<h3>&#8220;py2app&#8221; :  setup.py<a class="headerlink" href="#py2app-setup-py" title="Permalink to this headline">¶</a></h3>
1103<p>The PyObjC installer includes a copy of the <tt class="docutils literal"><span class="pre">py2app</span></tt> package.  This package
1104offers a way to build distutils scripts for building (standalone)
1105applications and plugin bundles.</p>
1106<p>An example <tt class="docutils literal"><span class="pre">setup.py</span></tt> script:</p>
1107<blockquote>
1108<div><div class="highlight-python"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
11092
11103
11114
11125
11136
11147</pre></div></td><td class="code"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="kn">import</span> <span class="n">setup</span>
1115<span class="kn">import</span> <span class="nn">py2app</span>
1116
1117<span class="n">setup</span><span class="p">(</span>
1118    <span class="n">app</span> <span class="o">=</span> <span class="p">[</span><span class="s">&quot;iClass.py&quot;</span><span class="p">],</span>
1119    <span class="n">data_files</span> <span class="o">=</span> <span class="p">[</span><span class="s">&quot;English.lproj&quot;</span><span class="p">],</span>
1120<span class="p">)</span>
1121</pre></div>
1122</td></tr></table></div>
1123</div></blockquote>
1124<p>During development you typically invoke it from the command line like this:</p>
1125<blockquote>
1126<div><div class="highlight-sh"><div class="highlight"><pre><span class="nv">$ </span>python setup.py py2app -A
1127</pre></div>
1128</div>
1129</div></blockquote>
1130<p>This will build an application bundle in a folder named <tt class="docutils literal"><span class="pre">dist</span></tt> in the
1131current folder. The <tt class="docutils literal"><span class="pre">-A</span></tt> option tells <tt class="docutils literal"><span class="pre">py2app</span></tt> to add symbolic
1132links for data folders and files and an Alias to your main script,
1133allowing you quickly rebuild the application without doing a full dependency
1134scan, with the additional bonus that you can edit them without rebuild. To
1135build a standalone application, simply do not use the <tt class="docutils literal"><span class="pre">-A</span></tt> option.
1136Note that if you are using a version of Python shipped with your operating
1137system, it will not be included in the application.  Otherwise, your
1138application will include stripped down version of the Python runtime that
1139you ran setup.py with.</p>
1140<p>For more information about <tt class="docutils literal"><span class="pre">py2app</span></tt> usage, read through some of the
1141<tt class="docutils literal"><span class="pre">setup.py</span></tt> scripts used by the examples in the <a class="reference external" href="/Examples/00ReadMe.txt">Examples</a> folder.
1142On any <tt class="docutils literal"><span class="pre">setup.py</span></tt> script that imports <tt class="docutils literal"><span class="pre">py2app</span></tt>, you can use the
1143following command to see the list of options:</p>
1144<blockquote>
1145<div><div class="highlight-sh"><div class="highlight"><pre><span class="nv">$ </span>python setup.py py2app --help
1146</pre></div>
1147</div>
1148</div></blockquote>
1149</div>
1150<div class="section" id="ide-approach-xcode">
1151<h3>&#8220;IDE approach&#8221; : Xcode<a class="headerlink" href="#ide-approach-xcode" title="Permalink to this headline">¶</a></h3>
1152<p>PyObjC includes a number of Xcode templates that can be used to
1153develop applications, using the same underlying functionality that
1154is in py2app.  These templates are used like any other Xcode template,
1155but there are some organizational rules about the template.</p>
1156<p>See <a class="reference external" href="Xcode-Templates.html">the documentation for the templates</a> for more details.</p>
1157</div>
1158</div>
1159</div>
1160
1161
1162          </div>
1163        </div>
1164      </div>
1165      <div class="sphinxsidebar">
1166        <div class="sphinxsidebarwrapper">
1167  <h3><a href="index.html">Table Of Contents</a></h3>
1168  <ul>
1169<li><a class="reference internal" href="#">An introduction to PyObjC</a><ul>
1170<li><a class="reference internal" href="#preface">Preface</a></li>
1171<li><a class="reference internal" href="#first-steps">First Steps</a><ul>
1172<li><a class="reference internal" href="#underscores-and-lots-of-them">Underscores, and lots of them</a></li>
1173<li><a class="reference internal" href="#two-phase-instantiation">Two-phase instantiation</a></li>
1174<li><a class="reference internal" href="#objective-c-uses-accessors-everywhere">Objective-C uses accessors everywhere</a></li>
1175</ul>
1176</li>
1177<li><a class="reference internal" href="#objective-c-for-pyobjc-users">Objective-C for PyObjC users</a></li>
1178<li><a class="reference internal" href="#overview-of-the-bridge">Overview of the bridge</a><ul>
1179<li><a class="reference internal" href="#classes">Classes</a></li>
1180<li><a class="reference internal" href="#messages-and-functions">Messages and Functions</a></li>
1181<li><a class="reference internal" href="#reference-counting">Reference counting</a></li>
1182<li><a class="reference internal" href="#protocols">Protocols</a></li>
1183<li><a class="reference internal" href="#cocoa-bindings">Cocoa Bindings</a></li>
1184<li><a class="reference internal" href="#categories">Categories</a></li>
1185</ul>
1186</li>
1187<li><a class="reference internal" href="#accessing-python-objects-from-objective-c">Accessing Python objects from Objective-C</a></li>
1188<li><a class="reference internal" href="#cocoa-for-python-programmers">Cocoa for Python programmers</a></li>
1189<li><a class="reference internal" href="#notes-on-specific-tasks">Notes on specific tasks</a><ul>
1190<li><a class="reference internal" href="#working-with-threads">Working with threads</a></li>
1191<li><a class="reference internal" href="#finalizers">Finalizers</a></li>
1192<li><a class="reference internal" href="#copying">Copying</a></li>
1193</ul>
1194</li>
1195<li><a class="reference internal" href="#building-applications">Building applications</a><ul>
1196<li><a class="reference internal" href="#py2app-setup-py">&#8220;py2app&#8221; :  setup.py</a></li>
1197<li><a class="reference internal" href="#ide-approach-xcode">&#8220;IDE approach&#8221; : Xcode</a></li>
1198</ul>
1199</li>
1200</ul>
1201</li>
1202</ul>
1203
1204  <h4>Previous topic</h4>
1205  <p class="topless"><a href="index.html"
1206                        title="previous chapter">Welcome to PyObjC-Core&#8217;s documentation!</a></p>
1207  <h4>Next topic</h4>
1208  <p class="topless"><a href="tutorials/index.html"
1209                        title="next chapter">PyObjC Tutorials</a></p>
1210  <h3>This Page</h3>
1211  <ul class="this-page-menu">
1212    <li><a href="_sources/intro.txt"
1213           rel="nofollow">Show Source</a></li>
1214  </ul>
1215<div id="searchbox" style="display: none">
1216  <h3>Quick search</h3>
1217    <form class="search" action="search.html" method="get">
1218      <input type="text" name="q" />
1219      <input type="submit" value="Go" />
1220      <input type="hidden" name="check_keywords" value="yes" />
1221      <input type="hidden" name="area" value="default" />
1222    </form>
1223    <p class="searchtip" style="font-size: 90%">
1224    Enter search terms or a module, class or function name.
1225    </p>
1226</div>
1227<script type="text/javascript">$('#searchbox').show(0);</script>
1228        </div>
1229      </div>
1230      <div class="clearer"></div>
1231    </div>
1232    <div class="related">
1233      <h3>Navigation</h3>
1234      <ul>
1235        <li class="right" style="margin-right: 10px">
1236          <a href="genindex.html" title="General Index"
1237             >index</a></li>
1238        <li class="right" >
1239          <a href="py-modindex.html" title="Python Module Index"
1240             >modules</a> |</li>
1241        <li class="right" >
1242          <a href="tutorials/index.html" title="PyObjC Tutorials"
1243             >next</a> |</li>
1244        <li class="right" >
1245          <a href="index.html" title="Welcome to PyObjC-Core’s documentation!"
1246             >previous</a> |</li>
1247        <li><a href="index.html">PyObjC-Core 2.5.0b1 documentation</a> &raquo;</li> 
1248      </ul>
1249    </div>
1250    <div class="footer">
1251        &copy; Copyright 2009-2012, Ronald Oussoren.
1252      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
1253    </div>
1254  </body>
1255</html>