DBFpy Package

DBF

DBF accessing helpers.

FIXME: more documentation needed

Examples

Create new table, setup structure, add records:

dbf = Dbf(filename, new=True) dbf.addField(

System Message: ERROR/3 (/home/docs/checkouts/readthedocs.org/user_builds/invest/envs/3.3.1/local/lib/python2.7/site-packages/natcap/invest/dbfpy/dbf.py:docstring of natcap.invest.dbfpy.dbf, line 11)

Unexpected indentation.
(“NAME”, “C”, 15), (“SURNAME”, “C”, 25), (“INITIALS”, “C”, 10), (“BIRTHDATE”, “D”),

System Message: WARNING/2 (/home/docs/checkouts/readthedocs.org/user_builds/invest/envs/3.3.1/local/lib/python2.7/site-packages/natcap/invest/dbfpy/dbf.py:docstring of natcap.invest.dbfpy.dbf, line 15)

Block quote ends without a blank line; unexpected unindent.

) for (n, s, i, b) in (

System Message: ERROR/3 (/home/docs/checkouts/readthedocs.org/user_builds/invest/envs/3.3.1/local/lib/python2.7/site-packages/natcap/invest/dbfpy/dbf.py:docstring of natcap.invest.dbfpy.dbf, line 17)

Unexpected indentation.
(“John”, “Miller”, “YC”, (1980, 10, 11)), (“Andy”, “Larkin”, “”, (1980, 4, 11)),

System Message: WARNING/2 (/home/docs/checkouts/readthedocs.org/user_builds/invest/envs/3.3.1/local/lib/python2.7/site-packages/natcap/invest/dbfpy/dbf.py:docstring of natcap.invest.dbfpy.dbf, line 19)

Block quote ends without a blank line; unexpected unindent.
):
rec = dbf.newRecord() rec[“NAME”] = n rec[“SURNAME”] = s rec[“INITIALS”] = i rec[“BIRTHDATE”] = b rec.store()

System Message: WARNING/2 (/home/docs/checkouts/readthedocs.org/user_builds/invest/envs/3.3.1/local/lib/python2.7/site-packages/natcap/invest/dbfpy/dbf.py:docstring of natcap.invest.dbfpy.dbf, line 26)

Definition list ends without a blank line; unexpected unindent.

dbf.close()

Open existed dbf, read some data:

dbf = Dbf(filename, True) for rec in dbf:

System Message: ERROR/3 (/home/docs/checkouts/readthedocs.org/user_builds/invest/envs/3.3.1/local/lib/python2.7/site-packages/natcap/invest/dbfpy/dbf.py:docstring of natcap.invest.dbfpy.dbf, line 32)

Unexpected indentation.
for fldName in dbf.fieldNames:
print ‘%s: %s (%s)’ % (fldName, rec[fldName],
type(rec[fldName]))

System Message: WARNING/2 (/home/docs/checkouts/readthedocs.org/user_builds/invest/envs/3.3.1/local/lib/python2.7/site-packages/natcap/invest/dbfpy/dbf.py:docstring of natcap.invest.dbfpy.dbf, line 35)

Definition list ends without a blank line; unexpected unindent.

print

System Message: WARNING/2 (/home/docs/checkouts/readthedocs.org/user_builds/invest/envs/3.3.1/local/lib/python2.7/site-packages/natcap/invest/dbfpy/dbf.py:docstring of natcap.invest.dbfpy.dbf, line 36)

Block quote ends without a blank line; unexpected unindent.

dbf.close()

class natcap.invest.dbfpy.dbf.Dbf(f, readOnly=False, new=False, ignoreErrors=False)

Bases: object

DBF accessor.

FIXME:
docs and examples needed (dont’ forget to tell about problems adding new fields on the fly)
Implementation notes:
_new field is used to indicate whether this is a new data table. addField could be used only for the new tables! If at least one record was appended to the table it’s structure couldn’t be changed.
HeaderClass

alias of DbfHeader

INVALID_VALUE = <INVALID>
RecordClass

alias of DbfRecord

__getitem__(index)

Return DbfRecord instance.

__len__()

Return number of records.

__setitem__(index, record)

Write DbfRecord instance to the stream.

addField(*defs)

Add field definitions.

For more information see header.DbfHeader.addField.

append(record)

Append record to the database.

changed
close()
closed
fieldDefs
fieldNames
flush()

