Introduction

This is a short introduction to the API. If you want to follow along you can find people.dbf in examples/files/.

Opening a DBF File

>>> from dbfread import DBF
>>> table = DBF('people.dbf')

This returns a DBF object. You can now iterate over records:

>>> for record in table:
...     print(record)
OrderedDict([('NAME', 'Alice'), ('BIRTHDATE', datetime.date(1987, 3, 1))])
OrderedDict([('NAME', 'Bob'), ('BIRTHDATE', datetime.date(1980, 11, 12))])

and count records:

>>> len(table)
2

Deleted records are available in deleted:

>>> for record in table.deleted:
...     print(record)
OrderedDict([('NAME', 'Deleted Guy'), ('BIRTHDATE', datetime.date(1979, 12, 22))])

>>> len(table.deleted)
1

You can also use the with statement:

with DBF('people.dbf') as table:
    ...

The DBF object doesn’t keep any files open, so this is provided merely as a convenience.

Streaming or Loading Records

By default records are streamed directly off disk, which means only one record is in memory at a time.

If have enough memory, you can load the records into a list by passing load=True. This allows for random access:

>>> table = DBF('people.dbf', load=True)
>>> print(table.records[1]['NAME'])
Bob
>>> print(table.records[0]['NAME'])
Alice

Deleted records are also loaded into a list in table.deleted.

Alternatively, you can load the records later by calling table.load(). This is useful when you want to look at the header before you commit to loading anything. For example, you can make a function which returns a list of tables in a directory and load only the ones you need.

If you just want a list of records and you don’t care about the other table attributes you can do:

>>> records = list(DBF('people.dbf'))

You can unload records again with table.unload().

If the table is not loaded, the records and deleted attributes return RecordIterator objects.

Loading or iterating over records will open the DBF and memo file once for each iteration. This means the DBF object doesn’t hold any files open, only the RecordIterator object does.

Character Encodings

All text fields and memos (except binary ones) will be returned as unicode strings.

dbfread will try to detect the character encoding (code page) used in the file by looking at the language_driver byte. If this fails it reverts to ASCII. You can override this by passing encoding='my-encoding'. The encoding is available in the encoding attribute.

There may still be characters that won’t decode. You can choose how to handle these by passing the char_decode_errors option. This is passed straight to bytes.decode. See pydoc bytes.decode for more.

Memo Files

If there is at least one memo field in the file dbfread will look for the corresponding memo file. For buildings.dbf this would be buildings.fpt (for Visual FoxPro) or buildings.dbt (for other databases).

Since the Windows file system is case preserving, the file names may end up mixed case. For example, you could have:

Buildings.dbf BUILDINGS.DBT

This creates problems in Linux, where file names are case sensitive. dbfread gets around this by ignoring case in file names. You can turn this off by passing ignorecase=False.

If the memo file is missing you will get a MissingMemoFile exception. If you still want the rest of the data you can pass ignore_missing_memofile=True. All memo field values will now be returned as None, as would be the case if there was no memo.

dbfread has full support for Visual FoxPro (.FPT) and dBase III (.DBT) memo files. It reads dBase IV (also .DBT) memo files, but only if they use the default block size of 512 bytes. (This will be fixed if I can find more files to study.)

Record Factories

If you don’t want records returned as collections.OrderedDict you can use the recfactory argument to provide your own record factory.

A record factory is a function that takes a list of (name, value) pairs and returns a record. You can do whatever you like with this data. Here’s a function that creates a record object with fields as attributes:

class Record(object):
    def __init__(self, items):
        for (name, value) in items:
            setattr(self, name, value)

for record in DBF('people.dbf', recfactory=Record, lowernames=True):
    print(record.name, record.birthdate)

If you pass recfactory=None you will get the original (name, value) list. (This is a shortcut for recfactory=lambda items: items.)

Custom Field Types

If the included message types are not enough you can add your own by subclassing FieldParser. As a silly example, here how you can read text (C) fields in reverse:

from dbfread import DBF, FieldParser

class MyFieldParser(FieldParser):
    def parseC(self, field, data):
        # Return strings reversed.
        return data.rstrip(' 0').decode()[::-1]

for record in DBF('files/people.dbf', parserclass=MyFieldParser):
    print(record['NAME'])

and here’s how you can return invalid values as InvalidValue instead of raising ValueError:

from dbfread import DBF, FieldParser, InvalidValue

class MyFieldParser(FieldParser):
    def parse(self, field, data):
        try:
            return FieldParser.parse(self, field, data)
        except ValueError:
            return InvalidValue(data)

table = DBF('invalid_value.dbf', parserclass=MyFieldParser):
for i, record in enumerate(table):
    for name, value in record.items():
        if isinstance(value, InvalidValue):
            print('records[{}][{!r}] == {!r}'.format(i, name, value))

This will print:

records[0][u'BIRTHDATE'] == InvalidValue(b'NotAYear')