feat(rpc): Added name and description parameters to import_group

.changes/unreleased/Added-20240528-231314.yaml

@@ -0,0 +1,5 @@
+kind: Added
+body: Added `name` and `description` parameters to `import_group`
+time: 2024-05-28T23:13:14.913661-06:00
+custom:
+ Issue: "1153"

.github/workflows/tests.yml

@@ -252,6 +252,11 @@ jobs:
  context: https://github.com/martialblog/docker-limesurvey.git#master:6.0/apache
  database: postgres
 
+ # - python-version: "3.12"
+ # ref: refs/pull/3860/head
+ # context: https://github.com/martialblog/docker-limesurvey.git#master:6.0/apache
+ # database: postgres
+
  steps:
  - name: Check out the repository
  uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4.2.1

src/citric/client.py

@@ -1231,30 +1231,42 @@ def import_group(
  file: t.IO[bytes],
  survey_id: int,
  file_type: str | enums.ImportGroupType = "lsg",
+ *,
+ name: str | None = None,
+ description: str | None = None,
  ) -> int:
  """Import group from a file.
 
  Create a new group from an exported LSG file.
 
- TODO: Check support for custom name and description.
-
  Calls :rpc_method:`import_group`.
 
  Args:
  file: File object.
  survey_id: The ID of the Survey that the question will belong to.
  file_type: Type of file. One of LSS, CSV, TXT and LSA.
+ name: Optional new name for the group.
+ description: Optional new description for the group.
 
  Returns:
  The ID of the new group.
 
+ .. code-block:: python
+
+ with open("group.lsg", "rb") as f:
+ group_id = client.import_group(f, survey_id)
+
  .. versionadded:: 0.0.10
+ .. versionchanged:: NEXT_VERSION
+ Added the ``name`` and ``description`` optional parameters.
  """
  contents = base64.b64encode(file.read()).decode()
  return self.session.import_group(
  survey_id,
  contents,
  enums.ImportGroupType(file_type),
+ name,
+ description,
  )
 
  def import_question(

tests/integration/test_rpc_client.py

@@ -211,44 +211,112 @@
 
 
 @pytest.mark.integration_test
-def test_group(client: citric.Client, survey_id: int):
+def test_group(client: citric.Client):
  """Test group methods."""
+ # Create a new survey
+ survey_id = client.add_survey(1234, "New Survey", "en")
+
  # Import a group
  with Path("./examples/group.lsg").open("rb") as f:
- group_id = client.import_group(f, survey_id)
+ imported_group = client.import_group(f, survey_id)
+
+ # Create a new group
+ created_group = client.add_group(
+ survey_id,
+ "Second Group",
+ description="A new group",
+ )
 
  # Get group properties
- group_props = client.get_group_properties(group_id)
- assert int(group_props["gid"]) == group_id
+ group_props = client.get_group_properties(imported_group)
+ assert int(group_props["gid"]) == imported_group
  assert int(group_props["sid"]) == survey_id
  assert group_props["group_name"] == "First Group"
  assert group_props["description"] == "<p>A new group</p>"
- assert int(group_props["group_order"]) == 3
+ assert int(group_props["group_order"]) == 1
+
+ group_props = client.get_group_properties(created_group)
+ assert int(group_props["gid"]) == created_group
+ assert int(group_props["sid"]) == survey_id
+ assert group_props["group_name"] == "Second Group"
+ assert group_props["description"] == "A new group"
+ assert int(group_props["group_order"]) == 2
 
  questions = sorted(
- client.list_questions(survey_id, group_id),
+ client.list_questions(survey_id, imported_group),
  key=operator.itemgetter("qid"),
  )
 
  assert questions[0]["question"] == "<p><strong>First question</p>"
  assert questions[1]["question"] == "<p><strong>Second question</p>"
 
  # Update group properties
- response = client.set_group_properties(group_id, group_order=1)
+ response = client.set_group_properties(imported_group, group_order=1)
  assert response == {"group_order": True}
 
- new_props = client.get_group_properties(group_id, settings=["group_order"])
- assert int(new_props["group_order"]) == 1
+ new_props = client.get_group_properties(imported_group, settings=["group_order"])
+ assert int(new_props["group_order"]) == 2
 
  with pytest.raises(LimeSurveyStatusError, match="Error: Invalid group ID"):
  client.set_group_properties(99999, group_order=1)
 
  # Delete group
- client.delete_group(survey_id, group_id)
+ client.delete_group(survey_id, imported_group)
  with pytest.raises(LimeSurveyStatusError, match="Error: Invalid group ID"):
  client.get_group_properties(survey_id)
 
 
+@pytest.mark.integration_test
+def test_import_group_with_name(
+ request: pytest.FixtureRequest,
+ client: citric.Client,
+ server_version: semver.VersionInfo,
+ survey_id: int,
+):
+ """Test importing a group with a custom name."""
+ request.applymarker(
+ pytest.mark.xfail(
+ server_version < semver.VersionInfo.parse("6.6.6"),
+ reason=(
+ f"The name override is broken in LimeSurvey {server_version} < 6.6.0"
+ ),
+ strict=True,
+ ),
+ )
+
+ with Path("./examples/group.lsg").open("rb") as f:
+ group_id = client.import_group(f, survey_id, name="Custom Name")
+
+ group_props = client.get_group_properties(group_id)
+ assert group_props["group_name"] == "Custom Name"
+
+
+@pytest.mark.integration_test
+def test_import_group_with_description(
+ request: pytest.FixtureRequest,
+ client: citric.Client,
+ server_version: semver.VersionInfo,
+ survey_id: int,
+):
+ """Test importing a group with a custom description."""
+ request.applymarker(
+ pytest.mark.xfail(
+ server_version < semver.VersionInfo.parse("6.6.6"),
+ reason=(
+ "The description override is broken in LimeSurvey "
+ f"{server_version} < 6.6.0"
+ ),
+ strict=True,
+ ),
+ )
+
+ with Path("./examples/group.lsg").open("rb") as f:
+ group_id = client.import_group(f, survey_id, description="Custom description")
+
+ group_props = client.get_group_properties(group_id)
+ assert group_props["description"] == "Custom description"
+
+
 @pytest.mark.integration_test
 def test_question(
  request: pytest.FixtureRequest,