capefile: Reader for CAPE-specific binary files

class cape.dkit.capefile.CapeFile(a: str | dict | IOBase | None = None, meta: bool = False)

Interface to simple binary format specific to CAPE

Call:
>>> cdb = CapeFile(fname=None, meta=False)
>>> cdb = CapeFile(fp, meta=False)
>>> cdb = CapeFile(data, meta=False)
Inputs:
fname: str

Name of file to read

fp: io.IOBase

File handle open in rb mode

meta: True | {False}

Option to only read variable names and sizes

Outputs:
cdb: CapeFile

Data from CAPE binary file

cdb.filename: None | str

Name of file data was read from

cdb.filedir: None | str

Absolute path to folder with file data was read from

cdb.cols: list[str]

Ordered list of columns

read(fname: str | IOBase, meta: bool = True)

Read data from a .cdb file

Call:
>>> db.read(fname, meta=True)
>>> db.read(fp, meta=True)
Inputs:
db: CapeFile

Instance of .cdb file interface

fname: str

Name of file to read

fp: io.IOBase

File handle open in 'rb' mode

meta: {True} | False

Option to only read column names and sizes

save_col(col: str | None, v, j=None)

Save value for one column

Call:
>>> db.save_col(col, v, j=None)
Inputs:
db: CapeFile

Instance of .cdb file interface

col: str

Name of column/field to save

v: Any

Value to save

j: {None} | int

Index of which instance of col to save

save_dict(a: dict)

Save all parameters of a dict

Call:
>>> db.save_dict(a)
Inputs:
db: CapeFile

Instance of .cdb file interface

a: dict

Any dictionary of serializable keys

write(fname: str | IOBase)

Write data to a .cdb file

Call:
>>> db.write(fname)
>>> db.write(fp)
Inputs:
db: CapeFile

Instance of .cdb file interface

fname: str

Name of file to write

fp: io.IOBase

File handle open in 'wb' mode

exception cape.dkit.capefile.CapeFileError

Base for all exceptions raised by capefile

exception cape.dkit.capefile.CapeFileTypeError

Exception class for incorrect type in capefile

exception cape.dkit.capefile.CapeFileValueError

Exception class for incorrect value in capefile

cape.dkit.capefile.assert_isinstance(obj, cls_or_tuple, desc=None)

Conveniently check types

Applies isinstance(obj, cls_or_tuple) but also constructs a TypeError and appropriate message if test fails.

If cls is None, no checks are performed.

Call:
>>> assert_isinstance(obj, cls, desc=None)
>>> assert_isinstance(obj, cls_tuple, desc=None)
Inputs:
obj: object

Object whose type is checked

cls: None | type

Single permitted class

cls_tuple: tuple[type]

Tuple of allowed classes

desc: {None} | str

Optional text describing obj for including in error msg

Raises:

CapeFileTypeError

cape.dkit.capefile.assert_size(v: ndarray, n: int, fp: IOBase, desc=None)

Check if array has expected size

Call:
>>> assert_size(v, n, fp, desc=None)
Inputs:
v: np.ndarray

An array

n: int

Expected size

fp: io.IOBase

File handle to report position

desc: {None} | str

Optional text describing v for including in error msg

Raises:

CapeFileValueError

cape.dkit.capefile.assert_value(obj, val_or_tuple, desc=None)

Conveniently check values

If val is None, no checks are performed.

Call:
>>> assert_value(obj, val, desc=None)
>>> assert_value(obj, val_tuple, desc=None)
Inputs:
obj: object

Object whose type is checked

val: None | object

Single permitted value

val_tuple: tuple

Tuple of allowed values

desc: {None} | str

Optional text describing obj for including in error msg

Raises:

CapeFileValueError

cape.dkit.capefile.check_header(fp: IOBase)

Check that file has the correct header for file type

Call:
>>> check_header(fp)
Inputs:
fp: io.IOBase

File open for reading bytes ('rb' or similar)

Raises:

CapeFileValueError if file does not have correct header

cape.dkit.capefile.genr8_recordtype(v, name: str | None = None) → uint32

Get capefile record type code based on Python type

Call:
>>> rt = genr8_recordtype(v, name=None)
Inputs:
v: object

Any value to analyze type

name: {None} | str

Title for v, used to determine “title” bit in rt

Outputs:
rt: np.uint32

Record type code

cape.dkit.capefile.read_nrecord(fp: IOBase) → uint64

Read number of records in file

Call:
>>> nr = read_nrecord(fp)
Inputs:
fp: io.IOBase

File handle

Outputs:
nr: np.uint64

Number of records

cape.dkit.capefile.write_record(fp: IOBase, v, name: str | None = None) → uint64

Write a record to file

Call:
>>> size = write_record(fp, v, name=None)
Inputs:
fp: io.IOBase

A file open for writing bytes

v: object

Object to be written to file

name: {None} | str

Optional title to save v as

Outputs:
size: np.uint64

Number of bytes written