Skip to content

Properties Reference

Property descriptors for the Google Cloud Datastore ODM.

This module provides the base Property descriptor and its type-specific subclasses (e.g., StringProperty, IntegerProperty). These classes handle data coercion, validation, default values, and Datastore schema mapping.

Property(*, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None)

Base descriptor for model properties.

This class implements the Python descriptor protocol (__get__, __set__, __delete__) to manage state on the underlying Model instances.

Responsibilities: - Required checks and default value assignment - Python type enforcement (via subclasses) - Inline property-level validators - Routing to Model-level @field_validator methods - Datastore aliasing (name) - Indexing control (indexed) - List support (repeated) - Value restriction (choices)

Initialize a new Property.

Parameters:

Name Type Description Default
name Optional[str]

The Datastore column name. If omitted, defaults to the Python attribute name. Useful for mapping legacy database fields.

 None
indexed bool

Whether the Datastore should index this property. Set to False for massive text blocks to save space and reduce write costs. If not sure leave this True and pass unindexed properties on the fly during put() operations.

 True
repeated bool

If True, this property expects an iterable (list/set/tuple) and stores it as an array in Datastore. Defaults to False.

 False
required bool

If True, assigning None or an empty list (if repeated) will raise a ValueError. Defaults to False.

 False
default Any

The default value or a zero-argument callable to generate one (e.g., default=list or default=datetime.now).

 None
choices Optional[list]

An optional list of allowed values. Assignments not in this list will raise a ValueError.

 None
validators Optional[List[Callable]]

A list of custom validation functions. Each function should accept a single value, validate/mutate it, and return it.

 None

Raises:

Type Description
TypeError

If any provided validator is not callable.
Example 
status = StringProperty(
    default="draft",
    choices=["draft", "published"],
    name="legacy_status_col"
)
tags = StringProperty(repeated=True)

validate(instance, value)

Validate and process a value (or list of values) for this property.

Handles None assignments, required checks, and maps the validation pipeline over elements if the property is repeated.

Parameters:

Name Type Description Default
instance Model

The underlying model instance.

 required
value Any

The assigned value (or iterable if repeated).

 required

Raises:

Type Description
ValueError

If the property is required but None/empty is provided.
TypeError

If a repeated property is assigned a non-iterable.

Returns:

Name Type Description
Any Any

The fully validated value or list of validated values.

in_(values)

Generates an 'IN' query filter.

not_in_(values)

Generates a 'NOT IN' query filter.

StringProperty(*, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None)

Bases: Property

A Datastore property that strictly enforces string values.

IntegerProperty(*, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None)

Bases: Property

A Datastore property that strictly enforces integer values.

Note: Python evaluates booleans as subclasses of integers (isinstance(True, int) is True). This descriptor explicitly rejects boolean values to maintain strict Datastore type integrity.

BooleanProperty(*, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None)

Bases: Property

A Datastore property that strictly enforces boolean values.

FloatProperty(*, name=None, indexed=True, repeated=False, required=False, default=None, choices=None, validators=None)

Bases: Property

A Datastore property that enforces floating-point values.

This property safely accepts both float and int types, automatically casting int assignments to float to prevent strict type errors over simple math (e.g. assigning 1 instead of 1.0).

TextProperty(compressed=False, **kwargs)

Bases: StringProperty

A Datastore property for large strings.

Unlike StringProperty, this is strictly unindexed to bypass Datastore's 1500-byte limit. It also supports optional zlib compression for saving space.

JsonProperty(compressed=False, **kwargs)

Bases: Property

A Datastore property that enforces JSON-serializable structures.

This property strictly defaults to indexed=False to prevent Datastore index explosions on arbitrarily nested dynamic keys. It also supports optional zlib compression to drastically reduce storage costs for massive JSON payloads.

DateTimeProperty(*, auto_now=False, auto_now_add=False, tzinfo=None, **kwargs)

Bases: Property

A Datastore property that enforces datetime values.

If tzinfo is None, this expects naive datetimes and assumes UTC. If tzinfo is provided, it converts Datastore's UTC datetimes to that timezone.

Initialize a new DateTimeProperty.

Parameters:

Name Type Description Default
auto_now bool

If True, automatically set to the current time on every put().

 False
auto_now_add bool

If True, automatically set to the current time when first created.

 False
tzinfo Optional[tzinfo]

The timezone to convert Datastore's UTC to/from.

 None
**kwargs Any

Additional base property arguments (e.g., name, required, indexed).

 {}

DateProperty(*, auto_now=False, auto_now_add=False, tzinfo=None, **kwargs)

Bases: DateTimeProperty

A Datastore property that enforces date values.

Datastore only supports Datetimes, so this property casts to a Datetime at midnight UTC before saving, and casts back to a Date when reading.

Initialize a new DateProperty.

Parameters:

Name Type Description Default
auto_now bool

If True, automatically set to the current date on every put().

 False
auto_now_add bool

If True, automatically set to the current date when first created.

 False
tzinfo Optional[tzinfo]

The timezone used to evaluate the "current" date.

 None
**kwargs Any

Additional base property arguments (e.g., name, required, indexed).

 {}

TimeProperty(*, auto_now=False, auto_now_add=False, tzinfo=None, **kwargs)

Bases: DateTimeProperty

A Datastore property that enforces time values.

Datastore only supports Datetimes, so this property casts to a Datetime on Jan 1, 1970 UTC before saving, and casts back to a Time when reading.

Initialize a new TimeProperty.

Parameters:

Name Type Description Default
auto_now bool

If True, automatically set to the current time on every put().

 False
auto_now_add bool

If True, automatically set to the current time when first created.

 False
tzinfo Optional[tzinfo]

The timezone used to evaluate the "current" time.

 None
**kwargs Any

Additional base property arguments (e.g., name, required, indexed).

 {}