source: trunk/sphinxdocs/source/imports.rst @ 1168

Last change on this file since 1168 was 1168, checked in by toby, 8 years ago

update imports to provide error messages

File size: 8.1 KB
Line 
1*GSAS-II Import Modules*
2====================================
3
4Imports are implemented by deriving a class from
5:class:`GSASIIIO.ImportPhase`, :class:`GSASIIIO.ImportStructFactor`
6or :class:`GSASIIIO.ImportPowderData` (which are in turn
7derived from :class:`GSASIIIO.ImportBaseclass`)
8to implement import of
9a phase, a single crystal or a powder dataset, respectively.
10Module file names (`G2phase_`, `G2pwd_` and `G2sfact_`) are used to
11determine which menu an import routine should be placed into. (N.B. this
12was an unnecessary choice; this could be done from the class used.)
13
14Writing an Import Routine
15--------------------------
16
17.. _Import_routines:
18
19
20When writing a import routine, one should create a new class derived
21from :class:`GSASIIIO.ImportPhase`, :class:`GSASIIIO.ImportStructFactor`
22or :class:`GSASIIIO.ImportPowderData`. As described below,
23all these classes will implement
24an ``__init__()`` and a ``Reader()`` method, and most will supply a
25``ContentsValidator()`` method, too.
26See the :class:`~GSASIIIO.ImportPhase`, :class:`~GSASIIIO.ImportStructFactor`
27or :class:`~GSASIIIO.ImportPowderData` class documentation
28for details on what values each type of ``Reader()`` should set.
29
30__init__()
31~~~~~~~~~~~~~~
32 
33The class should supply a
34``__init__`` method which calls the parent ``__init__`` method and
35specifies the following parameters:
36
37  * `extensionlist`: a list of extensions that may be used for this type of file.
38  * `strictExtension`: Should be True if only files with extensions in
39    `extensionlist` are allows; False if all file types should be offered
40    in the file browser. Also if False, the import class will be
41    used on all files when "guess from format" is tried, though
42    readers with matching extensions will be tried first.
43  * `formatName`: a string to be used in the menu. Should be short.
44  * `longFormatName`: a longer string to be used to describe the format in help.
45
46Reader()
47~~~~~~~~~~~~~~
48
49The class must supply a ``Reader`` method that actually performs the
50reading. All readers must have at a minimum these arguments::
51
52    def Reader(self, filename, filepointer, ParentFrame, **unused):
53
54where the arguments have the following uses:
55
56 * `filename`: a string with the name of the file being read
57 * `filepointer`: a file object (created by :func:`open`) that accesses
58   the file and is points to the beginning of the file when Reader is
59   called.
60 * `ParentFrame`: a reference to the main GSAS-II (tree) windows, for
61   the unusual ``Reader`` routines that will create GUI windows to ask
62   questions.
63
64In addition, the following keyword parameters are defined that ``Reader``
65routines may optionally use:
66
67 * `buffer`: a dict that can be used to retain information between repeated calls of the routine
68 * `blocknum`: counts the number of times that a reader is called
69 * `usedRanIdList`: a list of previously used random Id values that can be checked to determine that a value is unique.
70
71As an example, the `buffer` dict is used for CIF reading to hold the parsed CIF file
72so that it can be reused without having to reread the file from
73scratch.
74
75Reader return values
76______________________
77
78The ``Reader`` routine should return the value of True if the file has been
79read successfully. Optionally, use `self.warnings` to indicate any
80problems.
81
82If the file cannot be read,  the ``Reader`` routine should
83return False or raise an :class:`GSASIIIO.ImportBaseclass.ImportException`
84exception. (Why either? Sometimes an exception is the easiest way to
85bail out of a called routine.) Place text in `self.errors` and/or use::
86
87     ImportException('Error message')
88
89to give the user information on what went wrong during the reading.
90
91self.warnings
92_____________________
93
94Use `self.warnings` to indicate any information
95that should be displayed to the user if the file is read successfully,
96but perhaps not completely or additional settings will need to be
97made.
98
99self.errors
100_____________________
101
102Use `self.errors` to give the user information on where and why a read
103error occurs in the file. Note that text supplied with the ``raise``
104statement will be appended to ``self.errors``.
105
106self.repeat
107_____________________
108
109Set `self.repeat` to True (the default is False) if a Reader should be
110called again to read a second block from a file. Most commonly
111(only?) used for reading multiple powder histograms from a single
112file. Variable `self.repeatcount` is used to keep track of the block
113numbers.
114
115*support routines*
116_________________________
117Note that the base class (:class:`GSASIIIO.ImportBaseclass`) supplies two routines,
118:meth:`~GSASIIIO.ImportBaseclass.BlockSelector` and
119:meth:`~GSASIIIO.ImportBaseclass.MultipleBlockSelector` that are useful for
120selecting amongst one or more datasets (and perhaps phases) for
121``Reader()`` routines that may encounter more than one set of information
122in a file.
123Likewise, when an operation will take some time to complete,
124use :meth:`~GSASIIIO.ImportBaseclass.ShowBusy` and
125:meth:`~GSASIIIO.ImportBaseclass.DoneBusy` to show the user
126that something is happening.
127
128
129ContentsValidator()
130~~~~~~~~~~~~~~~~~~~~
131
132Defining a ``ContentsValidator`` method is optional, but is usually a
133good idea, particularly if the file extension is not a reliable
134identifier for the file type. The intent of this routine is to take a
135superficial look at the file to see if it has the expected
136characteristics of the expected file type. For example, are there
137numbers in the expected places?
138
139This routine is passed a single argument:
140
141* `filepointer`: a file object (created by :func:`open`) that accesses
142  the file and is points to the beginning of the file when ContentsValidator is
143  called.
144
145Note that :meth:`GSASIIIO.ImportBaseclass.CIFValidator` is a ContentsValidator
146for validating CIF files.
147
148
149ContentsValidator return values
150________________________________
151
152The ``ContentsValidator`` routine should return the value of True if
153the file appears to match the type expected for the class.
154
155If the file cannot be read by this class,  the routine should
156return False. Preferably one will also place text in `self.errors` 
157to give the user information on what went wrong during the reading.
158
159Currently Defined Phase Import Routines
160----------------------------------------
161Phase import routines are classes derived from
162:class:`GSASIIIO.ImportPhase`
163They must be found in files named `G2phase*.py` that are in the Python path
164and the class must override the ``__init__`` method and add a ``Reader`` method.
165The distributed routines are:
166
167.. automodule:: G2phase
168    :members: 
169    :synopsis: Uses previously implemented code: PDB and GSAS .EXP
170
171.. automodule:: G2phase_GPX
172    :members: 
173    :synopsis: Reads phase information from a GSAS-II project (.gpx) file
174      a text file.
175
176.. automodule:: G2phase_CIF
177    :members: 
178    :synopsis: Reads phase information from a CIF
179
180Currently Defined Powder Data Import Routines
181---------------------------------------------
182Powder data import routines are classes derived from
183:class:`GSASIIIO.ImportPowderData`.
184They must be found in files named `G2pwd*.py` that are in the Python path
185and the class must override the ``__init__`` method and add a ``Reader`` method.
186The distributed routines are:
187
188.. automodule:: G2pwd_GPX
189    :members: 
190    :synopsis: Reads powder data from from a GSAS-II project (.gpx) file
191
192.. automodule:: G2pwd_fxye
193    :members: 
194    :synopsis: Reads powder data in all of the GSAS formats
195
196.. automodule:: G2pwd_xye
197    :members: 
198    :synopsis: Reads powder data from a Topas format file
199
200.. automodule:: G2pwd_CIF
201    :members: 
202    :synopsis: Reads powder data from a CIF
203
204Currently Defined Single Crystal Data Import Routines
205-----------------------------------------------------
206Single crystal data import routines are classes derived from
207, :class:`GSASIIIO.ImportStructFactor`.
208They must be found in files named `G2sfact*.py` that are in the Python path
209and the class must override the ``__init__`` method and add a ``Reader`` method.
210The distributed routines are:
211
212.. automodule:: G2sfact
213    :members: 
214    :synopsis: Reads single crystal data from simple hkl files
215
216.. automodule:: G2sfact_CIF
217    :members: 
218    :synopsis: Reads single crystal data from CIF files
Note: See TracBrowser for help on using the repository browser.