feat: add a portable bare-name dialect example

Portable/Portable.ipynb

@@ -0,0 +1,139 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Portable bare-name dialect\n",
+    "\n",
+    "Every MobilityDB operator is callable in PyMEOS under a single, stable\n",
+    "**portable bare name** (`overlaps`, `contains`, `teq`,\n",
+    "`nearestApproachDistance`, ...). The mapping is the cross-binding source\n",
+    "of truth ([RFC #920](https://github.com/MobilityDB/MobilityDB);\n",
+    "contract: `MobilityDB/MEOS-API` `meta/portable-aliases.json`), so the\n",
+    "*same* names work identically on every binding/engine (PyMEOS, JMEOS,\n",
+    "MEOS.NET, MobilityDuck, MobilitySpark, ...): a user learns one reference\n",
+    "and assumes the rest.\n",
+    "\n",
+    "The 29 bare names are **type-agnostic** — one name covers every temporal\n",
+    "type family (temporal, geo, cbuffer, npoint, pose, rgeo). Each bare name\n",
+    "dispatches, by the runtime type of its arguments, to the *exact* function\n",
+    "the operator is backed by, so it is identical to the operator by\n",
+    "construction (nothing is reimplemented).\n",
+    "\n",
+    "> Requires the portable dialect (`pymeos.portable`), added on the PyMEOS\n",
+    "> 1.4 line by PR #87. Until that release is published, install PyMEOS\n",
+    "> from the PR branch:\n",
+    "> `pip install \"git+https://github.com/MobilityDB/PyMEOS@feat/portable-aliases\"`"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pymeos import (\n",
+    "    pymeos_initialize,\n",
+    "    pymeos_finalize,\n",
+    "    TsTzSpan,\n",
+    "    TFloatSeq,\n",
+    "    TGeomPointSeq,\n",
+    ")\n",
+    "from pymeos.portable import (\n",
+    "    overlaps,\n",
+    "    teq,\n",
+    "    nearestApproachDistance,\n",
+    ")\n",
+    "\n",
+    "pymeos_initialize()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## One bare name, any type family\n",
+    "\n",
+    "The same callable works regardless of the argument types — it resolves\n",
+    "the matching backing function at call time."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Topology on time spans -> backed by overlaps_span_span\n",
+    "s1 = TsTzSpan(\"[2000-01-01, 2000-01-03]\")\n",
+    "s2 = TsTzSpan(\"[2000-01-02, 2000-01-05]\")\n",
+    "print(\"overlaps(span, span) :\", overlaps(s1, s2))\n",
+    "\n",
+    "# Temporal comparison on temporal floats -> backed by teq_temporal_temporal\n",
+    "a = TFloatSeq(\"[1@2000-01-01, 3@2000-01-03]\")\n",
+    "b = TFloatSeq(\"[2@2000-01-01, 2@2000-01-03]\")\n",
+    "print(\"teq(tfloat, tfloat)  :\", teq(a, b))\n",
+    "\n",
+    "# Spatial distance on temporal points -> backed by the nad_* family\n",
+    "p1 = TGeomPointSeq(\"[Point(0 0)@2000-01-01, Point(2 2)@2000-01-03]\")\n",
+    "p2 = TGeomPointSeq(\"[Point(1 0)@2000-01-01, Point(3 0)@2000-01-03]\")\n",
+    "print(\"nearestApproachDistance(tgeompoint, tgeompoint) :\",\n",
+    "      nearestApproachDistance(p1, p2))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Identical to the operator by construction\n",
+    "\n",
+    "A bare name reuses the operator's own backing function — the same native\n",
+    "call the type-qualified API makes — so results match exactly."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Portable bare name vs. the type-qualified API: same backing call.\n",
+    "print(\"portable       :\", overlaps(s1, s2))\n",
+    "print(\"type-qualified :\", s1.overlaps(s2))        # Span.overlaps\n",
+    "\n",
+    "print(\"portable       :\", teq(a, b))\n",
+    "print(\"type-qualified :\", a.temporal_equal(b))    # Temporal.temporal_equal"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "pymeos_finalize()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The full set of 29 portable bare names is `pymeos.portable.__all__`."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

Portable/requirements.txt

@@ -0,0 +1,5 @@
+# Requires the portable bare-name dialect (`pymeos.portable`), added on the
+# PyMEOS 1.4 line by PR #87.  Until that release is published, install
+# PyMEOS from the PR branch:
+#   pip install "git+https://github.com/MobilityDB/PyMEOS@feat/portable-aliases"
+pymeos>=1.4.0a1

README.md

@@ -1,7 +1,7 @@
 # PyMEOS Examples
 
 
-The examples provided are divided in two folders:
+The examples provided are divided in three folders:
 - [PyMEOS Examples](./PyMEOS_Examples)  
   Replicas of [Tutorial Programs of MEOS](https://www.libmeos.org/tutorialprograms/) using PyMEOS.
   - [AIS](./PyMEOS_Examples/AIS.ipynb): Contains the PyMEOS examples using AIS data 
@@ -16,3 +16,8 @@ The examples provided are divided in two folders:
     - [Temporal Aggregation of Trips](https://libmeos.org/tutorialprograms/meos_aggregate_berlinmod/)
 - [MovingPandas](./MovingPandas):  
   Replicas of [MovingPandas examples](https://github.com/anitagraser/movingpandas-examples) using PyMEOS. (WIP)
+- [Portable](./Portable):  
+  The portable bare-name dialect — every MobilityDB operator under one
+  stable, cross-binding name, type-agnostic across all temporal families.
+  - [Portable](./Portable/Portable.ipynb): Calling operators by their
+    canonical portable bare name in PyMEOS (`pymeos.portable`).