Skip to content
Back to top
View this page

# Data types

Data types define how data should be imported during the creation of a `Table`.

If column types are not explicitly specified when a `Table` is created, agate will attempt to guess them. The `TypeTester` class can be used to control how types are guessed.

`agate.DataType` | Specifies how values should be parsed when creating a `Table`.

## Supported types

`agate.Text` | Data representing text.
`agate.Number` | Data representing numbers.
`agate.Boolean` | Data representing true and false.
`agate.Date` | Data representing dates alone.
`agate.DateTime` | Data representing dates with times.
`agate.TimeDelta` | Data representing the interval between two dates and/or times.

## Detailed list

class agate.DataType(null_values=('', 'na', 'n/a', 'none', 'null', '.'))

  Bases: `object`

  Specifies how values should be parsed when creating a `Table`.

  Parameters:

    null_values – A sequence of values which should be cast to `None` when encountered by this data type.

  test(d)

    Test, for purposes of type inference, if a value could possibly be coerced to this data type.

    This is really just a thin wrapper around `DataType.cast()`.

  cast(d)

    Coerce a given string value into this column’s data type.

  csvify(d)

    Format a given native value for CSV serialization.

  jsonify(d)

    Format a given native value for JSON serialization.

class agate.Text(cast_nulls=True, **kwargs)

  Bases: `DataType`

  Data representing text.

  Parameters:

    cast_nulls – If `True`, values in `DEFAULT_NULL_VALUES` will be converted to None. Disable to retain them as strings.

  cast(d)

    Cast a single value to `unicode()` (`str()` in Python 3).

    Parameters:

      d – A value to cast.

    Returns:

      `unicode()` (`str()` in Python 3) or `None`

class agate.Number(locale='en_US', group_symbol=None, decimal_symbol=None, currency_symbols=['؋', '$', 'ƒ', '៛', '¥', '₡', '₱', '£', '€', '¢', '﷼', '₪', '₩', '₭', '₮', '₦', '฿', '₤', '₫'], no_leading_zeroes=None, **kwargs)

  Bases: `DataType`

  Data representing numbers.

  Parameters:

    - locale – A locale specification such as `en_US` or `de_DE` to use for parsing formatted numbers.

    - group_symbol – A grouping symbol used in the numbers. Overrides the value provided by the specified `locale`.

    - decimal_symbol – A decimal separate symbol used in the numbers. Overrides the value provided by the specified `locale`.

    - currency_symbols – A sequence of currency symbols to strip from numbers.

    - no_leading_zeroes – Whether to disallow leading zeroes.

  cast(d)

    Cast a single value to a `decimal.Decimal`.

    Returns:

      `decimal.Decimal` or `None`.

  csvify(d)

    Format a given native value for CSV serialization.

  jsonify(d)

    Format a given native value for JSON serialization.

class agate.Boolean(true_values=('yes', 'y', 'true', 't', '1'), false_values=('no', 'n', 'false', 'f', '0'), null_values=('', 'na', 'n/a', 'none', 'null', '.'))

  Bases: `DataType`

  Data representing true and false.

  Note that by default numerical 1 and 0 are considered valid boolean values, but other numbers are not.

  Parameters:

    - true_values – A sequence of values which should be cast to `True` when encountered with this type.

    - false_values – A sequence of values which should be cast to `False` when encountered with this type.

  cast(d)

    Cast a single value to `bool`.

    Parameters:

      d – A value to cast.

    Returns:

      `bool` or `None`.

  jsonify(d)

    Format a given native value for JSON serialization.

class agate.Date(date_format=None, locale=None, **kwargs)

  Bases: `DataType`

  Data representing dates alone.

  Parameters:

    - date_format – A formatting string for `datetime.datetime.strptime()` to use instead of using regex-based parsing.

    - locale – A locale specification such as `en_US` or `de_DE` to use for parsing formatted dates.

  cast(d)

    Cast a single value to a `datetime.date`.

    If both date_format and locale have been specified in the agate.Date instance, the cast() function is not thread-safe. :returns: `datetime.date` or `None`.

  csvify(d)

    Format a given native value for CSV serialization.

  jsonify(d)

    Format a given native value for JSON serialization.

class agate.DateTime(datetime_format=None, timezone=None, locale=None, **kwargs)

  Bases: `DataType`

  Data representing dates with times.

  Parameters:

    - datetime_format – A formatting string for `datetime.datetime.strptime()` to use instead of using regex-based parsing.

    - timezone – A `ZoneInfo` timezone to apply to each parsed date.

    - locale – A locale specification such as `en_US` or `de_DE` to use for parsing formatted datetimes.

  cast(d)

    Cast a single value to a `datetime.datetime`.

    If both date_format and locale have been specified in the agate.DateTime instance, the cast() function is not thread-safe. :returns: `datetime.datetime` or `None`.

  csvify(d)

    Format a given native value for CSV serialization.

  jsonify(d)

    Format a given native value for JSON serialization.

class agate.TimeDelta(null_values=('', 'na', 'n/a', 'none', 'null', '.'))

  Bases: `DataType`

  Data representing the interval between two dates and/or times.

  cast(d)

    Cast a single value to `datetime.timedelta`.

    Parameters:

      d – A value to cast.

    Returns:

      `datetime.timedelta` or `None`