casacore
Converters.h
Go to the documentation of this file.
1 //# Converters.h: The Converters module - Boost.Python converters
2 //# Copyright (C) 2006
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id: Converters.h,v 1.1 2006/12/13 01:24:15 gvandiep Exp $
27 
28 #ifndef PYRAP_CONVERTERS_H
29 #define PYRAP_CONVERTERS_H
30 
31 //# Includes
32 #include <casacore/python/Converters/PycBasicData.h>
33 #include <casacore/python/Converters/PycRecord.h>
34 #include <casacore/python/Converters/PycValueHolder.h>
35 #include <casacore/python/Converters/PycExcp.h>
36 
37 
38 namespace casacore { //# NAMESPACE CASACORE - BEGIN
39 
40 // <module>
41 
42 // <summary>
43 // Convert Casacore objects to/from Python (using Boost.Python)
44 // </summary>
45 
46 // <use visibility=export>
47 
48 // <reviewed reviewer="" date="" tests="tConvert" demos="">
49 // </reviewed>
50 
51 // <prerequisite>
52 // <li> <linkto class="Record">Record</linkto> class
53 // <li> <linkto class="ValueHolder">Record</linkto> class
54 // </prerequisite>
55 
56 // <synopsis>
57 // Converters contains functions to convert the important Casacore objects
58 // to/from Python using the Boost.Python package.
59 // Converters for the following Casacore classes exist:
60 // <ul>
61 // <li> Scalars of basic data types like Bool, Int, Float, Complex.
62 // <li> casacore::String and std::string.
63 // <li> casacore::Vector and std::vector of any type which can be converted
64 // from a Python scalar, list, tuple, or 1-dim array. They are converted
65 // back to a Python list.
66 // <li> Record which is converted to/from a Python dict.
67 // <li> ValueHolder which is converted to/from the appropriate Python type.
68 // A ValueHolder is a class which can hold various value types:
69 // <ul>
70 // <li> Scalar of any basic data type.
71 // <li> Record.
72 // <li> N-dim Array of any basic data type. A casacore::Array can be
73 // constructed from Python types like tuple, list, and numpy array
74 // A Py_None object results in an empty array.
75 // The conversion back is done to a numpy array.
76 // An empty array is returned as an empty numpy array.
77 // <br>Because Casacore arrays are in Fortran order and numpy arrays
78 // (preferably) in C order, the axes are reversed during conversion.
79 // <br>A 1-dim <src>Array<String></src> object is converted to a list,
80 // while a higher dimensioned Array<String> object is converted to/from
81 // a dict containing the shape and the values as a list.
82 // However, conversion from a numpy string array is supported.
83 // </ul>
84 // A ValueHolder is for instance used by the Table System to be able
85 // to get or put data in a column of any type.
86 // It can be used by any Python binding to convert arrays. Class
87 // ValueHolder has functions to get or set the array.
88 // <li> casacore::IPosition which can be converted
89 // from a Python scalar, list, tuple, or 1-dim array.
90 // It is converted back to a Python list.
91 // An IPosition object represents an array shape or position, so its
92 // values are reversed because of the different ordening of
93 // Casacore and Python arrays.
94 // <li> Exceptions, which are mapped to a Python <src>RuntimeError</src>
95 // exception. Only the <src>casacore::IterError</src> exception is mapped
96 // to a Python <src>StopIteration</src> exception.
97 // </ul>
98 // The converts from Python to C++ can handle some special numpy objects.
99 // Such objects can also be contained in sequences or dicts.
100 // <ul>
101 // <li> Elements in a numpy array are called array scalars. They do not have
102 // a python type such as <src>int</src>, but instead a type as
103 // <src>numpy.int32</src>.
104 // The converters can handle such types and convert them correctly to
105 // a scalar.
106 // <li> A numpy scalar array (e.g. <src>array(1.0)</src> is a somewhat
107 // peculiar numpy object. It has an empty shape and cannot be indexed.
108 // It is handled correctly by the from converters and handled as a
109 // scalar value.
110 // <li> An empty numpy object (e.g. <src>array([])</src>) is handled as
111 // a None value.
112 // </ul>
113 // </synopsis>
114 
115 // </module>
116 
117 } //# NAMESPACE CASACORE - END
118 
119 #endif
this file contains all the compiler specific defines
Definition: mainpage.dox:28