Flush data to the associated stream.

header
ignoreErrors

Error processing mode for DBF field value conversion

if set, failing field value conversion will return INVALID_VALUE instead of raising conversion error.

indexOfFieldName(name)

Index of field named name.

name
newRecord()

Return new record, which belong to this table.

recordCount
stream

DBF New

.DBF creation helpers.

Note: this is a legacy interface. New code should use Dbf class
for table creation (see examples in dbf.py)
TODO:
  • handle Memo fields.
  • check length of the fields accoring to the http://www.clicketyclick.dk/databases/xbase/format/data_types.html
class natcap.invest.dbfpy.dbfnew.dbf_new

Bases: object

New .DBF creation helper.

Example Usage:

dbfn = dbf_new() dbfn.add_field(“name”,’C’,80) dbfn.add_field(“price”,’N’,10,2) dbfn.add_field(“date”,’D’,8) dbfn.write(“tst.dbf”)

Note

This module cannot handle Memo-fields, they are special.

FieldDefinitionClass

alias of _FieldDefinition

add_field(name, typ, len, dec=0)

Add field definition.

Parameters:
  • name – field name (str object). field name must not contain ASCII NULs and it’s length shouldn’t exceed 10 characters.
  • typ – type of the field. this must be a single character from the “CNLMDT” set meaning character, numeric, logical, memo, date and date/time respectively.
  • len – length of the field. this argument is used only for the character and numeric fields. all other fields have fixed length. FIXME: use None as a default for this argument?
  • dec – decimal precision. used only for the numric fields.
fields
write(filename)

Create empty .DBF file using current structure.

Fields

DBF fields definitions.

TODO:
  • make memos work
natcap.invest.dbfpy.fields.lookupFor(typeCode)

Return field definition class for the given type code.

typeCode must be a single character. That type should be previously registered.

Use registerField to register new field class.

Returns:Return value is a subclass of the DbfFieldDef.
class natcap.invest.dbfpy.fields.DbfCharacterFieldDef(name, length=None, decimalCount=None, start=None, stop=None, ignoreErrors=False)

Bases: natcap.invest.dbfpy.fields.DbfFieldDef

Definition of the character field.

decodeValue(value)

Return string object.

Return value is a value argument with stripped right spaces.

defaultValue = ''
encodeValue(value)

Return raw data string encoded from a value.

typeCode = 'C'
class natcap.invest.dbfpy.fields.DbfFloatFieldDef(name, length=None, decimalCount=None, start=None, stop=None, ignoreErrors=False)

Bases: natcap.invest.dbfpy.fields.DbfNumericFieldDef

Definition of the float field - same as numeric.

typeCode = 'F'
class natcap.invest.dbfpy.fields.DbfLogicalFieldDef(name, length=None, decimalCount=None, start=None, stop=None, ignoreErrors=False)

Bases: natcap.invest.dbfpy.fields.DbfFieldDef

Definition of the logical field.

decodeValue(value)

Return True, False or -1 decoded from value.

defaultValue = -1
encodeValue(value)

Return a character from the “TF?” set.

Returns:Return value is “T” if value is True ”?” if value is -1 or False otherwise.
length = 1
typeCode = 'L'
class natcap.invest.dbfpy.fields.DbfDateFieldDef(name, length=None, decimalCount=None, start=None, stop=None, ignoreErrors=False)

Bases: natcap.invest.dbfpy.fields.DbfFieldDef

Definition of the date field.

decodeValue(value)

Return a datetime.date instance decoded from value.

defaultValue = datetime.date(2016, 6, 10)
encodeValue(value)

Return a string-encoded value.

value argument should be a value suitable for the utils.getDate call.

Returns:Return value is a string in format “yyyymmdd”.
length = 8
typeCode = 'D'
class natcap.invest.dbfpy.fields.DbfMemoFieldDef(name, length=None, decimalCount=None, start=None, stop=None, ignoreErrors=False)

Bases: natcap.invest.dbfpy.fields.DbfFieldDef

Definition of the memo field.

Note: memos aren’t currenly completely supported.

decodeValue(value)

Return int .dbt block number decoded from the string object.

defaultValue = ' '
encodeValue(value)

Return raw data string encoded from a value.

Note: this is an internal method.

