descriptors

This contains all of the Descriptor objects we’ll will use to compose the basic classes that inherit from geodesic.bases.APIObject. They follow the pattern <Name>Descr. Rather than simply being namespaced here, the Descr suffix will allow them to be aligned with other objects that will be implemented as descriptors, such as AssetSpec and Project, and such. These, by necessity need to be implemented in separate packages and this convention will keep things internally consistent.

These descriptors are not meant for users as they are just something internal to Geodesic objects. Users can take advantage of the validation in them if needed, but in general this will all be taken care of by the Geodesic objects. Each descriptor inherits from _BaseDescr which provides the standard __get__() and __set__() functionality. In __set__() it also calls a validation function which is defined on the subclass. This allows at-set validation of things like types, regex, or anything else needed by the subclass.

When documenting descriptors make sure always include a link to the current descriptor as the first line of the docstring. This will allow the docs to propagate correctly to classes where the descriptor is used.

class geodesic.descriptors._BaseDescr(nested=None, doc=None, default=None, dict_name=None, deprecated=False, optional=False)

Bases: object

base functionality of Descriptor objects for use with APIObject

BaseDescr adds the basic functionality we use such as the attribute name and the private_name, which is prefixed by an “_”.

Parameters

• nested (str) – a subfield in the object’s dict to retrieve this out of. A json path, separated by ‘.’. only object paths are supported, not full JSON paths such as list indices or wildcards

• doc (str) – a custom docstring to override the default field descriptor docstring.

• default – a default value for this field

• dict_name – if the attribute name needs to be different than the name in the dictionary, it can be set with this. (example: object_class -> class since class is a reserved word)

• deprecated – If this field deprecated, will raise a DeprecationWarning

• optional – If True, this field is allowed to be None.

_get(obj, objtype=None)

_validate(obj, value)

override for type specific validation. Should raise an exception if invalid, not return a bool

_set(obj, value)

_attribute_error(objtype)

_get_object(obj)

Gets a field that is nested in another dictionary object. Allows a descriptor to grab a property from inside a dict that is potentially many levels deep

_set_object(obj, value)

Sets a field that is nested in another dictionary object. If that dictionary doesn’t exist, this creates it, first checking that the attribute exists

_BaseDescr__traverse_nested_objects(obj)

Goes through nested objects until it has traversed all nested levels. Returns that object, creating it and parents along the way.

class geodesic.descriptors._GeometryDescr(bbox=None, **kwargs)

Bases: geodesic.descriptors._BaseDescr

Geometry field descriptor for a geodesic.bases.APIObject.

Parameters

bbox – a bbox attribute that will be set when the geometry is updated. This is important for keeping geometry/bbox in sync on objects where the bbox is always derived from a geometry field.

__get__()

returns a shapely representation of the geometry

__set__()

coerces the input into a geojson dict (__geo_interface__) and stores internally to the APIObject dict

_get(obj, objtype=None)

Gets the geometry attribute of an object.

Raises

AttributeError if geometry is None or doesn't exist –

_set(obj, value)

Sets a geometry on obj.

Parameters

• obj (object) – the object to be modified

