agate-dbf

Common errors

• ModuleNotFoundError: No module named 'agate-dbf'

  cause The 'agate-dbf' package is not installed in the Python environment.
  fix Install the package using pip: 'pip install agate-dbf'.

• ImportError: cannot import name 'from_dbf' from 'agate'

  cause The 'from_dbf' method is not part of the 'agate' module; it is provided by the 'agate-dbf' extension.
  fix Ensure 'agate-dbf' is installed and import it alongside 'agate': 'import agate; import agatedbf'.

• AttributeError: module 'agate' has no attribute 'from_dbf'

  cause The 'from_dbf' method is not an attribute of the 'agate' module; it is added by the 'agate-dbf' extension.
  fix Import 'agate-dbf' to add 'from_dbf' support: 'import agate; import agatedbf'.

• TypeError: from_dbf() missing 1 required positional argument: 'path'

  cause The 'from_dbf' method requires a file path argument to specify the DBF file to read.
  fix Provide the path to the DBF file when calling 'from_dbf': 'table = agate.Table.from_dbf('path/to/file.dbf')'.

• ValueError: Unsupported DBF file encoding

  cause The DBF file uses an encoding that is not supported or recognized.
  fix Specify the correct encoding when calling 'from_dbf': 'table = agate.Table.from_dbf('file.dbf', encoding='utf-8')'.

Warnings

• gotcha `agate.Table.from_dbf()` specifically requires a file *path* string as an argument. It cannot accept an open file handle (e.g., from `open()`) due to limitations of its underlying `dbfread` dependency.
  Fix: Always pass the string path to the DBF file, not a file object.
• breaking As of version 0.2.2 (July 2020), `agate-dbf` no longer automatically lowercases column names when importing from DBF files.
  Fix: Update your code to expect column names as they appear in the DBF file (case-preserved). If lowercase names are needed, apply `.columns.lower()` manually after loading.
• breaking Version 0.2.0 (December 2016) introduced significant internal changes, removing a monkeypatching dependency and requiring `agate` version 1.5.0 or higher. Older code relying on previous internal mechanisms or `agate` versions before 1.5.0 will break.
  Fix: Upgrade `agate` to at least 1.5.0 and review usage if upgrading from versions prior to 0.2.0.
• breaking Support for older Python versions is routinely dropped to align with Python's end-of-life schedule. For example, version 0.2.4 dropped support for Python 3.8 and 3.9 (December 2025), and 0.2.3 dropped support for Python 3.7 and earlier (February 2024).
  Fix: Ensure your Python environment meets the minimum requirement specified in the `pyproject.toml` or `agate-dbf`'s documentation (currently `>=3.10`). Upgrade Python or pin `agate-dbf` to an older version compatible with your environment.

Install

• pip install agate-dbf Install stable version

Imports

• agate

  import agate

  Required for `agate.Table` functionality.
• agatedbf

  import agatedbf

  Importing `agatedbf` enables the `from_dbf` method on `agate.Table`.

Quickstart

This quickstart demonstrates how to load a DBF file into an `agate.Table` using the `from_dbf` method. Ensure you have a `.dbf` file available; a simple way to create one for testing is provided in the comments.

import agate
import agatedbf
import os

# Create a dummy .dbf file for demonstration purposes
# In a real scenario, you would already have a .dbf file.
# For local testing, you might use a library like `dbf` or create one manually.
# Example: (requires `pip install dbf`)
# import dbf
# db = dbf.Table('test.dbf', 'name C(15); age N(3,0)')
# db.open()
# db.append({'name': 'Alice', 'age': 30})
# db.append({'name': 'Bob', 'age': 24})
# db.close()

# Ensure a dummy dbf file exists for this example to run.
# We'll simulate this by checking for a non-existent file path
# or asking the user to create one.

dbf_path = 'test.dbf'
if not os.path.exists(dbf_path):
    print(f"Please create a dummy DBF file named '{dbf_path}' with some data.")
    print("You can use `dbf` library for this (pip install dbf) or any other DBF creator.")
    print("Example: `db = dbf.Table('test.dbf', 'name C(15); age N(3,0)'); db.open(); db.append({'name': 'Alice', 'age': 30}); db.close()`")
else:
    table = agate.Table.from_dbf(dbf_path)
    print("Table loaded successfully:")
    table.print_structure()
    table.print_table(max_rows=5)