From d5c1d3cef6853b6bb77f899ca8806d349c5c3bce Mon Sep 17 00:00:00 2001 From: Tyler Downer Date: Wed, 29 Jul 2009 14:41:32 +0200 Subject: [PATCH] Bug 470575 - Move PyXPCOM docs to dmo; r=mhammond --- extensions/python/xpcom/doc/advanced.html | 176 ----------- extensions/python/xpcom/doc/architecture.html | 116 ------- extensions/python/xpcom/doc/configure.html | 196 ------------ extensions/python/xpcom/doc/credits.html | 86 ------ extensions/python/xpcom/doc/tutorial.html | 286 ------------------ extensions/python/xpcom/readme.html | 121 -------- 6 files changed, 981 deletions(-) delete mode 100644 extensions/python/xpcom/doc/advanced.html delete mode 100644 extensions/python/xpcom/doc/architecture.html delete mode 100644 extensions/python/xpcom/doc/configure.html delete mode 100644 extensions/python/xpcom/doc/credits.html delete mode 100644 extensions/python/xpcom/doc/tutorial.html delete mode 100644 extensions/python/xpcom/readme.html diff --git a/extensions/python/xpcom/doc/advanced.html b/extensions/python/xpcom/doc/advanced.html deleted file mode 100644 index ab6994fcc8d..00000000000 --- a/extensions/python/xpcom/doc/advanced.html +++ /dev/null @@ -1,176 +0,0 @@ - - - - - - - -Python XPCOM Advanced Topics - - - - -

Python XPCOM Advanced Topics

- -

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.

- -

XPCOM Services

-

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 xpcom.components.services 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.

- -

nsIVariant

- -

There is (almost) full support for nsIVariant.  Any nsIVariant -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 nsIVariant object instead of a regular Python -object, thereby allowing explicit control over the type of variant created.

- -

nsISupports Primitives.

- -

There is a set of interfaces described in nsISupportsPrimitives.idl, which I -term collectively the nsISupports Primitives Interfaces.  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 nsISupportsCString 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 nsISupportsPRBool interface.

-

When you call an XPCOM object (i.e., you have an XPCOM interface you are -calling), you can use -the builtin functions str(), int(), long() etc., on the -object.  In the -case of str(), if the object does not support the nsISupportsCString -or nsISupportsString interfaces, the default string str() 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 ValueError -exception will be raised if the objects do not support any interface that can be -used for the conversion. ValueError is used instead of TypeError, -as the type itself (i.e., an XPCOM object) can sometimes be used in this context - -hence it is the specific value of the object that is the problem.

-

The use of repr() 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!

-

When you implement an XPCOM object, you have two choices for implementation -of these interfaces:

- -
-

This allows for an interesting feature that would not normally be -possible.  Consider Python code that does a str() on an  XPCOM -interface, and where the XPCOM interface itself is implemented in Python and -provides a __str__ method.  The str() on the original -interface queries for the nsISupportsCString interface.  The -Python implemented object responds to this interface and delegates to the __str__ -method. At the end of all this, str() returns the same result -as if the objects were native Python objects with no XPCOM layer in between.

- -
- -

Enumerators

- -

The primary enumerator used by XPCOM is nsISimpleEnumerator. -Although the Python XPCOM package has full support for nsIEnumerator, -since this interface is not "scriptable", you should avoided using it in interfaces -you design.

- -

When you use nsISimpleEnumerator from Python, the following enhancements -are available:

- -

nsIEnumerator has similar enhancements.

-

When implementing a Python XPCOM object, the Python class xpcom.server.enumerator.SimpleEnumerator() -can be used.  You can pass a standard Python sequence (list, etc), and it -will be correctly wrapped in an nsISimpleEnumerator interface.

-

Files

-

The Python XPCOM package provides an xpcom.file 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.,).

-

See this module for more information, including test code.

-

XPCOM Object Identity

-

XPCOM has defined rules for object identity and for how objects must behave -in their QueryInterface() 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.

-

Policies

-

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 QueryInterface(), 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.

-

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.

