Skip to content

Commit bf54179

Browse files
committed
Make doctests run on io.fits docs
1 parent c5c665a commit bf54179

12 files changed

Lines changed: 687 additions & 599 deletions

File tree

8.44 KB
Binary file not shown.
8.44 KB
Binary file not shown.
5.63 KB
Binary file not shown.
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
SIMPLE = T / conforms to FITS standard BITPIX = 8 / array data type NAXIS = 0 / number of array dimensions HISTORY I updated this file on 02/03/2011 HISTORY I updated this file on 02/04/2011 END
8.44 KB
Binary file not shown.

‎astropy/io/fits/tests/test_hdulist.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -695,6 +695,11 @@ def test_fromstring(filename):
695695
# versions of Numpy on Windows. See PyFITS ticket
696696
# https://aeon.stsci.edu/ssb/trac/pyfits/ticket/174
697697
continue
698+
elif filename.endswith('variable_length_table.fits'):
699+
# Comparing variable length arrays is non-trivial and thus
700+
# skipped at this point.
701+
# TODO: That's probably possible, so one could make it work.
702+
continue
698703
test_fromstring(filename)
699704

700705
# Test that creating an HDUList from something silly raises a TypeError

‎docs/io/fits/appendix/faq.rst‎

Lines changed: 48 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -117,11 +117,7 @@ the value of a non-existent keyword in a header::
117117
>>> h = fits.Header()
118118
>>> h['NAXIS']
119119
Traceback (most recent call last):
120-
File "<stdin>", line 1, in <module>
121-
File "/path/to/astropy/io/fits/header.py", line 125, in __getitem__
122-
return self._cards[self._cardindex(key)].value
123-
File "/path/to/astropy/io/fits/header.py", line 1535, in _cardindex
124-
raise KeyError("Keyword %r not found." % keyword)
120+
...
125121
KeyError: "Keyword 'NAXIS' not found."
126122

127123
This indicates that something was looking for a keyword called "NAXIS" that
@@ -232,20 +228,8 @@ is likely to cause more difficulties than it's worth.
232228
How do I open a very large image that won't fit in memory?
233229
----------------------------------------------------------
234230

235-
In PyFITS, prior to version 3.1, when the data portion of an HDU is accessed,
236-
the data is read into memory in its entirety. For example::
237-
238-
>>> hdul = pyfits.open('myimage.fits')
239-
>>> hdul[0].data
240-
...
241-
242-
reads the entire image array from disk into memory. For very large images or
243-
tables this is clearly undesirable, if not impossible given the available
244-
resources.
245-
246-
However, `astropy.io.fits.open` has an option to access the data portion of an
247-
HDU by memory mapping using `mmap`_. In both Astropy and newer versions of
248-
PyFITS this is used by *default*.
231+
`astropy.io.fits.open` has an option to access the data portion of an
232+
HDU by memory mapping using `mmap`_. In Astropy this is used by *default*.
249233

250234
What this means is that accessing the data as in the example above only reads
251235
portions of the data into memory on demand. For example, if I request just a
@@ -329,17 +313,26 @@ it, because it doesn't happen until the data portion of the HDU is accessed
329313
(to allow things like updating the header without rescaling the data). For
330314
example::
331315

332-
>>> hdul = fits.open('scaled.fits')
333-
>>> image = hdul['SCI', 1]
316+
>>> from astropy.utils.data import get_pkg_data_filename
317+
>>> def _(filename):
318+
... """For real usage you would just pass your filename/-object to
319+
... "fits.open" directly but to make this documentation testable it
320+
... needs to access data from the astropy package.
321+
... """
322+
... return get_pkg_data_filename(
323+
... 'io/fits/tests/data/{}'.format(filename), 'astropy')
324+
325+
>>> hdul = fits.open(_('scale.fits'))
326+
>>> image = hdul[0]
334327
>>> image.header['BITPIX']
335-
32
328+
16
336329
>>> image.header['BSCALE']
337-
2.0
330+
0.045777764213996
338331
>>> data = image.data # Read the data into memory
339-
>>> data.dtype
340-
dtype('float64') # Got float64 despite BITPIX = 32 (32-bit int)
332+
>>> data.dtype.name # Got float32 despite BITPIX = 16 (16-bit int)
333+
'float32'
341334
>>> image.header['BITPIX'] # The BITPIX will automatically update too
342-
-64
335+
-32
343336
>>> 'BSCALE' in image.header # And the BSCALE keyword removed
344337
False
345338

