From f215e02bf85f68d3a6106c2a1f4f7f063f819064 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Thu, 11 Apr 2024 10:17:27 +0200 Subject: Adding upstream version 7.0.14-dfsg. Signed-off-by: Daniel Baumann --- src/libs/xpcom18a4/python/doc/advanced.html | 176 +++++++++++++++ src/libs/xpcom18a4/python/doc/architecture.html | 116 ++++++++++ src/libs/xpcom18a4/python/doc/configure.html | 196 ++++++++++++++++ src/libs/xpcom18a4/python/doc/credits.html | 86 +++++++ src/libs/xpcom18a4/python/doc/tutorial.html | 286 ++++++++++++++++++++++++ 5 files changed, 860 insertions(+) create mode 100644 src/libs/xpcom18a4/python/doc/advanced.html create mode 100644 src/libs/xpcom18a4/python/doc/architecture.html create mode 100644 src/libs/xpcom18a4/python/doc/configure.html create mode 100644 src/libs/xpcom18a4/python/doc/credits.html create mode 100644 src/libs/xpcom18a4/python/doc/tutorial.html (limited to 'src/libs/xpcom18a4/python/doc') diff --git a/src/libs/xpcom18a4/python/doc/advanced.html b/src/libs/xpcom18a4/python/doc/advanced.html new file mode 100644 index 00000000..ab6994fc --- /dev/null +++ b/src/libs/xpcom18a4/python/doc/advanced.html @@ -0,0 +1,176 @@ + + + + + + + +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/src/libs/xpcom18a4/python/doc/architecture.html b/src/libs/xpcom18a4/python/doc/architecture.html new file mode 100644 index 00000000..d12a2a76 --- /dev/null +++ b/src/libs/xpcom18a4/python/doc/architecture.html @@ -0,0 +1,116 @@ + + + + + + + +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/src/libs/xpcom18a4/python/doc/configure.html b/src/libs/xpcom18a4/python/doc/configure.html new file mode 100644 index 00000000..e2b5d416 --- /dev/null +++ b/src/libs/xpcom18a4/python/doc/configure.html @@ -0,0 +1,196 @@ + + + + + + + +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/src/libs/xpcom18a4/python/doc/credits.html b/src/libs/xpcom18a4/python/doc/credits.html new file mode 100644 index 00000000..2be7809f --- /dev/null +++ b/src/libs/xpcom18a4/python/doc/credits.html @@ -0,0 +1,86 @@ + + + + + + + + +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/src/libs/xpcom18a4/python/doc/tutorial.html b/src/libs/xpcom18a4/python/doc/tutorial.html new file mode 100644 index 00000000..808d4c06 --- /dev/null +++ b/src/libs/xpcom18a4/python/doc/tutorial.html @@ -0,0 +1,286 @@ + + + + + + + +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.

+ + + + + + -- cgit v1.2.3