Skip to content

crandas.ctypes

ColumnBoundDerivedWarning(colname, coltype)

Bases: Warning

Constructor. colname and coltype can be strings or lists of strings

Ctype

Ctypes, or "crandas types", are an extensible client-side type system that allow the user to provide additional type information beyond pandas/numpy dtypes.

Ctypes are represented as class instances, e.g. NullableInteger. Some classes take arguments in their initialization, like Varchar(max_length=12). Each Ctype also has a string representation, like "varchar[12]". Either of these can be specified to the ctype kwarg of cd.DataFrame(), so e.g.

cd.DataFrame({"ints": [1, 2, 3], "strings": ["a", "bb", "ccc"]},
                ctype={"ints": "int8?", "strings": "varchar[5]"})

If a manual ctype is not specified, the appropriate ctype is automatically deduced using the pandas dtype. For details of how this is implemented, see the Ctype.for_series() class method.

The JSON representation of a ctype is of the following form:

  • type (str) column type (b: bytes | fp: fixed point | i: integer | s: string | d: date)
  • elements_per_value (int) number of elements in the column
  • nullable (bool) boolean determining if the column is nullable

Additionally it may contain a constraints field in the form of a Validation.

Internal workings

Each class (so e.g. Integer) has CtypeBase as a base class, and is decorated with @Ctype.register, which registers the Ctype's .dtype, .ctype, etc. properties so that the Ctype class may perform automatic ctype inference on pandas.Series objects. Note that a single dtype, etc. cannot be registered multiple times. If the type is registered both by a base class and a subclass, then the base class registration is used.

for_series(series, ctype_spec=None) classmethod

Determine the Ctype for a pandas.Series object, based on the specified ctype_str, the series.dtype, the ctype_cls.from_series() function, or the value_type (i.e. the type of next(iter(series))), in that order.

from_spec(ctype_spec) classmethod

Determine the Ctype based on a specification, that is a ctype object (i.e. an instance of a subclass of CtypeBase), a string, or a Python type.

CtypeDoubtWarning(*, msg, **kwargs)

Bases: UserWarning

Warning that a column has an automatically derived ctype but a different one possibly suits better

FixedPointBase(*, precision=None, min=None, max=None, modulus=None, **kwargs)

Bases: CtypeBase