- - - - diff --git a/extensions/python/xpcom/doc/architecture.html b/extensions/python/xpcom/doc/architecture.html deleted file mode 100644 index d12a2a76dee..00000000000 --- a/extensions/python/xpcom/doc/architecture.html +++ /dev/null @@ -1,116 +0,0 @@ - - - - - - - -Architecture - - - - -

Python XPCOM Package Architecture

-

Architecture

-

Much of the design for the Python XPCOM Package has been borrowed from the Python MS-COM -extensions in win32com. Most of the major limitations and drawbacks in the win32com -design have been addressed, mainly "auto-wrapping" of -interface objects, which is not supported by win32com.

-

Like win32com, this architecture includes the concept of client COM and server -COM.

-

Client COM:

- -

Server COM:

- -

The XPConnect framework is very powerful, and far exceeds what COM's -IDispatch can offer.  Thus, we are able to get by with far fewer interfaces -supported in the C++ level, and defer most things to the Python code that uses -XPConnect.  As a result, the requirement for a huge number of interfaces to -exist in the .pyd does not exist.  There are, however, a number of -interfaces that do require native C++ support: these are interfaces -required to "boot" the XPConnect support (i.e., the interfaces that are -used to get information about interfaces), and also two gateways that need to -work without interface information available. This last requirement is -due to the XPCOM shutdown-ordering - it may be a bug, but is not an unreasonable -amount of code anyway.

-

Auto-wrapping of COM objects is supported by both client COM and -server COM. For client COM, auto-wrapping means that the -Python programmer always sees Python "component" objects, rather than -raw C++ interface objects; to the user, it all appears to "just -work".  This is a major source of frustration in the win32com -framework.

-

For server COM, auto-wrapping means that you can -pass Python instances wherever a COM object is expected. If the Python -instance supports COM interfaces, by virtue of having a _com_interfaces_ -attribute that lists the interface requested, it will be automatically wrapped -in the correct COM object. 

-

Error Handling: The C++ framework has good error handling support, -and uses the XPCOM console service to log debug messages, Python exceptions and -tracebacks.  win32com does not have good exception/traceback support -at the C++ level, mainly because COM does not define a service like -the console where debug messages can go.  This does mean that in Mozilla -release builds, these debug messages are likely to be lost, but the --console -command line option to a release Mozilla will get them back.  Therefore, -the other error-support utilities, such as the error callbacks made on the -policy object, may be used.

-

Component Loader, Modules and Factories:  XPCOM has the concept -of a component loader - a module used to load all components of a -particular type.  For example, the moz.jsloader.1 component loads all -the JavaScript components. Similarly, the moz.pyloader.1 -component loads all Python components.  However, unlike -JavaScript, the Python component loader is actually implemented in Python -itself! Since the Python component loader can not be used to load -itself, this component has some special code, pyloader.dll, to boot-strap itself.

-

This means is that all XPCOM components, including the Python loader itself and all -XPCOM module and factory interfaces, are implemented in -Python. There are no components or interfaces implemented purely in C++ -in this entire package!

- - - - diff --git a/extensions/python/xpcom/doc/configure.html b/extensions/python/xpcom/doc/configure.html deleted file mode 100644 index e2b5d416b6e..00000000000 --- a/extensions/python/xpcom/doc/configure.html +++ /dev/null @@ -1,196 +0,0 @@ - - - - - - - -Configuring your Environment - - - - -

Building, Configuring and Testing Python XPCOM Package

-

This document attempts to explain how to build, configure and test the -Python XPCOM Package. This document assumes you have already successfully -built -Mozilla from source and your environment is currently set up for such a build - -see the Mozilla build documentation -for more information.

-

PyXPCOM can be built on Windows using either the nmake makefile.win -process, or the configure; gmake process used by Linux.

-

configure; gmake Instructions

-

Preparing for the build

- -

Building

- -

PyXPCOM outside Mozilla

-

When you are using PyXPCOM from inside mozilla, no additional configuration -options should be necessary.  However, if you wish to use PyXPCOM from -stand-alone Python (ie, so you can write simple Python scripts that can be -executed normally and use XPCOM), then additional environment variables must be -setup.

