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