length = 10
typeCode = 'M'
class natcap.invest.dbfpy.fields.DbfNumericFieldDef(name, length=None, decimalCount=None, start=None, stop=None, ignoreErrors=False)

Bases: natcap.invest.dbfpy.fields.DbfFieldDef

Definition of the numeric field.

decodeValue(value)

Return a number decoded from value.

If decimals is zero, value will be decoded as an integer; or as a float otherwise.

Returns:Return value is a int (long) or float instance.
defaultValue = 0
encodeValue(value)

Return string containing encoded value.

typeCode = 'N'
class natcap.invest.dbfpy.fields.DbfCurrencyFieldDef(name, length=None, decimalCount=None, start=None, stop=None, ignoreErrors=False)

Bases: natcap.invest.dbfpy.fields.DbfFieldDef

Definition of the currency field.

decodeValue(value)

Return float number decoded from value.

defaultValue = 0.0
encodeValue(value)

Return string containing encoded value.

length = 8
typeCode = 'Y'
class natcap.invest.dbfpy.fields.DbfIntegerFieldDef(name, length=None, decimalCount=None, start=None, stop=None, ignoreErrors=False)

Bases: natcap.invest.dbfpy.fields.DbfFieldDef

Definition of the integer field.

decodeValue(value)

Return an integer number decoded from value.

defaultValue = 0
encodeValue(value)

Return string containing encoded value.

length = 4
typeCode = 'I'
class natcap.invest.dbfpy.fields.DbfDateTimeFieldDef(name, length=None, decimalCount=None, start=None, stop=None, ignoreErrors=False)

Bases: natcap.invest.dbfpy.fields.DbfFieldDef

Definition of the timestamp field.

JDN_GDN_DIFF = 1721425
decodeValue(value)

Return a datetime.datetime instance.

defaultValue = datetime.datetime(2016, 6, 10, 0, 18, 15, 508195)
encodeValue(value)

Return a string-encoded value.

length = 8
typeCode = 'T'

Header

DBF header definition.

TODO:
  • handle encoding of the character fields (encoding information stored in the DBF header)
class natcap.invest.dbfpy.header.DbfHeader(fields=None, headerLength=0, recordLength=0, recordCount=0, signature=3, lastUpdate=None, ignoreErrors=False)

Bases: object

Dbf header definition.

For more information about dbf header format visit http://www.clicketyclick.dk/databases/xbase/format/dbf.html#DBF_STRUCT

Examples

Create an empty dbf header and add some field definitions:
dbfh = DbfHeader() dbfh.addField((“name”, “C”, 10)) dbfh.addField((“date”, “D”)) dbfh.addField(DbfNumericFieldDef(“price”, 5, 2))
Create a dbf header with field definitions:
dbfh = DbfHeader([
(“name”, “C”, 10), (“date”, “D”), DbfNumericFieldDef(“price”, 5, 2),

System Message: WARNING/2 (/home/docs/checkouts/readthedocs.org/user_builds/invest/envs/3.3.1/local/lib/python2.7/site-packages/natcap/invest/dbfpy/header.py:docstring of natcap.invest.dbfpy.header.DbfHeader, line 18)

Definition list ends without a blank line; unexpected unindent.

])

__getitem__(item)

Return a field definition by numeric index or name string

addField(*defs)

Add field definition to the header.

Examples

dbfh.addField(
(“name”, “C”, 20), dbf.DbfCharacterFieldDef(“surname”, 20), dbf.DbfDateFieldDef(“birthdate”), (“member”, “L”),

System Message: WARNING/2 (/home/docs/checkouts/readthedocs.org/user_builds/invest/envs/3.3.1/local/lib/python2.7/site-packages/natcap/invest/dbfpy/header.py:docstring of natcap.invest.dbfpy.header.DbfHeader.addField, line 10)

Definition list ends without a blank line; unexpected unindent.

) dbfh.addField((“price”, “N”, 5, 2)) dbfh.addField(dbf.DbfNumericFieldDef(“origprice”, 5, 2))

changed
day
fields
classmethod fromStream(stream)

Return header object from the stream.

classmethod fromString(string)

Return header instance from the string object.

headerLength
ignoreErrors

Error processing mode for DBF field value conversion

if set, failing field value conversion will return INVALID_VALUE instead of raising conversion error.

lastUpdate
month
recordCount
recordLength
setCurrentDate()

Update self.lastUpdate field with current date value.

signature
toString()

