docs: Clarification of STRTree documentation

I would like to (slightly) improve the documentation for the STRTree.

http://shapely.readthedocs.io/en/stable/manual.html#str-packed-r-tree says

Shapely provides an interface to the query-only GEOS R-tree packed using the Sort-Tile-Recursive algorithm. Pass a list of geometry objects to the STRtree constructor to create an R-tree that you can query with another geometric object.

The example then shows two queries that return Geometry objects.

I was hoping I could use STRTree just like the rtree module: passing index numbers to be able to match geometries to (Fiona) features but that seems not to be the case. STRTree simply takes a list of Geometry objects and on a query, returns the intersecting Geometry objects it knows about. There is no order or indices. Is that correct?

If so, I would just add one sentences about what the query method returns. For class descriptions (e.g. Point) the attributes are presented in prose, but if this should get a new .. method:: entry, just say so. 😃

[kannes]

https://github.com/Toblerity/Shapely/pull/623 thanks to QGIS’s @nathanw

[sgillies]

@kannes we’re not flexible right now about what gets stored, but we do store the geometry object as well as all its attributes. You can add attributes to a geometry object after it has been created because these geometry objects store their attributes in a __dict__ member (geom.myattr gets read as geom.__dict__['myattr']). We’re not going to change this behavior of Shapely any time soon, so the following code should work at least until a hypothetical Shapely 2.0:

>>> from shapely.strtree import STRtree
>>> from shapely.geometry import Point
>>> pt = Point(0.0, 0.0)
>>> pt.name = 'foo'
>>> tree = STRtree([pt])
>>> tree.query(Point(1.0, 1.0).buffer(2.0))
[<shapely.geometry.point.Point object at 0x109254208>]
>>> results = tree.query(Point(1.0, 1.0).buffer(2.0))
>>> respt = results[0]
>>> respt
<shapely.geometry.point.Point object at 0x109254208>
>>> respt.name
'foo'

There is some related discussion in #615.