Headers

Header

class pyfits.Header(cards=[], txtfile=None)

Bases: _abcoll.MutableMapping

FITS header class.

The purpose of this class is to present the header like a dictionary as opposed to a list of cards.

The attribute ascard supplies the header like a list of cards.

The header class uses the card’s keyword as the dictionary key and the cards value is the dictionary value.

The has_key, get, and keys methods are implemented to provide the corresponding dictionary functionality. The header may be indexed by keyword value and like a dictionary, the associated value will be returned. When the header contains cards with duplicate keywords, only the value of the first card with the given keyword will be returned.

The header may also be indexed by card list index number. In that case, the value of the card at the given index in the card list will be returned.

A delete method has been implemented to allow deletion from the header. When del is called, all cards with the given keyword are deleted from the header.

The Header class has an associated iterator class _Header_iter which will allow iteration over the unique keywords in the header dictionary.

Construct a Header from a CardList and/or text file.

Parameters:  

cards : A list of Card objects, optional

The cards to initialize the header with.

txtfile : file path, file object or file-like object, optional

Input ASCII header parameters file.

add_blank(value='', before=None, after=None)

Add a blank card.

Parameters:  

value : str, optional

text to be added.

before : str or int, optional

same as in Header.update

after : str or int, optional

same as in Header.update

add_comment(value, before=None, after=None)

Add a COMMENT card.

Parameters:  

value : str

text to be added.

before : str or int, optional

same as in Header.update

after : str or int, optional

same as in Header.update

add_history(value, before=None, after=None)

Add a HISTORY card.

Parameters:  

value : str

history text to be added.

before : str or int, optional

same as in Header.update

after : str or int, optional

same as in Header.update

ascardlist(*args, **kwargs)

Returns a CardList object.

clear() → None. Remove all items from D.

copy(strip=False)

Make a copy of the Header.

Parameters:  

strip : bool, optional

If True, strip any headers that are specific to one of the standard HDU types, so that this header can be used in a different HDU.

fromTxtFile(fileobj, replace=False)

Input the header parameters from an ASCII file.

The input header cards will be used to update the current header. Therefore, when an input card key matches a card key that already exists in the header, that card will be updated in place. Any input cards that do not already exist in the header will be added. Cards will not be deleted from the header.

Parameters:  

fileobj : file path, file object or file-like object

Input header parameters file.

replace : bool, optional

When True, indicates that the entire header should be replaced with the contents of the ASCII file instead of just updating the current header.

classmethod fromstring(data)

Creates an HDU header from a byte string containing the entire header data.

Parameters:  

data : str

String containing the entire header.

get(k[, d]) → D[k] if k in D, else d. d defaults to None.

get_comment()

Get all comment cards as a list of string texts.

get_history()

Get all history cards as a list of string texts.

has_key(*args, **kwargs)

Check for existence of a keyword.

Parameters:  

key : str or int

Keyword name. If given an index, always returns 0.

Returns:  

has_key : bool

Returns True if found, otherwise, False.

items()

Override items since the default implementation does not propertly handle duplicate keywords.

iteritems()

Override iteritems since the default implementation does not properly handle duplicate keywords.

iterkeys() → an iterator over the keys of D

itervalues()

Override itervalues since the default implementation does not properly handle duplicate keywords.

keys()

Return a list of keys with duplicates removed.

Warning

There is a surprising incogruity in Header objecets between Header.keys() and Header.iterkeys(). The latter does not remove duplicates. This incongruity exists for historical reasons, but is not be design. In PyFITS 3.1 it is done away with, and :meth:Header.keys returns the exact keywords appearin the header, including duplicates.

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.

rename_key(oldkey, newkey, force=False)

Rename a card’s keyword in the header.

Parameters:  

oldkey : str or int

old keyword

newkey : str

new keyword

force : bool

When True, if new key name already exists, force to have duplicate name.

setdefault(keyword, default='')

PyFITS < 3.1 won’t allow item assignment to keywords that don’t already exist, but for the setdefault dict method to work at all, it needs to be able to add nonexistent keywords with the default value.

toTxtFile(fileobj, clobber=False)

Output the header parameters to a file in ASCII format.

Parameters:  

fileobj : file path, file object or file-like object

Output header parameters file.

clobber : bool

When True, overwrite the output file if it exists.

update(key, value, comment=None, before=None, after=None, savecomment=False)

Update one header card.

If the keyword already exists, it’s value and/or comment will be updated. If it does not exist, a new card will be created and it will be placed before or after the specified location. If no before or after is specified, it will be appended at the end.

Parameters:  

key : str

keyword

value : str

value to be used for updating

comment : str, optional

to be used for updating, default=None.

before : str or int, optional

name of the keyword, or index of the Card before which the new card will be placed. The argument before takes precedence over after if both specified.

after : str or int, optional

name of the keyword, or index of the Card after which the new card will be placed.

savecomment : bool, optional

When True, preserve the current comment for an existing keyword. The argument savecomment takes precedence over comment if both specified. If comment is not specified then the current comment will automatically be preserved.

values()

Override values since the default implementation does not properly handle duplicate keywords.

CardList

class pyfits.CardList(cards=[], keylist=None)

Bases: list

FITS header card list class.

Construct the CardList object from a list of Card objects.

Parameters:  

cards :

A list of Card objects.

append(card, useblanks=True, bottom=False)

Append a Card to the CardList.

Parameters:  

card : Card object

The Card to be appended.

useblanks : bool, optional

Use any extra blank cards?

If useblanks is True, and if there are blank cards directly before END, it will use this space first, instead of appending after these blank cards, so the total space will not increase. When useblanks is False, the card will be appended at the end, even if there are blank cards in front of END.

bottom : bool, optional

If False the card will be appended after the last non-commentary card. If True the card will be appended after the last non-blank card.

copy()

Make a (deep)copy of the CardList.

count_blanks()

Returns how many blank cards are directly before the END card.

filterList(key)

Construct a CardList that contains references to all of the cards in this CardList that match the input key value including any special filter keys (*, ?, and ...).

Parameters:  

key : str

key value to filter the list with

Returns:  

cardlist : :

A CardList object containing references to all the requested cards.

filter_list(key)

Construct a CardList that contains references to all of the cards in this CardList that match the input key value including any special filter keys (*, ?, and ...).

Parameters:  

key : str

key value to filter the list with

Returns:  

cardlist : :

A CardList object containing references to all the requested cards.

index_of(key, backward=False)

Get the index of a keyword in the CardList.

Parameters:  

key : str or int

The keyword name (a string) or the index (an integer).

backward : bool, optional

When True, search the index from the END, i.e., backward.

Returns:  

index : int

The index of the Card with the given keyword.

insert(pos, card, useblanks=True)

Insert a Card to the CardList.

Parameters:  

pos : int

The position (index, keyword name will not be allowed) to insert. The new card will be inserted before it.

card : Card object

The card to be inserted.

useblanks : bool, optional

If useblanks is True, and if there are blank cards directly before END, it will use this space first, instead of appending after these blank cards, so the total space will not increase. When useblanks is False, the card will be appended at the end, even if there are blank cards in front of END.

keys()

Return a list of all keywords from the CardList.

Keywords include field_specifier for RecordValuedKeywordCard objects.

values()

Return a list of the values of all cards in the CardList.

For RecordValuedKeywordCard objects, the value returned is the floating point value, exclusive of the field_specifier.