2001-02-19 08:24:45 +03:00
< html >
<!-- Copyright (c) 2000 - 2001 ActiveState Tool Corporation.
See the file LICENSE.txt for licensing information. -->
< 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 Package Tutorial< / title >
< / head >
< body >
< h1 > Python XPCOM Package Tutorial< / h1 >
< p > This is a quick introduction to the Python XPCOM Package. We assume that you have a good understanding of Python and < a href = "http://www.mozilla.org/projects/xpcom/" > XPCOM< / a > ,
and have experience both using and implementing XPCOM objects in some other
language (e.g., C++ or JavaScript). We < b > < i > do not< / i > < / b > attempt to
provide a tutorial to XPCOM or Python itself, only to using Python < i > and< / i >
XPCOM.< / p >
< p > This tutorial contains the following sections:< / p >
< ul >
< li > < a href = "#Using" > Using XPCOM Objects and Interfaces< / a > - when you wish to
< i > use< / i > a component written by anyone else in any XPCOM supported
language.< / li >
< li > < a href = "#Implementing" > Implementing XPCOM Objects and Interfaces< / a > -
when you wish to implement a component for use by anyone else in any xpcom
supported language.< / li >
< li > < a href = "#Parameters" > Parameters and Types< / a > - useful information
regarding how Python translates XPCOM types, and handles byref parameters.< / li >
< / ul >
< p > For anything not covered here, try the < a href = "advanced.html" > advanced
documentation< / a > , and if that fails, use the source, Luke!< / p >
< h2 > < a name = "Using" > Using XPCOM object and interfaces.< / a > < / h2 >
< p > The techniques for using XPCOM in Python have been borrowed from JavaScript -
thus, the model described here should be quite familiar to existing JavaScript
XPCOM programmers.< / p >
< h3 > xpcom.components module< / h3 >
< p > When using an XPCOM object, the primary module used is the < u > < i > xpcom.components< / i > < / u >
module. Using this module, you can get a Python object that supports any
scriptable XPCOM interface. Once you have this Python object, you can
simply call XPCOM methods on the object, as normal.< / p >
< p > The < u > < i > xpcom.components< / i > < / u > module defines the following public
members:< / p >
< table border = "1" width = "100%" >
< tr >
< td width = "16%" > < b > Name< / b > < / td >
< td width = "84%" > < b > Description< / b > < / td >
< / tr >
< tr >
< td width = "16%" > classes< / td >
< td width = "84%" > A mapping (dictionary-like object) used to get XPCOM
" classes" . These are indexed by XPCOM contract ID, just
like the JavaScript object of the same name.
< p > Example:< / p >
< pre > cls = components.classes[" @mozilla.org/sample;1" ]
ob = cls.createInstance() # Now have an nsISupports< / pre >
< / td >
< / tr >
< tr >
< td width = "16%" > interfaces< / td >
< td width = "84%" > An object that exposes all XPCOM interface IDs (IIDs).
Like the JavaScript object of the same name, this object uses
" dot" notation, as demonstrated below.
< p > Example:< / p >
< pre > ob = cls.createInstance(components.interfaces.nsISample)
# Now have an nsISample< / pre >
< / td >
< / tr >
< / table >
< p > For many people, this is all you need to know. Consider the Mozilla Sample Component. The Mozilla Sample
Component has a contract ID of < i > @mozilla.org/sample;1< / i > ,
and implements the < i > nsISample< / i > interface.< / p >
< p > Thus, a complete Python program that uses this component is shown below.< / p >
< pre > from xpcom import components
cls = components.classes[" @mozilla.org/sample;1" ]
2001-05-27 06:51:18 +04:00
ob = cls.createInstance() # no need to specify an IID for most components
2001-02-19 08:24:45 +03:00
# nsISample defines a " value" property - let's use it!
ob.value = " new value"
if ob.value != " new value" :
print " Eeek - what happened?" < / pre >
< p > And that is it - a complete Python program that uses XPCOM.< / p >
< h2 > < a name = "Implementing" > Implementing XPCOM Objects and Interfaces.< / a > < / h2 >
< p > Implementing XPCOM objects is almost as simple as using them. The
basic strategy is this:< / p >
< ol >
< li > Create a standard Python source file, with a standard Python class.< / li >
< li > Add some special < a href = "#Attributes" > attributes< / a > to your class for use by the Python XPCOM
framework. This controls the XPCOM behavior of your object.< / li >
< li > Implement the XPCOM < a href = "#Properties" > properties< / a > and methods of your classes as normal.< / li >
< li > Put the Python source file in the Mozilla < i > components< / i > directory.< / li >
< li > Run < i > regxpcom.< / i > < / li >
< / ol >
< p > Your component is now ready to be used.< / p >
< h3 > < a name = "Attributes" > Attributes< / a > < / h3 >
< p > There are two classes of attributes: those used at runtime to define the object
behavior and those used at registration time to control object
registration. Not all objects require registration, thus not all
Python XPCOM objects will have registration-related attributes.< / p >
< table border = "1" width = "100%" >
< tr >
< td width = "17%" > < b > Attribute< / b > < / td >
< td width = "83%" > < b > Description< / b > < / td >
< / tr >
< tr >
< td width = "17%" > _com_interfaces_< / td >
< td width = "83%" > The interface IDs (IIDs) supported by the component.
For simplicity, this may be either a single IID, or a list of IIDs.
There is no need to specify base interfaces, as all parent interfaces are
automatically supported. Thus, it is never necessary to nominate < i >
nsISupports< / i > in the list of interfaces.
< p > This attribute is required. Objects without such an attribute are
deemed unsuitable for use as a XPCOM object.< / td >
< / tr >
< tr >
< td width = "17%" > _reg_contractid_< / td >
< td width = "83%" > The contract ID of the component. Required if the
component requires registration (i.e., exists in the components directory).< / td >
< / tr >
< tr >
< td width = "17%" > _reg_clsid_< / td >
< td width = "83%" > The Class ID (CLSID) of the component, as a string in the
standard " {XXX-XXX-XXX-XXX}" format. Required if the
component requires registration (i.e., exists in the components directory).< / td >
< / tr >
< tr >
< td width = "17%" > _reg_registrar_< / td >
< td width = "83%" > Nominates a function that is called at registration
time. The default is for no extra function to be called. This can
be useful if a component has special registration requirements and needs
to hook into the registration process.< / td >
< / tr >
< tr >
< td width = "17%" > _reg_desc_< / td >
< td width = "83%" > The description of the XPCOM object. This may be used by
browsers or other such objects. If not specified, the contract ID
is used.< / td >
< / tr >
< / table >
< h3 > < a name = "Properties" > Properties< / a > < / h3 >
< p > A Python class can support XPCOM properties in one of two ways. Either
a standard Python property of the same name can exist - our sample
component demonstrates this with the < i > boolean_value< / i > property.
Alternatively, the class can provide the < i > get_propertyName(self)< / i > and < i > set_propertyName(self,
value)< / i > functions (with < i > propertyName< / i > changed to the appropriate value for the
property), and these functions will be called instead.< / p >
< h4 > Example: The Python XPCOM Test Component< / h4 >
< p > As an example, examine the Python XPCOM Test Component. This
code can be found in < i > py_test_component.py< / i > .< / p >
< pre > from xpcom import components
class PythonTestComponent:
_com_interfaces_ = components.interfaces.nsIPythonTestInterface
_reg_clsid_ = " {7EE4BDC6-CB53-42c1-A9E4-616B8E012ABA}"
_reg_contractid_ = " Python.TestComponent"
def __init__(self):
self.boolean_value = 1
...
def do_boolean(self, p1, p2):
ret = p1 ^ p2
return ret, not ret, ret
...< / pre >
< p > < b > Note:< / b > This component only specifies the mandatory attributes - < i > _com_interfaces< / i > ,
< i > _reg_clsid_< / i > and < i > _reg_contractid_< / i > .< / p >
< p > This sample code demonstrates supporting the < i > boolean_value< / i > attribute,
supported implicitly, as it is defined in the IDL and exists as a real Python
attribute of that name, and a method called < i > do_boolean< / i > .< / p >
< h4 > Tip: The xpcom/xpt.py Script< / h4 >
< p > The xpcom/xpt.py script is a useful script that can generate the skeleton of a class for
any XPCOM interface. Just specify the interface name on the command-line,
and paste the output into your source file.< / p >
< p > This is the output of running this program over the < i > nsISample< / i >
interface (i.e., assuming we wanted to implement a component that supported this
interface):< / p >
< pre > class nsISample:
_com_interfaces_ = xpcom.components.interfaces.nsISample
# If this object needs to be registered, the following 2 are also needed.
# _reg_clsid_ = {a new clsid generated for this object}
# _reg_contractid_ = " The.Object.Name"
def get_value( self ):
# Result: string
pass
def set_value( self, param0 ):
# Result: void - None
# In: param0: string
pass
def writeValue( self, param0 ):
# Result: void - None
# In: param0: string
pass
def poke( self, param0 ):
# Result: void - None
# In: param0: string
pass< / pre >
< p > < b > Note:< / b > The types of the parameters and the function itself are included in
the comments. You need to implement the functions
themselves. Another advantage of this script is that the < a href = "#HiddenParams" > hidden
parameters< / a > are handled for you; the comments indicate when parameters
have been hidden.< / p >
< h2 > < a name = "Parameters" > Parameters and Types< / a > < / h2 >
< p > This section briefly describes the XPCOM type support in
Python.< / p >
< p > All XPCOM interfaces define parameters of a specific type. There is
currently no concept of a variant, or union of all types. Thus, the
conversion rules are very straightforward, and generally surprise free: for
any given XPCOM method, there is only one possible type for a given parameter.< / p >
< h3 > Type Conversion Rules:< / h3 >
< ul >
< li > All numeric types will attempt to be coerced to the correct type.
Thus, you can pass a Python float to an XPCOM method expecting an integer,
or vice-versa. Specifically, when an integer is required, you can pass
any Python object for which < i > int()< / i > would succeed; for a Python float,
any object for which < i > float()< / i > would succeed is acceptable. This
means that you can pass a Python string object as an integer, as long as the
string was holding a valid integer.< / li >
< li > Strings and Unicode objects are interchangeable, but no other automatic
string conversions are performed. Thus, you can not pass an integer
where a string is expected, even though the reverse is true.< / li >
< li > Any sequence object can be passed as an array. List objects are
always returned for arrays.< / li >
< li > Any Python instance suitable for use as a XPCOM object (i.e., with the
< a href = "#Implementing" > necessary annotations< / a > ) can be
passed as a XPCOM object. No special wrapping step is needed to turn a
Python instance into a XPCOM object. Note you must pass a class < i > instance< / i > ,
not the class itself.< / li >
< li > < a name = "HiddenParams" > Many XPCOM < b > method signatures< / b > specify
" count" or " size" parameters. For example, every
time an array is passed via XPCOM, the method signature will always specify
an integer that holds the count of the array. These parameters are
always hidden in Python. As the size param can be implied from the
length of the Python sequence passed, the Python programmer need never pass
these parameters; in contrast, JavaScript requires these redundant parameters.< / a > < / li >
< / ul >
2001-05-27 06:51:18 +04:00
< h2 > Interface Flattening< / h2 >
< p > Most people can ignore this information - Python XPCOM objects just
work. However, if you are familiar with xpcom from C++ and the concept of < i > QueryInterface< / i > ,
you may like to read this.< / p >
< p > Most components support the concept of " interface
flattening" . Such objects can report the interfaces they support,
allowing languages such as Python and Javascript avoid using < i > QueryInterface< / i > .
When you are using an XPCOM object from Python, you can just call methods and
reference properties without regard for the interface that implements it.< / p >
< p > When multiple interfaces share the same method or property name, you can use
the name of the interface as a differentiator. Thus, < i > ob.nsIFoo.close()< / i >
will call close on < i > ob< / i > 's < i > nsIFoo< / i > interface, while < i > ob.nsIBar.close()< / i >
will use the < i > nsIBar< / i > interface. < i > ob.close()< / i > is not defined.< / p >
2001-02-19 08:24:45 +03:00
< / body >
< / html >
