- | Tests |
+ Project Health |
+
+ 
+
@@ -79,17 +82,6 @@
- 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.4.1](https://github.com/LimeSurvey/LimeSurvey/releases/tag/6.4.1+240108)
-- [6.4.0](https://github.com/LimeSurvey/LimeSurvey/releases/tag/6.4.0+231218)
-- [6.3.9](https://github.com/LimeSurvey/LimeSurvey/releases/tag/6.3.9+231211)
-- [5.6.50](https://github.com/LimeSurvey/LimeSurvey/releases/tag/5.6.50+240109)
-- [5.6.49](https://github.com/LimeSurvey/LimeSurvey/releases/tag/5.6.49+231212)
-- [5.6.48](https://github.com/LimeSurvey/LimeSurvey/releases/tag/5.6.48+231205)
-
## Installation
```sh
@@ -134,9 +126,11 @@ If you'd like to contribute to this project, please see the [contributing guide]
## Credits
+- The [LimeSurvey][limesurvey-site] team for providing a great survey platform.
- [Markus Opolka][martialblog] for maintaining a very robust set of [LimeSurvey Docker images](https://github.com/martialblog/docker-limesurvey/).
- [Claudio Jolowicz][claudio] and [his amazing blog post][hypermodern].
[claudio]: https://twitter.com/cjolowicz/
[hypermodern]: https://cjolowicz.github.io/posts/hypermodern-python-01-setup/
+[limesurvey-site]: https://www.limesurvey.org/
[martialblog]: https://github.com/martialblog/
diff --git a/code_samples/duckdb_sql.py b/code_samples/duckdb_sql.py
index 7ab1d7af..092bd733 100644
--- a/code_samples/duckdb_sql.py
+++ b/code_samples/duckdb_sql.py
@@ -2,9 +2,11 @@
from __future__ import annotations
-# ruff: noqa: I001, PTH123
+# ruff: noqa: I001, PTH123, FURB103
# start example
+from pathlib import Path
+
import citric
import duckdb
@@ -14,8 +16,7 @@
"secret",
)
-with open("responses.csv", "wb") as file:
- file.write(client.export_responses(12345, file_format="csv"))
+Path("responses.csv").write_bytes(client.export_responses(12345, file_format="csv"))
duckdb.execute("CREATE TABLE responses AS SELECT * FROM 'responses.csv'")
duckdb.sql("""
diff --git a/code_samples/ruff.toml b/code_samples/ruff.toml
index 8eaab689..a6c5fca3 100644
--- a/code_samples/ruff.toml
+++ b/code_samples/ruff.toml
@@ -1,4 +1,6 @@
extend = "../pyproject.toml"
+
+[lint]
ignore = [
"INP001", # implicit-namespace-package
]
diff --git a/code_samples/session_attr.py b/code_samples/session_attr.py
index 1cb19d59..21de4284 100644
--- a/code_samples/session_attr.py
+++ b/code_samples/session_attr.py
@@ -11,6 +11,9 @@
"secret",
)
-# Call the not_available_in_client method, not available in the RPC class
-new_survey_id = client.session.not_available_in_client(35239, "copied_survey")
+# Get the raw response from mail_registered_participants
+result = client.session.call("mail_registered_participants", 35239)
+
+# Get the raw response from remind_participants
+result = client.session.call("remind_participants", 35239)
# end example
diff --git a/docker-compose.yml b/docker-compose.yml
index 146fbd71..fb2bff36 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -26,10 +26,10 @@ services:
EMAIL_SMTPPASSWORD: ${LS_SMTP_PASSWORD:-secret}
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8080/index.php/admin"]
- interval: 30s
+ interval: 15s
timeout: 10s
retries: 3
- start_period: 15s
+ start_period: 5s
db:
image: postgres:16
@@ -43,8 +43,8 @@ services:
- 5432:5432
healthcheck:
test: ["CMD", "pg_isready", "-U", "limesurvey"]
- interval: 30s
- timeout: 30s
+ interval: 15s
+ timeout: 10s
retries: 3
storage:
@@ -57,6 +57,7 @@ services:
command: server /data --console-address ":9001"
profiles:
- web
+ - notebook
mailhog:
image: mailhog/mailhog
diff --git a/docs/conf.py b/docs/conf.py
index e47d7dd7..e7ca5f8f 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -13,18 +13,25 @@
if t.TYPE_CHECKING:
from sphinx.application import Sphinx
+# -- Project information ---------------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
project = "citric"
+
author = "Edgar Ramírez Mondragón"
+project_copyright = f"2020, {author}"
version = citric.__version__
release = citric.__version__
-project_copyright = f"2020, {author}"
+
+# -- General configuration -------------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.extlinks",
"sphinx.ext.intersphinx",
"sphinx.ext.linkcode",
"sphinx.ext.napoleon",
- "sphinx_autodoc_typehints",
"autoapi.extension",
"myst_parser",
"sphinx_copybutton",
@@ -33,30 +40,29 @@
"notfound.extension",
]
-myst_heading_anchors = 2
+source_suffix = {
+ ".rst": "restructuredtext",
+ ".md": "markdown",
+}
-autodoc_typehints = "description"
-autodoc_typehints_description_target = "documented"
+nitpicky = True
+nitpick_ignore = {
+ ("py:class", "citric.types.Result"),
+ ("py:class", "Result"),
+ ("py:class", "YesNo"),
+ ("py:class", "T"),
+ ("py:obj", "T"),
+}
-autoapi_type = "python"
-autoapi_root = "_api"
-autoapi_dirs = [
- Path("../src").resolve(),
-]
-autoapi_options = [
- "members",
- "undoc-members",
- "show-inheritance",
- "show-module-summary",
- "special-members",
- "imported-members",
- "private-members",
-]
+# -- Options for internationalization --------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-internationalization
+
+# -- Options for Math ------------------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-math
+
+# -- Options for HTML output -----------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
-html_extra_path = [
- "googled10b55fb460af091.html",
- "code.png",
-]
html_theme = "furo"
html_theme_options = {
"navigation_with_keys": True,
@@ -65,46 +71,47 @@
"source_directory": "docs/",
}
html_title = "Citric, a Python client for LimeSurvey"
-
-hoverxref_default_type = "tooltip"
-
-intersphinx_mapping = {
- "requests": ("https://requests.readthedocs.io/en/latest/", None),
- "requests-cache": ("https://requests-cache.readthedocs.io/en/stable/", None),
- "python": ("https://docs.python.org/3/", None),
-}
-
-hoverxref_intersphinx = [
- "requests",
+html_extra_path = [
+ "googled10b55fb460af091.html",
+ "code.png",
]
-hoverxref_domains = [
- "py",
-]
+# -- Options for Autodoc ---------------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration
-hoverxref_role_types = {
- "hoverxref": "tooltip",
- "ref": "modal",
- "mod": "modal",
- "class": "tooltip",
-}
+autodoc_typehints = "description"
+autodoc_typehints_description_target = "documented"
+
+# -- Options for extlinks --------------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
extlinks = {
"rpc_method": (
- "https://api.limesurvey.org/classes/remotecontrol_handle.html#method_%s",
+ "https://api.limesurvey.org/classes/remotecontrol-handle.html#method_%s",
"RPC method %s",
),
"ls_manual": (
"https://manual.limesurvey.org/%s",
"%s",
),
+ "ls_tag": (
+ "https://github.com/LimeSurvey/LimeSurvey/releases/tag/%s",
+ "%s",
+ ),
}
-source_suffix = {
- ".rst": "restructuredtext",
- ".md": "markdown",
+# -- Options for intersphinx -----------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration
+
+intersphinx_mapping = {
+ "requests": ("https://requests.readthedocs.io/en/latest/", None),
+ "requests-cache": ("https://requests-cache.readthedocs.io/en/stable/", None),
+ "python": ("https://docs.python.org/3/", None),
}
+# -- Options for linkcode --------------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/linkcode.html#configuration
+
def linkcode_resolve(domain: str, info: dict) -> str | None:
"""Get URL to source code.
@@ -124,6 +131,49 @@ def linkcode_resolve(domain: str, info: dict) -> str | None:
return f"https://github.com/edgarrmondragon/citric/tree/main/src/{filename}.py"
+# -- Options for Napoleon --------------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#configuration
+
+# -- Options for AutoAPI ---------------------------------------------------------------
+# https://sphinx-autoapi.readthedocs.io/en/latest/reference/config.html
+
+autoapi_dirs = [
+ Path("../src").resolve(),
+]
+autoapi_options = [
+ "members",
+ "undoc-members",
+ "show-inheritance",
+ "show-module-summary",
+ "special-members",
+ "imported-members",
+ "private-members",
+]
+autoapi_root = "_api"
+
+# -- Options for Myst ------------------------------------------------------------------
+# https://myst-parser.readthedocs.io/en/latest/configuration.html
+
+myst_heading_anchors = 2
+
+# -- Options for hoverxref -------------------------------------------------------------
+# https://sphinx-hoverxref.readthedocs.io/en/latest/configuration.html
+
+hoverxref_role_types = {
+ "hoverxref": "tooltip",
+ "ref": "modal",
+ "mod": "modal",
+ "class": "tooltip",
+}
+hoverxref_default_type = "tooltip"
+hoverxref_domains = [
+ "py",
+]
+hoverxref_intersphinx = [
+ "requests",
+]
+
+
def skip_member_filter(
app: Sphinx, # noqa: ARG001
what: str, # noqa: ARG001
diff --git a/docs/contributing/environment.md b/docs/contributing/environment.md
index 7e431fe8..441a22f5 100644
--- a/docs/contributing/environment.md
+++ b/docs/contributing/environment.md
@@ -14,8 +14,6 @@ Ready to contribute? Here's how to set up `citric` for local development.
cd citric
```
-1. Install [`hatch`][hatch]:
-
1. Install [`nox`][nox] (used for automation):
```shell
@@ -54,7 +52,6 @@ Ready to contribute? Here's how to set up `citric` for local development.
changie new
```
-[hatch]: https://hatch.pypa.io/latest/install/
[nox]: https://nox.thea.codes/en/stable/
[pre-commit]: https://pre-commit.com/
[changie]: https://changie.dev/
diff --git a/docs/contributing/update-github-actions.md b/docs/contributing/update-github-actions.md
new file mode 100644
index 00000000..bac8f41f
--- /dev/null
+++ b/docs/contributing/update-github-actions.md
@@ -0,0 +1,25 @@
+# Update GitHub Actions pins
+
+There are a few ways to update the GitHub Actions pins.
+
+## Run workflow in GitHub
+
+Go to the [Actions tab](https://github.com/edgarrmondragon/citric/actions/workflows/gha-update.yml) and click on the `Run workflow` dropdown.
+
+## Run workflow locally
+
+1. Install the [GitHub CLI](https://cli.github.com/).
+2. Run the following command:
+
+ ```bash
+ gh workflow run gha-update.yml
+ ```
+
+## Run the `gha-update` tool locally
+
+1. Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/).
+2. Run the following command:
+
+ ```bash
+ uvx gha-update
+ ```
diff --git a/docs/how-to.md b/docs/how-to.md
index 50b35aa7..a3f95aaf 100644
--- a/docs/how-to.md
+++ b/docs/how-to.md
@@ -39,7 +39,7 @@ Otherwise, you can manually close the session with {meth}`client.close() ` are supported by the
+{ls_manual}`different plugins ` are supported using the
`auth_plugin` argument.
```{literalinclude} ../code_samples/auth_plugin.py
@@ -72,7 +72,7 @@ Common plugins are `Authdb` (default), `AuthLDAP` and `Authwebserver`.
## Use the session attribute for low-level interaction
-This library doesn't (yet) implement all RPC methods, so if you're in dire need of using a method not currently supported, you can use the `session` attribute to invoke the underlying RPC interface without having to pass a session key explicitly:
+This library doesn't implement all RPC methods, so if you're in dire need of using a method not currently supported, you can use the `session` attribute to invoke the underlying RPC interface without having to pass a session key explicitly:
```{literalinclude} ../code_samples/session_attr.py
:start-after: start example
diff --git a/docs/index.md b/docs/index.md
index 69dbed62..f370b4e2 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -18,6 +18,19 @@ Release **v{sub-ref}`version`**. ([What's new?](./changelog.md))
:end-before:
```
+### 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:
+
+- {ls_tag}`6.5.9+240521`
+- {ls_tag}`6.5.7+240515`
+- {ls_tag}`6.5.5+240429`
+- {ls_tag}`5.6.65+240522`
+- {ls_tag}`5.6.63+240508`
+- {ls_tag}`5.6.61+240430`
+
+But also, the latest 5.x and 6.x are tested continuously and are expected to work.
+
## How-to guides
- [Automatically close the session with a context manager](how-to.md#automatically-close-the-session-with-a-context-manager)
@@ -25,7 +38,7 @@ Release **v{sub-ref}`version`**. ([What's new?](./changelog.md))
- [Export responses to a `pandas` dataframe](how-to.md#export-responses-to-a-pandas-dataframe)
- [Export responses to a DuckDB database and analyze with SQL](how-to.md#export-responses-to-a-duckdb-database-and-analyze-with-sql)
- [Change the default HTTP session attributes](how-to.md#change-the-default-http-session-attributes)
-- [Use custom `requests` session](how-to.md#use-custom-requests-session)
+- [Use a custom `requests` session](how-to.md#use-a-custom-requests-session)
- [Use a different authentication plugin](how-to.md#use-a-different-authentication-plugin)
- [Get files uploaded to a survey and move them to S3](how-to.md#get-files-uploaded-to-a-survey-and-move-them-to-s3)
- [Use the raw `RPC.session` for low-level interaction](how-to.md#use-the-session-attribute-for-low-level-interaction)
@@ -85,4 +98,5 @@ contributing/docs
contributing/docker
contributing/release
contributing/unreleased-features
+contributing/update-github-actions
```
diff --git a/docs/notebooks/duckdb.ipynb b/docs/notebooks/duckdb.ipynb
index 15ec56e1..8a067d59 100644
--- a/docs/notebooks/duckdb.ipynb
+++ b/docs/notebooks/duckdb.ipynb
@@ -11,19 +11,9 @@
"cell_type": "code",
"execution_count": 1,
"metadata": {},
- "outputs": [
- {
- "name": "stdout",
- "output_type": "stream",
- "text": [
- "Note: you may need to restart the kernel to use updated packages.\n",
- "Note: you may need to restart the kernel to use updated packages.\n"
- ]
- }
- ],
+ "outputs": [],
"source": [
- "%pip install --upgrade pip duckdb-engine faker sqlalchemy jupysql --quiet\n",
- "%pip install ../.. --quiet # or pip install citric"
+ "!pip install --upgrade pip citric duckdb-engine faker jupysql sqlalchemy --quiet"
]
},
{
@@ -147,7 +137,12 @@
}
],
"source": [
- "client.activate_survey(survey_id)\n",
+ "client.activate_survey(\n",
+ " survey_id,\n",
+ " user_activation_settings={\n",
+ " \"datestamp\": True,\n",
+ " },\n",
+ ")\n",
"client.activate_tokens(survey_id)\n",
"\n",
"result = client.add_responses(survey_id, fake_responses)\n",
@@ -168,7 +163,12 @@
"outputs": [],
"source": [
"with Path(\"responses.csv\").open(\"wb\") as file:\n",
- " file.write(client.export_responses(survey_id, file_format=\"csv\"))"
+ " file.write(\n",
+ " client.export_responses(\n",
+ " survey_id,\n",
+ " file_format=\"csv\",\n",
+ " )\n",
+ " )"
]
},
{
@@ -186,10 +186,10 @@
{
"data": {
"text/html": [
- "Found pyproject.toml from '/Users/edgarramirez/Code/edgarrmondragon/citric'"
+ "The 'toml' package isn't installed. To load settings from pyproject.toml or ~/.jupysql/config, install with: pip install toml"
],
"text/plain": [
- "Found pyproject.toml from '/Users/edgarramirez/Code/edgarrmondragon/citric'"
+ "The 'toml' package isn't installed. To load settings from pyproject.toml or ~/.jupysql/config, install with: pip install toml"
]
},
"metadata": {},
@@ -204,7 +204,20 @@
"cell_type": "code",
"execution_count": 9,
"metadata": {},
- "outputs": [],
+ "outputs": [
+ {
+ "data": {
+ "text/html": [
+ "Connecting to 'duckdb://'"
+ ],
+ "text/plain": [
+ "Connecting to 'duckdb://'"
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ }
+ ],
"source": [
"%sql duckdb://"
]
@@ -237,8 +250,7 @@
" \n",
" \n",
" \n",
- " |