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=['؋', '$', 'ƒ', '៛', '¥', '₡', '₱', '£', '€', '¢', '﷼', '₪', '₩', '₭', '₮', '₦', '฿', '₤', '₫'], **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.

cast(d)#

Cast a single value to a decimal.Decimal.

Returns:

decimal.Decimal or None.

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