@@ -355,6 +348,7 @@ If the data must be returned to integers before saving, use the `ImageHDU.scale
355348
>>> image.scale('int32')
356349
>>> image.header['BITPIX']
357350
32
351+
>>> hdul.close() # close the file again
358352

359353
Alternatively, if a file is opened with ``mode='update'`` along with the
360354
``scale_back=True`` argument, the original BSCALE and BZERO scaling will
@@ -368,10 +362,11 @@ you don't intend for the code to access the data, it's good to err on the side
368362
of caution here), use the ``do_not_scale_image_data`` argument when opening
369363
the file::
370364

371-
>>> hdul = fits.open('scaled.fits', do_not_scale_image_data=True)
372-
>>> image = hdul['SCI', 1]
373-
>>> image.data.dtype
374-
dtype('int32')
365+
>>> hdul = fits.open(_('scale.fits'), do_not_scale_image_data=True)
366+
>>> image = hdul[0]
367+
>>> image.data.dtype.name
368+
'int16'
369+
>>> hdul.close() # close the file again
375370

376371

377372
Why am I losing precision when I assign floating point values in the header?
@@ -443,16 +438,16 @@ I'm opening many FITS files in a loop and getting OSError: Too many open files
443438

444439
Say you have some code like:
445440

446-
.. doctest-skip::
441+
.. code:: python
442+
443+
from astropy.io import fits
444+
445+
for filename in filenames:
446+
with fits.open(filename) as hdul:
447+
for hdu in hdul:
448+
hdu_data = hdul.data
449+
# Do some stuff with the data
447450
448-
>>> from astropy.io import fits
449-
>>> for filename in filenames:
450-
... hdul = fits.open(filename)
451-
... for hdu in hdul:
452-
... hdu_data = hdul.data
453-
... # Do some stuff with the data
454-
... hdul.close()
455-
...
456451
457452
The details may differ, but the qualitative point is that the data to many
458453
HDUs and/or FITS files are being accessed in a loop. This may result in
@@ -476,21 +471,21 @@ persists, the data array attached to it may persist too. The easiest
476471
workaround is to *manually* delete the ``.data`` attribute on the HDU object so
477472
that the `~numpy.ndarray` reference is freed and the mmap can be closed:
478473

479-
.. doctest-skip::
474+
.. code:: python
475+
476+
from astropy.io import fits
477+
478+
for filename in filenames:
479+
with fits.open(filename) as hdul:
480+
for hdu in hdul:
481+
hdu_data = hdul.data
482+
# Do some stuff with the data
483+
# ...
484+
# Don't need the data anymore; delete all references to it
485+
# so that it can be garbage collected
486+
del hdu_data
487+
del hdu.data
480488
481-
>>> from astropy.io import fits
482-
>>> for filename in filenames:
483-
... hdul = fits.open(filename)
484-
... for hdu in hdul:
485-
... hdu_data = hdul.data
486-
... # Do some stuff with the data
487-
... # ...
488-
... # Don't need the data anymore; delete all references to it
489-
... # so that it can be garbage collected
490-
... del hdu_data
491-
... del hdu.data
492-
... hdul.close()
493-
...
494489
495490
In some extreme cases files are opened and closed fast enough that Python's
496491
garbage collector does not free them (and hence free the file handles) often

0 commit comments

Comments
 (0)