feat: Experimental support for the new REST API (#994)

* First commit

* Tweak experimental API language

* XFail on 5.x

* Do not try to create REST client in unsupported versions

* Implement survey detail

* Add unit tests

* Do not pull MarkupSafe binary for PyPy

* Add missing test

* Fix mypy

* Use TypeAlias

* Add context manager to REST client

* Add change file

* Skip docs for citric._rest.client

* Move to citric.rest

* Abstract away request logic

* Update lockfile

* Skip binary wheel for MarkupSafe in python 3.13

* Fix typo

* Document REST coverage

* Document REST coverage

* Make RESTClient.authenticate a side effect

* Sort tags lexicographically

* Remove unnecessary classifiers

* Add async client

* Revert "Add async client"

This reverts commit 672ca69.

* Make REST module private

* Update expection for PATCH `survey-detail`

* Document REST client

* Update integration tests list

.changes/unreleased/Added-20230920-033626.yaml

@@ -0,0 +1,5 @@
+kind: Added
+body: Experimental support for the new REST API
+time: 2023-09-20T03:36:26.529589-06:00
+custom:
+  Issue: "994"

.github/workflows/tests.yml

@@ -325,7 +325,7 @@ jobs:
       id: nox-integration
       env:
         BACKEND: ${{ matrix.database }}
-        LS_URL: http://localhost:${{ env.LS_PORT }}/index.php/admin/remotecontrol
+        LS_URL: http://localhost:${{ env.LS_PORT }}
       run: |
         nox
 

README.md

@@ -57,17 +57,18 @@
 - Easily export survey data to CSV files, [Pandas DataFrames](https://citric.readthedocs.io/en/stable/how-to.html#export-responses-to-a-pandas-dataframe) and [DuckDB databases](https://citric.readthedocs.io/en/stable/how-to.html#export-responses-to-a-duckdb-database-and-analyze-with-sql).
 - Easily [download survey files](https://citric.readthedocs.io/en/stable/how-to.html#get-files-uploaded-to-a-survey-and-move-them-to-s3) (e.g. images, audio, etc.) to a local directory.
 - Tested against LimeSurvey 6.0.0+ and 5.0.0+ versions.
+- Experimental support for the new [REST API](https://manual.limesurvey.org/REST_API).
 
 ### Integration tests
 
 Integration tests are run against a LimeSurvey instance, and both PostgreSQL and MySQL backends, using Docker Compose. The following versions of LimeSurvey were tested for this release:
 
-- [6.3.5](https://github.com/LimeSurvey/LimeSurvey/releases/tag/6.3.4%2B231108)
-- [6.3.4](https://github.com/LimeSurvey/LimeSurvey/releases/tag/6.3.3%2B231106)
-- [6.3.3](https://github.com/LimeSurvey/LimeSurvey/releases/tag/6.3.1%2B231023)
-- [5.6.45](https://github.com/LimeSurvey/LimeSurvey/releases/tag/5.6.44%2B231107)
-- [5.6.44](https://github.com/LimeSurvey/LimeSurvey/releases/tag/5.6.43%2B231030)
-- [5.6.43](https://github.com/LimeSurvey/LimeSurvey/releases/tag/5.6.42%2B231024)
+- [6.3.6](https://github.com/LimeSurvey/LimeSurvey/releases/tag/6.3.6%2B231120)
+- [6.3.5](https://github.com/LimeSurvey/LimeSurvey/releases/tag/6.3.5%2B231113)
+- [6.3.4](https://github.com/LimeSurvey/LimeSurvey/releases/tag/6.3.4%2B231108)
+- [5.6.46](https://github.com/LimeSurvey/LimeSurvey/releases/tag/5.6.46%2B231121)
+- [5.6.45](https://github.com/LimeSurvey/LimeSurvey/releases/tag/5.6.45%2B231114)
+- [5.6.44](https://github.com/LimeSurvey/LimeSurvey/releases/tag/5.6.44%2B231107)
 
 ## Installation
 

docs/conf.py

@@ -3,12 +3,15 @@
 from __future__ import annotations
 
 import sys
+import typing as t
 from pathlib import Path
 
 import citric
 
 sys.path.append(str(Path("./_ext").resolve()))
 
+if t.TYPE_CHECKING:
+    from sphinx.application import Sphinx
 
 project = "citric"
 author = "Edgar Ramírez Mondragón"
@@ -123,3 +126,39 @@ def linkcode_resolve(domain: str, info: dict) -> str | None:
         return None
     filename = info["module"].replace(".", "/")
     return f"https://github.com/edgarrmondragon/citric/tree/main/src/{filename}.py"
+
+
+def skip_member_filter(
+    app: Sphinx,  # noqa: ARG001
+    what: str,  # noqa: ARG001
+    name: str,
+    obj: t.Any,  # noqa: ARG001, ANN401
+    skip: bool,  # noqa: FBT001
+    options: t.Any,  # noqa: ARG001, ANN401
+) -> bool | None:
+    """Filter autoapi members.
+
+    Args:
+        app: Sphinx application object.
+        what: The type of the object which the docstring belongs to.
+        name: The fully qualified name of the object.
+        obj: The object itself.
+        skip: Whether AutoAPI will skip this member if the handler does not override
+            the decision.
+        options: The options given to the directive.
+
+    Returns:
+        Whether to skip the member.
+    """
+    if name == "citric.rest.client":
+        skip = True
+    return skip
+
+
+def setup(sphinx: Sphinx) -> None:
+    """Setup function.
+
+    Args:
+        sphinx: Sphinx application object.
+    """
+    sphinx.connect("autoapi-skip-member", skip_member_filter)

docs/contributing/docker.md

@@ -27,7 +27,7 @@ LimeSurvey. First you'll need to setup the environment variables:
 
 ```shell
 export BACKEND=postgres
-export LS_URL=http://localhost:8001/index.php/admin/remotecontrol
+export LS_URL=http://localhost:8001
 export LS_USER=iamadmin
 export LS_PASSWORD=secret
 ```

docs/index.md

@@ -49,6 +49,7 @@ how-to
 :hidden:
 
 RPC method coverage <rpc_coverage>
+REST endpoints coverage <rest_coverage>
 ```
 
 ```{toctree}

docs/rest_coverage.md

@@ -0,0 +1,10 @@
+# REST endpoints coverage
+
+
+| Name                                       | Implemented                                         |
+| :----------------------------------------- | :-------------------------------------------------- |
+| `POST /rest/v1/session`                    | [Yes](citric._rest.RESTClient.authenticate)          |
+| `DELETE /rest/v1/session`                  | [Yes](citric._rest.RESTClient.close)                 |
+| `GET /rest/v1/survey`                      | [Yes](citric._rest.RESTClient.get_surveys)           |
+| `GET /rest/v1/survey-detail/{survey_id}`   | [Yes](citric._rest.RESTClient.get_survey_details)    |
+| `PATCH /rest/v1/survey-detail/{survey_id}` | [Yes](citric._rest.RESTClient.update_survey_details) |

noxfile.py

@@ -23,9 +23,11 @@
     "coverage[toml]",
     "faker",
     "pytest",
+    "pytest-httpserver",
     "pytest-subtests",
     "python-dotenv",
     "semver",
+    "tinydb",
 ]
 
 package = "citric"
@@ -50,7 +52,10 @@ def tests(session: Session) -> None:
         deps.append("pytest-github-actions-annotate-failures")
 
     if session.python == "3.13":
-        env["PIP_NO_BINARY"] = "coverage"
+        env["PIP_NO_BINARY"] = "coverage,MarkupSafe"
+
+    if session.python.startswith("pypy"):
+        env["PIP_NO_BINARY"] = "MarkupSafe"
 
     session.install(".", env=env)
     session.install(*deps, env=env)
@@ -134,12 +139,13 @@ def mypy(session: Session) -> None:
         "faker",
         "mypy",
         "pytest",
+        "pytest-httpserver",
         "pytest-subtests",
         "python-dotenv",
         "semver",
         "sphinx",
+        "tinydb",
         "types-requests",
-        "types-tabulate",
         "typing-extensions",
     )
     session.run("mypy", *args)