- -
-

Note that on Windows, the PYTHONPATH is generally maintained in the - Registry; however, you can set this variable at a DOS prompt, and it will still be -added to the core PYTHONPATH. -

- -

Testing your Setup

-

The Python XPCOM Package has a complete test suite.

-

In the rest of this section, we walk through some simpler tests a step at a time, -to help diagnose any problems.

-

Note: We recommend you do all your testing outside of mozilla.exe; it is far simpler to test all of -this using the PyXPCOM package stand-alone.

-

Note: On Windows, if you use a debug build of Mozilla (i.e., in dist\WIN32_D.OBJ\bin), - you must use python_d.exe; if you use a release build (i.e., in - a dist\WIN32_O.OBJ\bin directory), you must use python.exe.  -makefile.stupid.win handles this automatically.

-

To test your setup:

-
    -
  1. Start Python, and check
    - >>> import xpcom
    - works. If not, check your PYTHONPATH - the - main PyXPCOM package can not be located.  Also check your PATH, - and if you are on Linux, remember that executing ./run-mozilla.sh python is - the easiest way.
    2. -
  2. Check
    - >>> import xpcom._xpcom
    - -works. If not, then most likely your Mozilla - directory is not on your path, or something is wrong with _xpcom(_d).pyd/_xpcommodule.so.
    3. - -
  3. Next run a simple test: test/test_misc.py. With a Windows debug build, the command may look like:
    - C:\Anywhere> python_d \src\python\xpcom\test\test_misc.py
    -     or on Linux
    - /home/user/src/mozilla/dist/bin$ python /home/user/src/python/xpcom/test/test_misc.py
    4. -
-

If you can't get this going, you won't get much further! (You may see a few -errors - that is OK, as long as it appears something worked!).  If -everything looks OK, the -next step is to register our test component and run our full test suite.

-

Registering the Loader and Test Component

-

First register the generic Python loader. For instructions, see the architecture -document. Do this only once, regardless of how many -Python components you have.  Then install the test component itself, and -finally you can test it!

-

Registering the Python Loader and Component

-

To register the Python Loader and Component:

-
    -
  1. Ensure the build process has put pyloader.dll (or modpyloader.so - for Unix), and the files py_test_component.py and py_test_component.idl into - the Mozilla bin/components directory.  If not, copy the files - there manually.
    2. -
  2. Run regxpcom (or ./run-mozilla.sh ./regxpcom if appropriate). regxpcom is a standard Mozilla - executable, found in the bin directory, that detects the new DLL and - .py - files and registers them accordingly.  You should - see a few messages that include the following:
    3. -
-
- 
Registering: PythonComponentLoader
-Registered 1 Python components in pyloader.dll
-nsNativeComponentLoader: autoregistering succeeded
-Auto-registering all Python components in F:\src\mozilla\dist\WIN32_D.OBJ\bin\components
-Registering: PythonTestComponent
-Registered 1 Python components in py_test_component.py
-
-

If so (or you see no message at all), you are ready to run the test suite.

-

Note: If you execute this same step a second time, you will not -see any of the above mentioned messages. XPCOM knows that nothing has -changed since you last ran regxpcom, so nothing is registered.  If -you do not see these messages the first time you run it, there is the -possibility that some other process, possibly the build process, has already -executed this step.

-

Running the Test Suite

-

Before running the test suite, you should change to the mozilla/xpcom/sample -directory and build it.  This will build and install a sample component -which is used by the test suite.  If you do not have this component -available, some of the Python tests will fail.

- -

To run the test suite, run xpcom/test/regrtest.py.  This runs the -tests and ensures that the test output is as expected.  If all tests -pass, you have a fully functioning Python XPCOM package.  Enjoy!

- - - - diff --git a/extensions/python/xpcom/doc/credits.html b/extensions/python/xpcom/doc/credits.html deleted file mode 100644 index 2be7809fd1f..00000000000 --- a/extensions/python/xpcom/doc/credits.html +++ /dev/null @@ -1,86 +0,0 @@ - - - - - - - - -Credits and Acknowledgements - - - - -

