DOC: improve doc of where param

[theroggy]

reference #276

Note: for the links to external pages in the inline documentation, I had to put newlines around the links below, otherwise ".." is placed at the end of them and then most don't work anymore as intended.

For reference, this is the script used to test what the documentation should contain:

from pathlib import Path
import warnings
import pyogrio

# Ignore all warnings
warnings.simplefilter("ignore")

url_shp = "https://github.com/theroggy/pysnippets/raw/main/pysnippets/pyogrio/polygon-parcel_31370.zip"
url_gpkg = "https://github.com/geofileops/geofileops/raw/main/tests/data/polygon-parcel.gpkg"
wheres = [
    None,
    "LBLHFDTLT LIKE 'Gras%'",
    "LBLHFDTLT LIKE 'gras%'",
    "LBLHFDTLT ILIKE 'gras%'",
    "LBLHFDTLT NOT LIKE 'Gras%'",
    "LBLHFDTLT != 'Grasklaver'",
    "LBLHFDTLT IN ('Hoofdgebouwen', 'Grasklaver')",
    f"ST_Area({{geometrycolumn}}) > 1000",
]

for where in wheres:
    for url in [url_shp, url_gpkg]:
        for sql_dialect in [None, "OGRSQL", "SQLITE"]:
            where_f = where
            if where is not None:
                geometrycolumn = "geom" if url.endswith(".gpkg") else "geometry"
                where_f = where.format(geometrycolumn=geometrycolumn)
            try:
                df = pyogrio.read_dataframe(url, where=where_f)
                # print(f"\nnb_rows with where: {where}: {len(df)}")
                # print(df["LBLHFDTLT"].unique())
            except Exception as ex:
                name = Path(url).name
                print(f"Error, where={where_f}, sql_dialect={sql_dialect} on {name}")

Output:

Error, where=LBLHFDTLT ILIKE 'gras%', sql_dialect=None on polygon-parcel.gpkg
Error, where=LBLHFDTLT ILIKE 'gras%', sql_dialect=OGRSQL on polygon-parcel.gpkg
Error, where=LBLHFDTLT ILIKE 'gras%', sql_dialect=SQLITE on polygon-parcel.gpkg
Error, where=ST_Area(geometry) > 1000, sql_dialect=None on polygon-parcel_31370.zip
Error, where=ST_Area(geometry) > 1000, sql_dialect=OGRSQL on polygon-parcel_31370.zip
Error, where=ST_Area(geometry) > 1000, sql_dialect=SQLITE on polygon-parcel_31370.zip