[uss_qualifier/resource] Add base class for geospatial modifier

[the-glu]

Continuing on #1465 for #1458, this PR introduce:

• GeospatialResource, as suggested to ease implementation of
• GeospatialModifier, allowing a resource to generate unique 'Geospatial' resources

Include simple unit tests with a TestSquareResource.

[BenjaminPelletier]

I think I misread #1465 and would like to adjust it before looking closely at this one. The issue is that I would expect "resource modifier" to mean something that modifies resources, but the more important aspect of ResourceModifier in #1465 is that it presents as the modified resource itself, so it seems like a better name would be "IndexAdjustableResource". That's important because in this PR we have GeospatialModifierResource and with a name like that, I would expect it to handle any geospatial modification we might want to make to resources. Instead, it's actually just one particular way to offset GeospatialResources. With AdjustableResource, I think it would be more obvious that a name like GeospatiallyOffsetResource is probably more descriptive than GeospatialModifierResource. I think this is important because this is an external surface of the product that users will directly see and touch. I'll propose an adjustment PR.

[the-glu]

I think I misread #1465 and would like to adjust it before looking closely at this one. The issue is that I would expect "resource modifier" to mean something that modifies resources, but the more important aspect of ResourceModifier in #1465 is that it presents as the modified resource itself, so it seems like a better name would be "IndexAdjustableResource".

Ok, to do that (behaving as the modified resource, witch it doesn't do for now) we can just have it expose the underlying type as well + proxy with getattr()/setattr() attributes to the underling resources.

Let me know, I can also do the change :)

[the-glu]

@BenjaminPelletier I pre-rebased that one on top of #1474

Not sure about naming for this base class, I will update next ones in the chain when that one seems ok

[BenjaminPelletier]

This branch currently has merge conflicts which makes the diffs hard to interpret; can we merge main into this branch or rebase the changes onto main?

[the-glu]

This branch currently has merge conflicts which makes the diffs hard to interpret; can we merge main into this branch or rebase the changes onto main?

Rebased, not sure why it diverged again

[BenjaminPelletier]

The specification is a contract for how the modifier will behave so I think we want to make behavior as explicit as possible to avoid mismatched expectations. I don't think 1km is a universally-good default, so let's just require the user to provide the values explicitly so we know they match their use case. Also, this is an API-level definition, so let's make sure to document it well.

Suggested change

	meters_east_margin: float = 1000
	meters_north_margin: float = 1000
	meters_east_margin: float
	"""Modify the resource by moving it this far along the east-west axis to separate it from other modification instances."""
	meters_north_margin: float
	"""Modify the resource by moving it this far along the north-south axis to separate it from other modification instances."""

[BenjaminPelletier]

It seems like a GeospatialResource can exist without modifiers; can we rename this file geospatial.py since it pertains to geospatial resources, including their modification?

[BenjaminPelletier]

The implementation of this class seems too narrow to fit its name. If we want to make a single GeospatialModifier, then we should make sure to leave the door open to all kinds of geospatial modifications we could potentially want to make in the future, so the specification would probably look more like:

class IntervalOffset(ImplicitDict):
    meters_east_margin: float
    """Size of the interval in the north-south axis (meters)."""

    meters_north_margin: float
    """Size of the interval in the east-west axis (meters)."""

class GeospatialModifierSpecification(ImplicitDict):
    triangular_cascade_southeast: Optional[IntervalOffset]
    """When specified, offset the geospatial resource in a triangular cascade to the southeast according to an `index`."""

    <other styles of geospatial modification would presumably go here in the future>

But, it seems like it would probably be more robust to just name this modifier according to its narrow implementation:

Suggested change

	class GeospatialModifier[GeospatialResourceType: GeospatialResource](
	ResourceProvidingResource[GeospatialModifierSpecification, GeospatialResourceType]
	):
	class TriangularCascadeSoutheastResource[GeospatialResourceType: GeospatialResource](
	ResourceProvidingResource[GeospatialModifierSpecification, GeospatialResourceType]
	):
	"""Provides modified copies of a base geospatial resource which are offset east and south of the original resource."""

[BenjaminPelletier]

Documentation is especially important when a definition is intended to be reused by other contributors in the future and has more than one reasonable interpretation (e.g., mutate in place and return literal self, as in the Java "factory" pattern):

Suggested change

	def move(self, meters_east: float, meters_north: float) -> Self:
	def move(self, meters_east: float, meters_north: float) -> Self:
	"""Return a copy of this resource that has been moved the specified number of meters east and north."""