@@ -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
127123This 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.
232228How 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
250234What this means is that accessing the data as in the example above only reads
251235portions 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
330314example::
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
359353Alternatively, 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
368362of caution here), use the ``do_not_scale_image_data `` argument when opening
369363the 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
377372Why 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
444439Say 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
458453HDUs 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
476471workaround is to *manually * delete the ``.data `` attribute on the HDU object so
477472that 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
496491garbage collector does not free them (and hence free the file handles) often
0 commit comments