Credits and Acknowledgements

-

ActiveState Tool Corporation

-

The Python XPCOM Package was developed primarily by Mark -Hammond of ActiveState Tool Corporation.

-

The developers on the Komodo -project deserve high praise for putting up with early versions when almost -nothing worked, and for believing in Python as a viable XPCOM language.  -Their feedback and patience has allowed the first public release to be amazingly -functional and bug-free.

-

Komodo Development Team (at December 2000)

-

David Ascher, Aaron Bingham, -Bin Du, Mark -Hammond, Trent Mick (build god),  -Paul Prescod,  Eric Promislow, -Ken Simpson, Neil Watkiss, -Audrey Schumacher.

-

Mozilla/Netscape

-

The following people at Netscape and Mozilla -(or not there but still heavily involved in the project) have provided enormous -help in getting things integrated with their build system, answering us on the -newsgroup, teaching us the finer points of XPCOM, gently slapping us for accidentally -referring to jscript, etc., and otherwise lending us a clue in the -Mozilla/Netscape/XPCOM world.

-

John Bandhauer, Brendan -Eich, Mike Shaver, Eric Vaughan, -David Hyatt

-

External Contributors

-

The following people have made contributions to the project, simply because -they find it useful and enjoy supporting Open Source projects.

-

Christof Meerwald

-

Documentation Credits

-

The following people have contributed to the Python XPCOM Package -documentation 

-

Mark -Hammond, Audrey Schumacher

- - - - diff --git a/extensions/python/xpcom/doc/tutorial.html b/extensions/python/xpcom/doc/tutorial.html deleted file mode 100644 index 808d4c06f50..00000000000 --- a/extensions/python/xpcom/doc/tutorial.html +++ /dev/null @@ -1,286 +0,0 @@ - - - - - - - -Python XPCOM Package Tutorial - - - - -

Python XPCOM Package Tutorial

-

This is a quick introduction to the Python XPCOM Package. We assume that you have a good understanding of Python and XPCOM, -and have experience both using and implementing XPCOM objects in some other -language (e.g., C++ or JavaScript). We do not attempt to -provide a tutorial to XPCOM or Python itself, only to using Python and - XPCOM.

-

This tutorial contains the following sections:

- -

For anything not covered here, try the advanced -documentation, and if that fails, use the source, Luke!

-

Using XPCOM object and interfaces.

-

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.

-

xpcom.components module

-

When using an XPCOM object, the primary module used is the xpcom.components - 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.

-

The xpcom.components module defines the following public -members:

- - - - - - - - - - - - - -
NameDescription
classesA 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.   -

Example:

- 
cls = components.classes["@mozilla.org/sample;1"]
-ob = cls.createInstance() # Now have an nsISupports
-
interfacesAn object that exposes all XPCOM interface IDs (IIDs).  - Like the JavaScript object of the same name, this object uses - "dot" notation, as demonstrated below. -

Example:

- 
ob = cls.createInstance(components.interfaces.nsISample) 
-# Now have an nsISample
-
-

For many people, this is all you need to know. Consider the Mozilla Sample Component.  The Mozilla Sample -Component has a contract ID of @mozilla.org/sample;1, -and implements the nsISample interface.

-

Thus, a complete Python program that uses this component is shown below.

-
from xpcom import components
-cls = components.classes["@mozilla.org/sample;1"]
-ob = cls.createInstance() # no need to specify an IID for most components
-# nsISample defines a "value" property - let's use it!
-ob.value = "new value"
-if ob.value != "new value":
-    print "Eeek - what happened?"
-

And that is it - a complete Python program that uses XPCOM.

-

Implementing XPCOM Objects and Interfaces.

-

Implementing XPCOM objects is almost as simple as using them. The -basic strategy is this:

-
    -
  1. Create a standard Python source file, with a standard Python class.
    2. -
  2. Add some special attributes to your class for use by the Python XPCOM - framework. This controls the XPCOM behavior of your object.
    3. -
  3. Implement the XPCOM properties and methods of your classes as normal.
    4. -
  4. Put the Python source file in the Mozilla components directory.
    5. -
  5. Run regxpcom.
    6. -