• value (Union[object, dict, str, bytes]) – any object implementing the __geo_interface__ convention (https://gist.github.com/sgillies/2217756), a dict representing an RFC 7946 GeoJSON geometry, a WKT string, or a WKB bytestring

_validate(obj, value)

class geodesic.descriptors._BBoxDescr(**kwargs)

Bases: geodesic.descriptors._GeometryDescr

BBoxDescr is a bounding box field descriptor for a geodesic.bases.APIObject.

Inherits from GeometeryDescr to use its validator

__get__()

returns a tuple of 4 values representing corners of the bbox (xmin, ymin, xmax, ymax)

__set__()

coerces the input into a shapely geom before taking the bounds and stores internally to the APIObject dict

_get(obj, objtype=None)

_set(obj, value)

_validate(obj, value)

class geodesic.descriptors._RegexDescr(regex, empty_allowed=False, **kwargs)

Bases: geodesic.descriptors._BaseDescr

RegexDescr is a field that is validated against a regex

Valid inputs for this field follow: {regex}

__get__()

this attribute returns the validated string

__set__()

validates a string and then sets the value in the APIObject dict

_get(obj, objtype=None)

_set(obj, value)

_validate(obj, value)

class geodesic.descriptors._DictDescr(**kwargs)

Bases: geodesic.descriptors._BaseDescr

DictDescr is a dictionary field, such as properties in a GeoJSON object.

This set/returns a dictionary field no matter what, it doesn’t raise an attribute error

__get__()

returns the dict, creating it on the base object if necessary

__set__()

sets the dictionary after validating that it is a dict

_get(obj, objtype=None)

_set(obj, value)

_validate(obj, value)

class geodesic.descriptors._ListDescr(item_type=None, min_len=None, max_len=None, coerce_items=False, **kwargs)

Bases: geodesic.descriptors._BaseDescr

ListDescr is a list field, such as links in a GeoJSON feature collection object.

This sets/returns a list field no matter what, it doesn’t raise an attribute error

Parameters

• item_type (tuple or type) – A type or tuple of types that are allowed as the inputs to this descriptor. If you also set coerce to True, then the output type of the list (when you do a get) will be coerced to the first element of the tuple. If you would like to use this to pass in one type (typeA) and return another (typeB) then item_type should be (typeB, typeA) as well as coerce=True.

• min_len (int) – a minimum number of elements for this list

• max_len (int) – a maximum number of elements for this list

• coerce_items (bool) – coerce all elements to the first type in the item_type arg when setting the values of the list.

__get__()

returns the list, creating it on the base object if necessary

__set__()

sets the list after validating that it is a list

_get(obj, objtype=None)

_set(obj, value)

_validate(obj, value)

class geodesic.descriptors._TupleDescr(item_type=None, min_len=None, max_len=None, **kwargs)

Bases: geodesic.descriptors._BaseDescr

TupleDescr is a tuple field (immutable), such as image shape.

This raises an attribute error

Parameters

• item_type (type) – Type to validate all elements in this tuple against

• min_len (int) – The minimum allowed length for this tuple to be instantiated

• max_len (int) – The maximum allowed length for this tuple

__get__()

returns the tuple, creating it on the base object if necessary

__set__()

sets the tuple after validating that it is a tuple

_get(obj, objtype=None)

_set(obj, value)

_validate(obj, value)

class geodesic.descriptors._DatetimeDescr(**kwargs)

Bases: geodesic.descriptors._BaseDescr

DatetimeDescr is a UTC datetime field and is setable through typical python datetime objects, numpy datetime64, or pandas.Timestamp objects, pandas datetime objects, and RFC3339 strings.

__get__()

returns the datetime, raise an AttributeError if missing

__set__()

sets the datetime, storing internally as an RFC3339 string

rfc3339_regex = re.compile('^((?:(\\d{4}-\\d{2}-\\d{2})T(\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?))(Z|[\\+-]\\d{2}:\\d{2})?)$')

_get(obj, objtype=None)

_set(obj, value)

_validate(obj, value)

class geodesic.descriptors._TimeDeltaDescr(**kwargs)

Bases: geodesic.descriptors._BaseDescr

_TimeDeltaDescr is represents a time delta, formatted like:

d+(ms|us|ns|[YMWDhms]){1}”

d+ - one or more digits Y - years M - months W - weeks D - days h - hours m - minutes s - seconds ms - milliseconds us - microseconds ns - nanoseconds

If specified by a string, it must be in a single choice of time unit, or can be provided as a datetime.timedelta or numpy.timedelta64 (which will be formatted in whole number seconds)

__get__()

returns the string

__set__()

sets from a string, datetime.timedelta or numpy.timedelta64

timedelta_re = re.compile('^\\d+(ms|us|ns|[YMWDhms]){1}')

unit_keys_classes = {'D': ('days', <class 'datetime.timedelta'>), 'M': ('months', <class 'dateutil.relativedelta.relativedelta'>), 'W': ('weeks', <class 'dateutil.relativedelta.relativedelta'>), 'Y': ('years', <class 'dateutil.relativedelta.relativedelta'>), 'h': ('hours', <class 'datetime.timedelta'>), 'm': ('minutes', <class 'datetime.timedelta'>), 'ms': ('milliseconds', <class 'datetime.timedelta'>), 's': ('seconds', <class 'datetime.timedelta'>), 'us': ('microseconds', <class 'datetime.timedelta'>)}

_get(obj, objtype=None)

_set(obj, value)

_validate(obj, value)

class geodesic.descriptors._StringDescr(one_of=[], coerce=False, **kwargs)

Bases: geodesic.descriptors._BaseDescr

StringDescr is a string field, raises attribute error if the string isn’t set

Parameters

• one_of – is a list of possible values this string can be.

• coerce (bool) – stringify whatever the input

__get__()

returns the string

__set__()

sets the string after validating that it is a string/unicode

_get(obj, objtype=None)

_set(obj, value)

_validate(obj, value)

class geodesic.descriptors._IntDescr(**kwargs)

Bases: geodesic.descriptors._BaseDescr

IntDescr is an integer field, raises attribute error if the int isn’t set

__get__()

returns the int

__set__()

sets the int after validating that it is an int

_get(obj, objtype=None)

_set(obj, value)

_validate(obj, value)

class geodesic.descriptors._FloatDescr(**kwargs)

Bases: geodesic.descriptors._BaseDescr

FloatDescr is an float field, raises attribute error if the float isn’t set

__get__()

returns the float

__set__()

sets the float after validating that it is an float

_get(obj, objtype=None)

_set(obj, value)

_validate(obj, value)

class geodesic.descriptors._NumberDescr(**kwargs)

Bases: geodesic.descriptors._BaseDescr

NumberDescr is an numeric field, raises attribute error if the number isn’t set

__get__()

returns the number

__set__()

sets the number after validating that it is a number

_get(obj, objtype=None)

_set(obj, value)

_validate(obj, value)

class geodesic.descriptors._BoolDescr(**kwargs)

Bases: geodesic.descriptors._BaseDescr

BoolDescr is an bool field, raises attribute error if the bool isn’t set

__get__()

returns the bool

__set__()

sets the bool after validating that it is an bool

_get(obj, objtype=None)

_set(obj, value)

_validate(obj, value)

class geodesic.descriptors._DatetimeIntervalDescr(**kwargs)

Bases: geodesic.descriptors._BaseDescr

DatetimeIntervalDescr is a start/end pair which can be specified using either RFC3339 strings datetime.datetime, pandas.Timestamp, or numpy.datetime64

__get__()

returns the datetime interval as a tuple, raise an AttributeError if missing

__set__()

sets the datetime interval, storing internally as a string of the format ‘<start>/<end>’ where

start/end are RFC3339 formatted strings or "..". This is in accordance with the STAC datetime spec

rfc3339_regex = re.compile('^((?:(\\d{4}-\\d{2}-\\d{2})T(\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?))(Z|[\\+-]\\d{2}:\\d{2})?)$')

_get(obj, objtype=None)

_set(obj, value)

_validate(obj, value)

class geodesic.descriptors._DTypeDescr(**kwargs)

Bases: geodesic.descriptors._BaseDescr

DTypeDescr is a np.dtype field, raises attribute error if dtype is not set

__get__()

returns the np.dtype

__set__()

sets the dtype after validating that it is a dtype, holds internally by its str representation

_get(obj, objtype=None)

_set(obj, value)

_validate(obj, value)

class geodesic.descriptors._TypeConstrainedDescr(type, coerce=False, **kwargs)

Bases: geodesic.descriptors._BaseDescr

TypeConstrainedDescr creates an arbitrary field that must be constrained to a specific type

Parameters

• type (type) – the type you want to constrain this too

• coerce (bool) – the stored/retrieved result will be coerced to the type (or the first type in a tuple of types)

__get__()

returns the object as is, AttributeError if missing

__set__()

sets the object as is, validating against the specified type constraint

_get(obj, objtype=None)

_set(obj, value)

_validate(obj, value)

class geodesic.descriptors._URLDescr(one_of=[], coerce=False, **kwargs)

Bases: geodesic.descriptors._StringDescr

A URL string that is checked to be a valid URL. Inherits from _StringDescr for all methods except validate.

__get__()

Returns the validated URL string

__set__()

Check that its a valid URL and set the URL as a string

_validate(obj, value)