feat: Support userActivationSettings parameter in RPC method `activ…

…ate_survey`

.changes/unreleased/Added-20231028-222932.yaml

@@ -1,5 +1,5 @@
 kind: Added
-body: Support `DestSurveyID` parameter to RPC method `copy_survey`
+body: Support `DestSurveyID` parameter in RPC method `copy_survey`
 time: 2023-10-28T22:29:32.491728-06:00
 custom:
   Issue: "1016"

.changes/unreleased/Added-20231109-165350.yaml

@@ -0,0 +1,5 @@
+kind: Added
+body: Support `userActivationSettings` parameter in RPC method `activate_survey`
+time: 2023-11-09T16:53:50.378464-06:00
+custom:
+  Issue: "1026"

.changes/unreleased/Fixed-20231109-165446.yaml

@@ -0,0 +1,5 @@
+kind: Fixed
+body: Update `types.YesNo` to include inherited (`I`) values
+time: 2023-11-09T16:54:46.179939-06:00
+custom:
+  Issue: "1026"

.flake8

@@ -1,5 +1,5 @@
 [flake8]
-select = DAR
+select = DOC
 docstring_style=google
 max-line-length = 88
 strictness = short

.pre-commit-config.yaml

@@ -47,10 +47,10 @@ repos:
   hooks:
   - id: flake8
     additional_dependencies:
-    - darglint==1.8.1
+    - pydoclint==0.3.8
 
 - repo: https://github.com/pre-commit/mirrors-mypy
-  rev: v1.6.1
+  rev: v1.7.0
   hooks:
   - id: mypy
     additional_dependencies:
@@ -66,7 +66,7 @@ repos:
   - id: validate_manifest
 
 - repo: https://github.com/hadialqattan/pycln
-  rev: v2.3.0
+  rev: v2.4.0
   hooks:
   - id: pycln
     args: [--all]

README.md

@@ -61,12 +61,12 @@ Python.
 <!-- start integration status -->
 | | **PostgreSQL** | **MySQL** |
 | - |:--: | :-: |
+| 6.3.3  | ✅ | ✅ |
 | 6.3.1  | ✅ | ✅ |
 | 6.3.0  | ✅ | ✅ |
-| 6.2.11 | ✅ | ✅ |
+| 5.6.44 | ✅ | ✅ |
+| 5.6.43 | ✅ | ✅ |
 | 5.6.42 | ✅ | ✅ |
-| 5.6.41 | ✅ | ✅ |
-| 5.6.40 | ✅ | ✅ |
 <!-- end integration status -->
 
 ## Installation

pyproject.toml

