fairdm.utils.location.forms

Forms and widgets for entering locations.

Module Contents

Classes

Location	What a location input cleans to: a WGS 84 point with its elevation and uncertainty.
LocationWidget	The location input: a latitude and a longitude in WGS 84, elevation and uncertainty.
LocationField	Read a latitude and a longitude in signed decimal degrees, WGS 84.
LocationFormMixin	Give a ModelForm of a model with a location the location input.

API

class Location

Bases: typing.NamedTuple

What a location input cleans to: a WGS 84 point with its elevation and uncertainty.

Attributes: point: The point, in SRID 4326. elevation: Metres above mean sea level, or None. uncertainty: Metres, zero or more, or None.

point: django.contrib.gis.geos.Point

None

elevation: float | None

None

uncertainty: float | None

None

class LocationWidget(full=True, attrs=None)

Bases: django.forms.MultiWidget

The location input: a latitude and a longitude in WGS 84, elevation and uncertainty.

Args: full: Offer the elevation and uncertainty. Without it the widget asks for a latitude and a longitude only, as an organization’s point does. attrs: HTML attributes for the widget.

Initialization

template_name

‘location/widgets/location.html’

full_parts

(‘first’, ‘second’, ‘elevation’, ‘uncertainty’)

point_parts

(‘first’, ‘second’)

decompress(value)

Split a stored location into the values the inputs show.

Args: value: A Location, a bare GEOS point, or None.

Returns: The input values in order, with the coordinates as WGS 84 decimal degrees written out in full, so that saving an unchanged form leaves the point where it was.

get_context(name, value, attrs)

Add what the template reads: full and parts by name.

class LocationField(full=True, **kwargs)

Bases: django.forms.MultiValueField

Read a latitude and a longitude in signed decimal degrees, WGS 84.

Cleans to None when every input is empty, or to a Location whose point is in SRID 4326.

Args: full: Take an elevation and uncertainty besides the two coordinates. Without it the field takes a latitude and a longitude only. **kwargs: Passed to MultiValueField.

Initialization

compress(data_list)

Combine the inputs into a Location in WGS 84, or None when all are empty.

Args: data_list: The cleaned values of the inputs, in widget order.

Returns: A Location, or None.

Raises: ValidationError: Only one coordinate is given, or an elevation or uncertainty has no coordinates.

class LocationFormMixin(*args, **kwargs)

Give a ModelForm of a model with a location the location input.

When location is among the form’s fields, it becomes a full LocationField that starts from the instance’s point, elevation and uncertainty. On clean the point goes to location and the elevation and uncertainty to the instance, so that model validation sees the three together.

Example: python     class RockSampleForm(LocationFormMixin, forms.ModelForm):         class Meta:             model = RockSample             fields = ["name", "location"]    

Initialization

clean()

Move the cleaned location’s elevation and uncertainty onto the instance.