Returned 32 chars length string with encoded header.

write(stream)

Encode and write header to the stream.

year

Record

DBF record definition.

class natcap.invest.dbfpy.record.DbfRecord(dbf, index=None, deleted=False, data=None)

Bases: object

DBF record.

Instances of this class shouldn’t be created manualy, use dbf.Dbf.newRecord instead.

Class implements mapping/sequence interface, so fields could be accessed via their names or indexes (names is a preffered way to access fields).

Hint:
Use store method to save modified record.

Examples

Add new record to the database:
db = Dbf(filename) rec = db.newRecord() rec[“FIELD1”] = value1 rec[“FIELD2”] = value2 rec.store()

System Message: WARNING/2 (/home/docs/checkouts/readthedocs.org/user_builds/invest/envs/3.3.1/local/lib/python2.7/site-packages/natcap/invest/dbfpy/record.py:docstring of natcap.invest.dbfpy.record.DbfRecord, line 21)

Definition list ends without a blank line; unexpected unindent.

Or the same, but modify existed (second in this case) record:

System Message: ERROR/3 (/home/docs/checkouts/readthedocs.org/user_builds/invest/envs/3.3.1/local/lib/python2.7/site-packages/natcap/invest/dbfpy/record.py:docstring of natcap.invest.dbfpy.record.DbfRecord, line 23)

Unexpected indentation.
db = Dbf(filename) rec = db[2] rec[“FIELD1”] = value1 rec[“FIELD2”] = value2 rec.store()
__getitem__(key)

Return value by field name or field index.

__setitem__(key, value)

Set field value by integer index of the field or string name.

asDict()

Return a dictionary of fields.

Note

Change of the dicts’s values won’t change real values stored in this object.

asList()

Return a flat list of fields.

Note

Change of the list’s values won’t change real values stored in this object.

dbf
delete()

Mark method as deleted.

deleted
fieldData
classmethod fromStream(dbf, index)

Return a record read from the stream.

Parameters:
  • dbf – A Dbf.Dbf instance new record should belong to.
  • index – Index of the record in the records’ container. This argument can’t be None in this call.

Return value is an instance of the current class.

classmethod fromString(dbf, string, index=None)

Return record read from the string object.

Parameters:
  • dbf – A Dbf.Dbf instance new record should belong to.
  • string – A string new record should be created from.
  • index – Index of the record in the container. If this argument is None, record will be appended.

Return value is an instance of the current class.

index
position
classmethod rawFromStream(dbf, index)

Return raw record contents read from the stream.

Parameters:
  • dbf – A Dbf.Dbf instance containing the record.
  • index – Index of the record in the records’ container. This argument can’t be None in this call.

Return value is a string containing record data in DBF format.

store()

Store current record in the DBF.

If self.index is None, this record will be appended to the records of the DBF this records belongs to; or replaced otherwise.

toString()

Return string packed record values.

Utilities

String utilities.

TODO:
  • allow strings in getDateTime routine;
class natcap.invest.dbfpy.utils.classproperty

Bases: property

Works in the same way as a property, but for the classes.

natcap.invest.dbfpy.utils.getDate(date=None)

Return datetime.date instance.

Type of the date argument could be one of the following:
None:
use current date value;
datetime.date:
this value will be returned;
datetime.datetime:
the result of the date.date() will be returned;
string:
assuming “%Y%m%d” or “%y%m%dd” format;
number:
assuming it’s a timestamp (returned for example by the time.time() call;
sequence:
assuming (year, month, day, ...) sequence;

Additionaly, if date has callable ticks attribute, it will be used and result of the called would be treated as a timestamp value.

natcap.invest.dbfpy.utils.getDateTime(value=None)

Return datetime.datetime instance.

Type of the value argument could be one of the following:
None:
use current date value;
datetime.date:
result will be converted to the datetime.datetime instance using midnight;
datetime.datetime:
value will be returned as is;
string:
* CURRENTLY NOT SUPPORTED *;
number:
assuming it’s a timestamp (returned for example by the time.time() call;
sequence:
assuming (year, month, day, ...) sequence;

Additionaly, if value has callable ticks attribute, it will be used and result of the called would be treated as a timestamp value.

natcap.invest.dbfpy.utils.unzfill(str)

Return a string without ASCII NULs.

This function searchers for the first NUL (ASCII 0) occurance and truncates string till that position.

Module contents