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)[source]¶
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.
- _validate(obj, value)[source]¶
override for type specific validation. Should raise an exception if invalid, not return a bool
- _get_object(obj)[source]¶
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)[source]¶
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)[source]¶
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
field. (geometry/bbox in sync on objects where the bbox is always derived from a geometry) –
- __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)[source]¶
Gets the geometry attribute of an object.
- Raises
AttributeError if geometry is None or doesn't exist –
- class geodesic.descriptors._BBoxDescr(**kwargs)[source]¶
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
- class geodesic.descriptors._RegexDescr(regex, empty_allowed=False, **kwargs)[source]¶
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
- class geodesic.descriptors._DictDescr(**kwargs)[source]¶
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
- class geodesic.descriptors._ListDescr(item_type=None, min_len=None, max_len=None, coerce_items=False, **kwargs)[source]¶
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
- class geodesic.descriptors._TupleDescr(item_type=None, min_len=None, max_len=None, **kwargs)[source]¶
Bases:
geodesic.descriptors._BaseDescr
TupleDescr is a tuple field (immutable), such as image shape.
This raises an attribute error
- Parameters
- __get__()¶
returns the tuple, creating it on the base object if necessary
- __set__()¶
sets the tuple after validating that it is a tuple
- class geodesic.descriptors._DatetimeDescr(**kwargs)[source]¶
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})?)$')¶
- class geodesic.descriptors._TimeDeltaDescr(**kwargs)[source]¶
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'>)}¶
- class geodesic.descriptors._StringDescr(one_of=[], coerce=False, **kwargs)[source]¶
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
- class geodesic.descriptors._IntDescr(**kwargs)[source]¶
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
- class geodesic.descriptors._FloatDescr(**kwargs)[source]¶
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
- class geodesic.descriptors._NumberDescr(**kwargs)[source]¶
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
- class geodesic.descriptors._BoolDescr(**kwargs)[source]¶
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
- class geodesic.descriptors._DatetimeIntervalDescr(format='string', **kwargs)[source]¶
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})?)$')¶
- class geodesic.descriptors._DTypeDescr(**kwargs)[source]¶
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
- class geodesic.descriptors._TypeConstrainedDescr(type, coerce=False, **kwargs)[source]¶
Bases:
geodesic.descriptors._BaseDescr
TypeConstrainedDescr creates an arbitrary field that must be constrained to a specific type
- Parameters
- __get__()¶
returns the object as is, AttributeError if missing
- __set__()¶
sets the object as is, validating against the specified type constraint
- class geodesic.descriptors._URLDescr(one_of=[], coerce=False, **kwargs)[source]¶
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