-

Your component is now ready to be used.

-

Attributes

-

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.

- - - - - - - - - - - - - - - - - - - - - - - - - -
AttributeDescription
_com_interfaces_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 - nsISupports in the list of interfaces. -

This attribute is required. Objects without such an attribute are - deemed unsuitable for use as a XPCOM object.

_reg_contractid_The contract ID of the component.  Required if the - component requires registration (i.e., exists in the components directory).
_reg_clsid_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).
_reg_registrar_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.
_reg_desc_The description of the XPCOM object. This may be used by - browsers or other such objects.  If not specified, the contract ID - is used.
-

Properties

-

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 boolean_value property.  -Alternatively, the class can provide the get_propertyName(self) and set_propertyName(self, -value) functions (with propertyName changed to the appropriate value for the -property), and these functions will be called instead.

-

Example:  The Python XPCOM Test Component

-

As an example, examine the Python XPCOM Test Component.  This -code can be found in py_test_component.py.

-
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
-...
-

Note: This component only specifies the mandatory attributes - _com_interfaces, -_reg_clsid_ and _reg_contractid_.

-

This sample code demonstrates supporting the boolean_value attribute, -supported implicitly, as it is defined in the IDL and exists as a real Python -attribute of that name, and a method called do_boolean.

-

Tip: The xpcom/xpt.py Script

-

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.

-

This is the output of running this program over the nsISample -interface (i.e., assuming we wanted to implement a component that supported this -interface):

-
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
-

Note: 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 hidden -parameters are handled for you; the comments indicate when parameters -have been hidden.

-

Parameters and Types

-

This section briefly describes the XPCOM type support in -Python.

-

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.

-

Type Conversion Rules:

- - -

Interface Flattening

-

Most people can ignore this information - Python XPCOM objects just -work.  However, if you are familiar with xpcom from C++ and the concept of QueryInterface, -you may like to read this.

-

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 QueryInterface.  -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.

-

When multiple interfaces share the same method or property name, you can use -the name of the interface as a differentiator.  Thus, ob.nsIFoo.close() -will call close on ob's nsIFoo interface, while ob.nsIBar.close() -will use the nsIBar interface.  ob.close() is not defined.

- - - - - - diff --git a/extensions/python/xpcom/readme.html b/extensions/python/xpcom/readme.html deleted file mode 100644 index 112f43e0cf4..00000000000 --- a/extensions/python/xpcom/readme.html +++ /dev/null @@ -1,121 +0,0 @@ - - - - - - - -Python XPCOM module - - - - -

Python XPCOM Package

- -

Mozilla CVS Version - Last updated May 2002

-

This is the readme for the Python interface to XPCOM.

-

XPCOM is an acronym for "Cross Platform COM".  It has -come out of the Mozilla project, which -maintains the main XPCOM -project pages.  The Python XPCOM package is a set of Python bindings to -XPCOM, allowing a Python programmer to both use and implement XPCOM -interfaces.  If you don't know what Python -is, then none of this probably interests you at all!

-

This readme has links to the following information:

- -

Note: This package requires Python 1.6 or later; we recommend using -the latest -official Python version.  This package works -very well with the latest ActivePython, -and does not require any external modules or packages beyond what is provided in -the core Python release for each platform.

-

About the Python XPCOM Package

-

The Python XPCOM Package was developed by ActiveState -Tool Corporation, and came out of their Komodo -project.  The Python XPCOM package is released under the Mozilla -Public License (MPL)

-

Please see the credits file for a list of -contributors.

-

Known Bugs/Issues

- -

Release History

-

Version 0.90 - January 2001

- -

Version 0.91 - January 2001

- - -

Version 0.92 - May 2001

-

Implement interface flattening.  You should (almost) never need to use QueryInterface()!  -We are still 100% backwards compatible, so usage of QI still works - just is -generally not necessary.

- -

Version 0.93 - May 2002

- -

Implement nsIVariant and all new string types.  Complete move to -autoconf build system.

- - - -