1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
|
<html>
<!-- ***** BEGIN LICENSE BLOCK *****
- Version: MPL 1.1/GPL 2.0/LGPL 2.1
-
- The contents of this file are subject to the Mozilla Public License Version
- 1.1 (the "License"); you may not use this file except in compliance with
- the License. You may obtain a copy of the License at
- http://www.mozilla.org/MPL/
-
- Software distributed under the License is distributed on an "AS IS" basis,
- WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
- for the specific language governing rights and limitations under the
- License.
-
- The Original Code is PyXPCOM.
-
- The Initial Developer of the Original Code is
- ActiveState Tool Corporation.
- Portions created by the Initial Developer are Copyright (C) 2000-2001
- the Initial Developer. All Rights Reserved.
-
- Contributor(s):
-
- Alternatively, the contents of this file may be used under the terms of
- either the GNU General Public License Version 2 or later (the "GPL"), or
- the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
- in which case the provisions of the GPL or the LGPL are applicable instead
- of those above. If you wish to allow use of your version of this file only
- under the terms of either the GPL or the LGPL, and not to allow others to
- use your version of this file under the terms of the MPL, indicate your
- decision by deleting the provisions above and replace them with the notice
- and other provisions required by the LGPL or the GPL. If you do not delete
- the provisions above, a recipient may use your version of this file under
- the terms of any one of the MPL, the GPL or the LGPL.
-
- ***** END LICENSE BLOCK ***** -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<title>Python XPCOM Advanced Topics</title>
</head>
<body>
<h1>Python XPCOM Advanced Topics</h1>
<p>This document contains a series of tidbits that don't fit
anywhere else. As the Python XPCOM Package documentation matures, most of
these topics will have another home.</p>
<h2>XPCOM Services</h2>
<p>An XPCOM service is simply a singleton registered by name. Python has
full support for both using and implementing XPCOM services. To use a
service, use <i>xpcom.components.services</i> just like the JavaScript
counterpart. There is nothing special about implementing a service in
Python; see the standard XPCOM documentation on services for more information.</p>
<h2>nsIVariant</h2>
<p>There is (almost) full support for <i>nsIVariant</i>. Any <i>nsIVariant</i>
parameters will automatically be translated to and from regular Python objects
giving, in effect, a multi-type parameter. This should be automatic, so
there is not much else to say! Note that if you really want, you can
create and pass your own <i>nsIVariant</i> object instead of a regular Python
object, thereby allowing explicit control over the type of variant created.</p>
<h2>nsISupports Primitives.</h2>
<p>There is a set of interfaces described in <i>nsISupportsPrimitives.idl</i>, which I
term collectively the <i>nsISupports Primitives Interfaces</i>. These
are a set of interfaces a component can support to allow automatic conversion to
and from many basic types. For example, an interface can define that it
supports the <i>nsISupportsCString</i> interface, and this could be used by any
program that wishes to get a string representation of the object. If an
interface wishes to expose itself as a "boolean value", it may choose
to support the <i>nsISupportsPRBool</i> interface.</p>
<p>When you call an XPCOM object (i.e., you have an XPCOM interface you are
calling), you can use
the builtin functions <i>str()</i>, <i>int()</i>, <i>long()</i> etc., on the
object<i>.</i> In the
case of <i>str()</i>, if the object does not support the <i>nsISupportsCString</i>
or <i>nsISupportsString</i> interfaces, the default string <i>str()</i> for the
object will be returned (i.e., what is normally returned for most XPCOM objects -
support for these interface is not very common!). In the case of the numeric functions, a <i>ValueError</i>
exception will be raised if the objects do not support any interface that can be
used for the conversion. <i>ValueError</i> is used instead of <i>TypeError</i>,
as the type itself (i.e., an XPCOM object) can sometimes be used in this context -
hence it is the specific <i>value</i> of the object that is the problem.</p>
<p>The use of <i>repr()</i> on an XPCOM interface object prevents support
attempts for these interfaces, and allows you to see the
"real" object, rather than what the object wants you to see!</p>
<p>When you implement an XPCOM object, you have two choices for implementation
of these interfaces:</p>
<ul>
<li>You can explicitly handle these interfaces like any other interface.
In this case, you have full control. However, if you
implement only one of these standard interfaces, then you are only
overriding the default behavior for that specific interface - all other
interfaces not explicitly listed in your class will still get the behavior
described below.<br>
</li>
<li>If your class does not define support for these interfaces, the framework
will use standard Python class semantics to implement them - i.e., if your
class provides a <i>__str__</i> method, it will be used to implement <i>nsISupportsCString</i>
and <i>nsISupportsString</i>, if you provide <i>__int__</i>, <i>__long__</i>,
<i>__float__</i> etc., methods, they will be used to implement the numeric
interfaces. If your class defines no such special methods, then the <i>
QueryInterface()</i> for those interfaces fails (rather than the QI succeeding
and the operation to fetch the data failing).</li>
</ul>
<blockquote>
<p>This allows for an interesting feature that would not normally be
possible. Consider Python code that does a <i>str()</i> on an XPCOM
interface, and where the XPCOM interface itself is implemented in Python and
provides a <i>__str__</i> method. The <i>str()</i> on the original
interface queries for the <i>nsISupportsCString</i> interface. The
Python implemented object responds to this interface and delegates to the <i>__str__</i>
method. At the end of all this, <i>str()</i> returns the same result
as if the objects were native Python objects with no XPCOM layer in between.</p>
</blockquote>
<h2>Enumerators</h2>
<p>The primary enumerator used by XPCOM is <i>nsISimpleEnumerator</i>.
Although the Python XPCOM package has full support for <i>nsIEnumerator</i>,
since this interface is not "scriptable", you should avoided using it in interfaces
you design.</p>
<p>When you use <i>nsISimpleEnumerator</i> from Python, the following enhancements
are available:</p>
<ul>
<li>The <i>GetNext()</i> method takes an optional IID as a parameter. If
this is specified, the returned object will be of this interface. This
prevents the manual <i>QueryInterface()</i> generally required from other
languages.</li>
<li>There is a <i>FetchBlock(num, [iid])</i> method, which fetches the
specified number of elements in one operation and returns a Python
list. This can be useful for large enumerator sets, so the loop
iterating the elements runs at full C++ speed.</li>
</ul>
<p><i>nsIEnumerator</i> has similar enhancements.</p>
<p>When implementing a Python XPCOM object, the Python class <i>xpcom.server.enumerator.SimpleEnumerator()</i>
can be used. You can pass a standard Python sequence (list, etc), and it
will be correctly wrapped in an <i>nsISimpleEnumerator</i> interface.</p>
<h2>Files</h2>
<p>The Python XPCOM package provides an <i> xpcom.file</i> module. This implements
a Python-like file object on top of the XPCOM/Mozilla stream interfaces.
When run from within the Mozilla environment, this allows you to open almost any
URL supported by Mozilla (including "chrome://" etc.,).</p>
<p>See this module for more information, including test code.</p>
<h2>XPCOM Object Identity</h2>
<p>XPCOM has defined rules for object identity and for how objects must behave
in their <i> QueryInterface()</i> implementations. The Python XPCOM framework
manages this for you; your code can return new Python instances etc., when
responding to new interfaces, and the framework itself will ensure the XPCOM
semantics are followed. Critically, the framework provides no mechanism
for breaking these rules.</p>
<h2>Policies</h2>
<p>The Python XPCOM framework has the concept of "policies" that
define how XPCOM semantics are mapped to Python objects. It is the policy
that implements delegation of <i> QueryInterface()</i>, translates property
references into direct property references, and failing that, "get_name"
and "set_name" calls, decides how to handle exceptions in the
component, and so on.</p>
<p>The default policy is very flexible and suitable for most purposes.
Indeed, the Komodo project has never had to implement a custom policy.
However, you should be aware the feature exists should you wish to do some
bizarre things, such as using Python as a bridge between XPCOM and some other
component technology.</p>
</body>
</html>
|
