Skip to content

Commit ba3a657

Browse files
junkmdjunkmd
authored
Split documentation into multiple pages (part 3 of #722). (#725)
* Rename the documentation file temporarily and make `npsupport.rst`. * Revert temporarily renaming documentation file and make `threading.rst`. * Revert `master_doc` in `conf.py` to reflect the temporary module name change.
1 parent 97b09a8 commit ba3a657

4 files changed

Lines changed: 277 additions & 1 deletion

File tree

‎docs/source/conf.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@
4545
# source_encoding = 'utf-8-sig'
4646

4747
# The master toctree document.
48-
master_doc = "main"
48+
master_doc = "index"
4949

5050
# General information about the project.
5151
project = "comtypes"

docs/source/main.rst renamed to docs/source/index.rst

File renamed without changes.

‎docs/source/npsupport.rst‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
####################
2+
The comtypes package
3+
####################
4+
5+
|comtypes| is a *pure Python* COM package based on the ctypes_ ffi
6+
foreign function library. |ctypes| is included in Python 2.5 and
7+
later, it is also available for Python 2.4 as separate download.
8+
9+
While the pywin32_ package contains superior client side support
10+
for *dispatch based* COM interfaces, it is not possible to access
11+
*custom* COM interfaces unless they are wrapped in C++-code.
12+
13+
The |comtypes| package makes it easy to access and implement both
14+
custom and dispatch based COM interfaces.
15+
16+
17+
.. contents::
18+
19+
NumPy interop
20+
*************
21+
22+
NumPy provides the *de facto* array standard for Python. Though NumPy
23+
is not required to use |comtypes|, |comtypes| provides various options for
24+
NumPy interoperability. NumPy version 1.7 or greater is required to access
25+
all of these features.
26+
27+
28+
NumPy Arrays as Input Arguments
29+
+++++++++++++++++++++++++++++++
30+
31+
NumPy arrays can be passed as ``VARIANT`` arrays arguments. The array is
32+
converted to a SAFEARRAY according to its type. The type conversion
33+
is defined by the ``numpy.ctypeslib`` module. The following table
34+
shows type conversions that can be performed quickly by (nearly) direct
35+
conversion of a numpy array to a SAFEARRAY. Arrays with type that do not
36+
appear in this table, including object arrays, can still be converted to
37+
SAFEARRAYs on an item-by-item basis.
38+
39+
+------------------------------------------------+---------------+
40+
| NumPy type | VARIANT type |
41+
+================================================+===============+
42+
| ``int8`` | VT_I1 |
43+
+------------------------------------------------+---------------+
44+
| ``int16``, ``short`` | VT_I2 |
45+
+------------------------------------------------+---------------+
46+
| ``int32``, ``int``, ``intc``, ``int_`` | VT_I4 |
47+
+------------------------------------------------+---------------+
48+
| ``int64``, ``long``, ``longlong``, ``intp`` | VT_I8 |
49+
+------------------------------------------------+---------------+
50+
| ``uint8``, ``ubyte`` | VT_UI1 |
51+
+------------------------------------------------+---------------+
52+
| ``uint16``, ``ushort`` | VT_UI2 |
53+
+------------------------------------------------+---------------+
54+
| ``uint32``, ``uint``, ``uintc`` | VT_UI4 |
55+
+------------------------------------------------+---------------+
56+
| ``uint64``, ``ulonglong``, ``uintp`` | VT_UI8 |
57+
+------------------------------------------------+---------------+
58+
| ``float32`` | VT_R4 |
59+
+------------------------------------------------+---------------+
60+
| ``float64``, ``float_`` | VT_R8 |
61+
+------------------------------------------------+---------------+
62+
| ``datetime64`` | VT_DATE |
63+
+------------------------------------------------+---------------+
64+
65+
NumPy Arrays as Output Arguments
66+
++++++++++++++++++++++++++++++++
67+
68+
By default, |comtypes| converts SAFEARRAY output arguments to tuples of
69+
python objects on an item-by-item basis. When dealing with large
70+
SAFEARRAYs, this conversion can be costly. Comtypes provides a the
71+
``safearray_as_ndarray`` context manager (from ``comtypes.safearray``)
72+
for modifying this behavior to return a NumPy array. This altered
73+
behavior is to put an ndarray over a copy of the SAFEARRAY's memory,
74+
which is faster than calling into python for each item. When this fails,
75+
a NumPy array can still be created on an item-by-item basis. The context
76+
manager is thread-safe, in that usage of the context manager on one
77+
thread does not affect behavior on other threads.
78+
79+
This is a hypothetical example of using the context manager. The context
80+
manager can be used around any property or method call to retrieve a
81+
NumPy array rather than a tuple.
82+
83+
84+
.. sourcecode:: python
85+
86+
"""Sample demonstrating use of safearray_as_ndarray context manager """
87+
88+
from comtypes.safearray import safearray_as_ndarray
89+
90+
# Hypothetically, this returns a SAFEARRAY as a tuple
91+
data1 = some_interface.some_property
92+
93+
# This will return a NumPy array, and will be faster for basic types.
94+
with safearray_as_ndarray:
95+
data2 = some_interface.some_property
96+
97+
98+
Threading
99+
*********
100+
101+
XXX mention single threaded apartments, multi threaded apartments.
102+
``sys.coinit_flags``, ``CoInitialize``, ``CoUninitialize`` and so on.
103+
All this is pretty advanced stuff.
104+
105+
XXX mention threading issues, message loops
106+
107+
108+
Links
109+
*****
110+
111+
Yaroslav Kourovtsev has written an article_ titled "Working with custom
112+
COM interfaces from Python" that describes how to use |comtypes| to
113+
access a custom COM object.
114+
115+
.. _article: http://www.codeproject.com/KB/COM/python-comtypes-interop.aspx
116+
117+
Downloads
118+
*********
119+
120+
The |comtypes| project is hosted on github_. Releases can be downloaded from
121+
the github releases_ section.
122+
123+
124+
.. |comtypes| replace:: ``comtypes``
125+
126+
.. |ctypes| replace:: ``ctypes``
127+
128+
.. _`WMI monikers`: http://www.microsoft.com/technet/scriptcenter/guide/sas_wmi_jgfx.mspx?mfr=true
129+
130+
.. _ctypes: https://docs.python.org/3/library/ctypes.html
131+
132+
.. _pywin32: https://pypi.org/project/pywin32/
133+
134+
.. _`enum.IntFlag`: https://docs.python.org/3/library/enum.html#enum.IntFlag
135+
136+
.. _github: https://github.com/enthought/comtypes
137+
138+
.. _releases: https://github.com/enthought/comtypes/releases

‎docs/source/threading.rst‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
####################
2+
The comtypes package
3+
####################
4+
5+
|comtypes| is a *pure Python* COM package based on the ctypes_ ffi
6+
foreign function library. |ctypes| is included in Python 2.5 and
7+
later, it is also available for Python 2.4 as separate download.
8+
9+
While the pywin32_ package contains superior client side support
10+
for *dispatch based* COM interfaces, it is not possible to access
11+
*custom* COM interfaces unless they are wrapped in C++-code.
12+
13+
The |comtypes| package makes it easy to access and implement both
14+
custom and dispatch based COM interfaces.
15+
16+
17+
.. contents::
18+
19+
NumPy interop
20+
*************
21+
22+
NumPy provides the *de facto* array standard for Python. Though NumPy
23+
is not required to use |comtypes|, |comtypes| provides various options for
24+
NumPy interoperability. NumPy version 1.7 or greater is required to access
25+
all of these features.
26+
27+
28+
NumPy Arrays as Input Arguments
29+
+++++++++++++++++++++++++++++++
30+
31+
NumPy arrays can be passed as ``VARIANT`` arrays arguments. The array is
32+
converted to a SAFEARRAY according to its type. The type conversion
33+
is defined by the ``numpy.ctypeslib`` module. The following table
34+
shows type conversions that can be performed quickly by (nearly) direct
35+
conversion of a numpy array to a SAFEARRAY. Arrays with type that do not
36+
appear in this table, including object arrays, can still be converted to
37+
SAFEARRAYs on an item-by-item basis.
38+
39+
+------------------------------------------------+---------------+
40+
| NumPy type | VARIANT type |
41+
+================================================+===============+
42+
| ``int8`` | VT_I1 |
43+
+------------------------------------------------+---------------+
44+
| ``int16``, ``short`` | VT_I2 |
45+
+------------------------------------------------+---------------+
46+
| ``int32``, ``int``, ``intc``, ``int_`` | VT_I4 |
47+
+------------------------------------------------+---------------+
48+
| ``int64``, ``long``, ``longlong``, ``intp`` | VT_I8 |
49+
+------------------------------------------------+---------------+
50+
| ``uint8``, ``ubyte`` | VT_UI1 |
51+
+------------------------------------------------+---------------+
52+
| ``uint16``, ``ushort`` | VT_UI2 |
53+
+------------------------------------------------+---------------+
54+
| ``uint32``, ``uint``, ``uintc`` | VT_UI4 |
55+
+------------------------------------------------+---------------+
56+
| ``uint64``, ``ulonglong``, ``uintp`` | VT_UI8 |
57+
+------------------------------------------------+---------------+
58+
| ``float32`` | VT_R4 |
59+
+------------------------------------------------+---------------+
60+
| ``float64``, ``float_`` | VT_R8 |
61+
+------------------------------------------------+---------------+
62+
| ``datetime64`` | VT_DATE |
63+
+------------------------------------------------+---------------+
64+
65+
NumPy Arrays as Output Arguments
66+
++++++++++++++++++++++++++++++++
67+
68+
By default, |comtypes| converts SAFEARRAY output arguments to tuples of
69+
python objects on an item-by-item basis. When dealing with large
70+
SAFEARRAYs, this conversion can be costly. Comtypes provides a the
71+
``safearray_as_ndarray`` context manager (from ``comtypes.safearray``)
72+
for modifying this behavior to return a NumPy array. This altered
73+
behavior is to put an ndarray over a copy of the SAFEARRAY's memory,
74+
which is faster than calling into python for each item. When this fails,
75+
a NumPy array can still be created on an item-by-item basis. The context
76+
manager is thread-safe, in that usage of the context manager on one
77+
thread does not affect behavior on other threads.
78+
79+
This is a hypothetical example of using the context manager. The context
80+
manager can be used around any property or method call to retrieve a
81+
NumPy array rather than a tuple.
82+
83+
84+
.. sourcecode:: python
85+
86+
"""Sample demonstrating use of safearray_as_ndarray context manager """
87+
88+
from comtypes.safearray import safearray_as_ndarray
89+
90+
# Hypothetically, this returns a SAFEARRAY as a tuple
91+
data1 = some_interface.some_property
92+
93+
# This will return a NumPy array, and will be faster for basic types.
94+
with safearray_as_ndarray:
95+
data2 = some_interface.some_property
96+
97+
98+
Threading
99+
*********
100+
101+
XXX mention single threaded apartments, multi threaded apartments.
102+
``sys.coinit_flags``, ``CoInitialize``, ``CoUninitialize`` and so on.
103+
All this is pretty advanced stuff.
104+
105+
XXX mention threading issues, message loops
106+
107+
108+
Links
109+
*****
110+
111+
Yaroslav Kourovtsev has written an article_ titled "Working with custom
112+
COM interfaces from Python" that describes how to use |comtypes| to
113+
access a custom COM object.
114+
115+
.. _article: http://www.codeproject.com/KB/COM/python-comtypes-interop.aspx
116+
117+
Downloads
118+
*********
119+
120+
The |comtypes| project is hosted on github_. Releases can be downloaded from
121+
the github releases_ section.
122+
123+
124+
.. |comtypes| replace:: ``comtypes``
125+
126+
.. |ctypes| replace:: ``ctypes``
127+
128+
.. _`WMI monikers`: http://www.microsoft.com/technet/scriptcenter/guide/sas_wmi_jgfx.mspx?mfr=true
129+
130+
.. _ctypes: https://docs.python.org/3/library/ctypes.html
131+
132+
.. _pywin32: https://pypi.org/project/pywin32/
133+
134+
.. _`enum.IntFlag`: https://docs.python.org/3/library/enum.html#enum.IntFlag
135+
136+
.. _github: https://github.com/enthought/comtypes
137+
138+
.. _releases: https://github.com/enthought/comtypes/releases

0 commit comments

Comments
 (0)