|
1 | | -"""Policies |
| 1 | +"""Policies |
2 | 2 |
|
3 | 3 | Note that Dispatchers are now implemented in "dispatcher.py", but |
4 | 4 | are still documented here. |
5 | 5 |
|
6 | 6 | Policies |
7 | 7 |
|
8 | | - A policy is an object which manages the interaction between a public |
9 | | - Python object, and COM . In simple terms, the policy object is the |
10 | | - object which is actually called by COM, and it invokes the requested |
11 | | - method, fetches/sets the requested property, etc. See the |
| 8 | + A policy is an object which manages the interaction between a public |
| 9 | + Python object, and COM . In simple terms, the policy object is the |
| 10 | + object which is actually called by COM, and it invokes the requested |
| 11 | + method, fetches/sets the requested property, etc. See the |
12 | 12 | @win32com.server.policy.CreateInstance@ method for a description of |
13 | 13 | how a policy is specified or created. |
14 | 14 |
|
15 | | - Exactly how a policy determines which underlying object method/property |
16 | | - is obtained is up to the policy. A few policies are provided, but you |
17 | | - can build your own. See each policy class for a description of how it |
| 15 | + Exactly how a policy determines which underlying object method/property |
| 16 | + is obtained is up to the policy. A few policies are provided, but you |
| 17 | + can build your own. See each policy class for a description of how it |
18 | 18 | implements its policy. |
19 | 19 |
|
20 | | - There is a policy that allows the object to specify exactly which |
21 | | - methods and properties will be exposed. There is also a policy that |
22 | | - will dynamically expose all Python methods and properties - even those |
| 20 | + There is a policy that allows the object to specify exactly which |
| 21 | + methods and properties will be exposed. There is also a policy that |
| 22 | + will dynamically expose all Python methods and properties - even those |
23 | 23 | added after the object has been instantiated. |
24 | 24 |
|
25 | 25 | Dispatchers |
26 | 26 |
|
27 | | - A Dispatcher is a level in front of a Policy. A dispatcher is the |
28 | | - thing which actually receives the COM calls, and passes them to the |
29 | | - policy object (which in turn somehow does something with the wrapped |
| 27 | + A Dispatcher is a level in front of a Policy. A dispatcher is the |
| 28 | + thing which actually receives the COM calls, and passes them to the |
| 29 | + policy object (which in turn somehow does something with the wrapped |
30 | 30 | object). |
31 | 31 |
|
32 | 32 | It is important to note that a policy does not need to have a dispatcher. |
33 | | - A dispatcher has the same interface as a policy, and simply steps in its |
34 | | - place, delegating to the real policy. The primary use for a Dispatcher |
35 | | - is to support debugging when necessary, but without imposing overheads |
| 33 | + A dispatcher has the same interface as a policy, and simply steps in its |
| 34 | + place, delegating to the real policy. The primary use for a Dispatcher |
| 35 | + is to support debugging when necessary, but without imposing overheads |
36 | 36 | when not (ie, by not using a dispatcher at all). |
37 | 37 |
|
38 | | - There are a few dispatchers provided - "tracing" dispatchers which simply |
39 | | - prints calls and args (including a variation which uses |
40 | | - win32api.OutputDebugString), and a "debugger" dispatcher, which can |
| 38 | + There are a few dispatchers provided - "tracing" dispatchers which simply |
| 39 | + prints calls and args (including a variation which uses |
| 40 | + win32api.OutputDebugString), and a "debugger" dispatcher, which can |
41 | 41 | invoke the debugger when necessary. |
42 | 42 |
|
43 | 43 | Error Handling |
44 | 44 |
|
45 | 45 | It is important to realise that the caller of these interfaces may |
46 | | - not be Python. Therefore, general Python exceptions and tracebacks aren't |
| 46 | + not be Python. Therefore, general Python exceptions and tracebacks aren't |
47 | 47 | much use. |
48 | 48 |
|
49 | | - In general, there is an COMException class that should be raised, to allow |
| 49 | + In general, there is an COMException class that should be raised, to allow |
50 | 50 | the framework to extract rich COM type error information. |
51 | 51 |
|
52 | | - The general rule is that the **only** exception returned from Python COM |
53 | | - Server code should be an COMException instance. Any other Python exception |
54 | | - should be considered an implementation bug in the server (if not, it |
55 | | - should be handled, and an appropriate COMException instance raised). Any |
56 | | - other exception is considered "unexpected", and a dispatcher may take |
| 52 | + The general rule is that the **only** exception returned from Python COM |
| 53 | + Server code should be an COMException instance. Any other Python exception |
| 54 | + should be considered an implementation bug in the server (if not, it |
| 55 | + should be handled, and an appropriate COMException instance raised). Any |
| 56 | + other exception is considered "unexpected", and a dispatcher may take |
57 | 57 | special action (see Dispatchers above) |
58 | 58 |
|
59 | | - Occasionally, the implementation will raise the policy.error error. |
60 | | - This usually means there is a problem in the implementation that the |
| 59 | + Occasionally, the implementation will raise the policy.error error. |
| 60 | + This usually means there is a problem in the implementation that the |
61 | 61 | Python programmer should fix. |
62 | 62 |
|
63 | | - For example, if policy is asked to wrap an object which it can not |
64 | | - support (because, eg, it does not provide _public_methods_ or _dynamic_) |
65 | | - then policy.error will be raised, indicating it is a Python programmers |
| 63 | + For example, if policy is asked to wrap an object which it can not |
| 64 | + support (because, eg, it does not provide _public_methods_ or _dynamic_) |
| 65 | + then policy.error will be raised, indicating it is a Python programmers |
66 | 66 | problem, rather than a COM error. |
67 | | - |
68 | 67 | """ |
69 | 68 |
|
70 | 69 | __author__ = "Greg Stein and Mark Hammond" |
|
0 commit comments