@@ -83,11 +83,12 @@ target-version = "py38"
 [tool.ruff.lint]
 explicit-preview-rules = false
 ignore = [
-  "ANN101", # missing-type-self
-  "DJ",     # flake8-django
-  "FIX002", # line-contains-todo
+  "ANN101",  # missing-type-self
+  "DJ",      # flake8-django
+  "FIX002",  # line-contains-todo
   "COM812",  # missing-trailing-comma
   "ISC001",  # single-line-implicit-string-concatenation
+  "D107",    # undocumented-public-init
 ]
 preview = true
 select = [

src/citric/client.py

@@ -123,7 +123,6 @@ def __init__(
         requests_session: requests.Session | None = None,
         auth_plugin: str = "Authdb",
     ) -> None:
-        """Create a LimeSurvey Python API client."""
         self.__session = self.session_class(
             url,
             username,
@@ -169,20 +168,34 @@ def get_fieldmap(self, survey_id: int) -> dict[str, t.Any]:
         """
         return self.session.get_fieldmap(survey_id)
 
-    def activate_survey(self, survey_id: int) -> types.OperationStatus:
+    def activate_survey(
+        self,
+        survey_id: int,
+        *,
+        user_activation_settings: types.SurveyUserActivationSettings | None = None,
+    ) -> types.OperationStatus:
         """Activate a survey.
 
         Calls :rpc_method:`activate_survey`.
 
         Args:
             survey_id: ID of survey to be activated.
+            user_activation_settings: Optional user activation settings.
 
         Returns:
             Status and plugin feedback.
 
         .. versionadded:: 0.0.1
         """
-        return self.session.activate_survey(survey_id)
+        activation_settings = (
+            {
+                key: "Y" if value else "N"
+                for key, value in user_activation_settings.items()
+            }
+            if user_activation_settings
+            else None
+        )
+        return self.session.activate_survey(survey_id, activation_settings)
 
     def activate_tokens(
         self,

src/citric/exceptions.py

@@ -8,14 +8,13 @@ class ResponseMismatchError(Exception):
 
 
 class LimeSurveyError(Exception):
-    """Basic exception raised by LimeSurvey."""
+    """Basic exception raised by LimeSurvey.
 
-    def __init__(self, message: str) -> None:
-        """Create a generic error for the LimeSurvey RPC API.
+    Args:
+        message: Exception message. By default none, and a generic message is used.
+    """
 
-        Args:
-            message: Exception message. By default none, and a generic message is used.
-        """
+    def __init__(self, message: str) -> None:
         super().__init__(message)
 
 
@@ -31,15 +30,13 @@ class RPCInterfaceNotEnabledError(LimeSurveyError):
     """RPC interface not enabled on LimeSurvey."""
 
     def __init__(self) -> None:
-        """Create a new exception."""
         super().__init__("RPC interface not enabled")
 
 
 class InvalidJSONResponseError(LimeSurveyError):
     """RPC interface maybe not enabled on LimeSurvey."""
 
     def __init__(self) -> None:
-        """Create a new exception."""
         msg = (
             "Received a non-JSON response, verify that the JSON RPC interface is "
             "enabled in global settings"

src/citric/method.py

@@ -10,10 +10,14 @@
 
 
 class Method(t.Generic[T]):
-    """RPC method."""
+    """RPC method.
+
+    Args:
+        caller: RPC caller function.
+        name: RPC method name.
+    """
 
     def __init__(self, caller: t.Callable[[str], T], name: str) -> None:
-        """Instantiate an RPC method."""
         self.__caller = caller
         self.__name = name
 

src/citric/session.py

@@ -106,7 +106,6 @@ def __init__(
         requests_session: requests.Session | None = None,
         json_encoder: type[json.JSONEncoder] | None = None,
     ) -> None:
-        """Create a LimeSurvey RPC session."""
         self.url = url
         self._session = requests_session or requests.session()
         self._session.headers["User-Agent"] = self.USER_AGENT

src/citric/types.py

@@ -27,11 +27,12 @@
     "RPCResponse",
     "SetQuotaPropertiesResult",
     "SurveyProperties",
+    "SurveyUserActivationSettings",
     "CPDBParticipantImportResult",
 ]
 
 Result: TypeAlias = t.Any
-YesNo: TypeAlias = t.Literal["Y", "N"]
+YesNo: TypeAlias = t.Literal["Y", "N", "I"]
 
 
 class FileUploadResult(t.TypedDict):
@@ -495,3 +496,23 @@ class CPDBParticipantImportResult(t.TypedDict):
 
     ImportCount: int
     UpdateCount: int
+
+
+class SurveyUserActivationSettings(t.TypedDict, total=False):
+    """User settings for survey activation.
+
+    Keys:
+        anonymized: Whether the survey is anonymized.
+        datestamp: Whether the survey records dates.
+        ipaddr: Whether the survey records IP addresses.
+        ipanonymize: Whether the survey anonymizes IP addresses.
+        refurl: Whether the survey records referrer URLs.
+        savetimings: Whether the survey saves response timings.
+    """
+
+    anonymized: bool
+    datestamp: bool
+    ipaddr: bool
+    ipanonymize: bool
+    refurl: bool
+    savetimings: bool

tests/test_client.py

@@ -44,9 +44,6 @@ class MockSession(Session):
         "restrictToLanguages": "en fr es",
     }
 
-    def __init__(self, *args: t.Any, **kwargs: t.Any) -> None:
-        """Create a mock session."""
-
     def rpc(self, method: str, *params: t.Any) -> dict[str, t.Any]:
         """Process a mock RPC call."""
         return {"method": method, "params": [*params]}
@@ -197,7 +194,12 @@ def client() -> t.Generator[Client, None, None]:
 
 def test_activate_survey(client: MockClient):
     """Test activate_survey client method."""
-    assert_client_session_call(client, "activate_survey", 1)
+    assert_client_session_call(
+        client,
+        "activate_survey",
+        1,
+        user_activation_settings=None,
+    )
 
 
 def test_activate_tokens(client: MockClient):

tests/test_integration.py

@@ -197,7 +197,7 @@ def test_copy_survey_destination_id(
         pytest.mark.xfail(
             server_version < semver.VersionInfo.parse("6.4.0-dev"),
             reason=(
-                "The destination_survey_id parameter is only supported in LimeSurvey "
+                "The destination_survey_id parameter is not supported in LimeSurvey "
                 f"{server_version} < 6.4.0"
             ),
         ),
@@ -348,6 +348,51 @@ def test_activate_survey(client: citric.Client, survey_id: int):
     assert properties_after["active"] == "Y"
 
 
+@pytest.mark.integration_test
+def test_activate_survey_with_settings(
+    request: pytest.FixtureRequest,
+    client: citric.Client,
+    server_version: semver.VersionInfo,
+    survey_id: int,
+):
+    """Test whether the survey gets activated with the requested settings."""
+    min_version = (5, 6, 44) if server_version < (6, 0) else (6, 3, 5)
+    request.applymarker(
+        pytest.mark.xfail(
+            server_version < min_version,
+            reason=(
+                "The user_activation_settings parameter is not supported in LimeSurvey "
+                f"{server_version} < {'.'.join(str(v) for v in min_version)}"
+            ),
+        ),
+    )
+
+    properties_before = client.get_survey_properties(
+        survey_id,
+        ["active", "anonymized", "ipaddr"],
+    )
+    assert properties_before["active"] == "N"
+    assert properties_before["anonymized"] == "N"
+    assert properties_before["ipaddr"] == "I"
+
+    result = client.activate_survey(
+        survey_id,
+        user_activation_settings={
+            "anonymized": True,
+            "ipaddr": False,
+        },
+    )
+    assert result["status"] == "OK"
+
+    properties_after = client.get_survey_properties(
+        survey_id,
+        ["active", "anonymized", "ipaddr"],
+    )
+    assert properties_after["active"] == "Y"
+    assert properties_after["anonymized"] == "Y"
+    assert properties_after["ipaddr"] == "N"
+
+
 @pytest.mark.integration_test
 def test_activate_tokens(client: citric.Client, survey_id: int):
     """Test whether the participants table gets activated."""