Repository: aeye-lab/pymovements
Pull request #1121 (2025-04-24 18:23:42)

feat: make `DatasetDefinition.long_name` optional
## Description

Make `DatasetDefinition.long_name` optional and use `DatasetDefinition.name` in disclaimer in case `DatasetDefinition.long_name` is `None`.

## Implemented changes

- [x] move disclaimer to `Dataset._disclaimer()` and log in `Dataset.download()`
- [x] change attribute to `Dataset.long_name: str | None = None`

## How Has This Been Tested?

No additional tests written. I should probably write at least two tests.

## Type of change

- New functionality

## Checklist:

- [x] My code follows the style guidelines of this project
- [x] I have performed a self-review of my own code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my feature works
- [x] New and existing unit tests pass locally with my changes
- [x] Any dependent changes have been merged and published in downstream modules
- [x] I have checked my code and corrected any misspellings


codecov[bot]: ## [Codecov](https://app.codecov.io/gh/aeye-lab/pymovements/pull/1121?dropdown=coverage&src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=aeye-lab) Report
All modified and coverable lines are covered by tests :white_check_mark:
> Project coverage is 99.94%. Comparing base [(`a0b89ae`)](https://app.codecov.io/gh/aeye-lab/pymovements/commit/a0b89ae3ba4579059cd81465e9cc7aede993029a?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=aeye-lab) to head [(`a9856e6`)](https://app.codecov.io/gh/aeye-lab/pymovements/commit/a9856e68b94ebe73a134ae01086aeeb99beebf96?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=aeye-lab).

<details><summary>Additional details and impacted files</summary>


```diff
@@             Coverage Diff             @@
##              main    #1121      +/-   ##
===========================================
- Coverage   100.00%   99.94%   -0.06%     
===========================================
  Files           87       87              
  Lines         3797     3800       +3     
  Branches       657      658       +1     
===========================================
+ Hits          3797     3798       +1     
- Misses           0        1       +1     
- Partials         0        1       +1     
```

</details>

[:umbrella: View full report in Codecov by Sentry](https://app.codecov.io/gh/aeye-lab/pymovements/pull/1121?dropdown=coverage&src=pr&el=continue&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=aeye-lab).   
:loudspeaker: Have feedback on the report? [Share it here](https://about.codecov.io/codecov-pr-comment-feedback/?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=aeye-lab).

<details><summary> :rocket: New features to boost your workflow: </summary>

- :snowflake: [Test Analytics](https://docs.codecov.com/docs/test-analytics): Detect flaky tests, report on failures, and find test suite problems.
</details>

Patch:
diff --git a/src/pymovements/dataset/dataset.py b/src/pymovements/dataset/dataset.py
index 5619cc6..66e8b02 100644
--- a/src/pymovements/dataset/dataset.py
+++ b/src/pymovements/dataset/dataset.py
@@ -20,6 +20,7 @@
 """Provides the Dataset class."""
 from __future__ import annotations
 
+import logging
 from collections.abc import Callable
 from collections.abc import Sequence
 from copy import deepcopy
@@ -40,6 +41,10 @@ from pymovements.gaze import GazeDataFrame
 from pymovements.reading_measures import ReadingMeasures
 
 
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
 class Dataset:
     """Dataset base class.
 
@@ -998,6 +1003,8 @@ class Dataset:
         RuntimeError
             If downloading a resource failed for all given mirrors.
         """
+        logger.info(self._disclaimer())
+
         dataset_download.download_dataset(
             definition=self.definition,
             paths=self.paths,
@@ -1100,3 +1107,18 @@ class Dataset:
             raise AttributeError('gaze files were not loaded yet. please run load() beforehand')
         if len(self.gaze) == 0:
             raise AttributeError('no files present in gaze attribute')
+
+    def _disclaimer(self) -> str:
+        """Return string for dataset download disclaimer."""
+        if self.definition.long_name is not None:
+            dataset_name = self.definition.long_name
+        else:
+            dataset_name = self.definition.name + ' dataset'
+
+        return f"""\
+        You are downloading the {dataset_name}. Please be aware that pymovements does not
+        host or distribute any dataset resources and only provides a convenient interface to
+        download the public dataset resources that were published by their respective authors.
+
+        Please cite the referenced publication if you intend to use the dataset in your research.
+        """
diff --git a/src/pymovements/dataset/dataset_definition.py b/src/pymovements/dataset/dataset_definition.py
index e815e04..54a45cc 100644
--- a/src/pymovements/dataset/dataset_definition.py
+++ b/src/pymovements/dataset/dataset_definition.py
@@ -47,8 +47,8 @@ class DatasetDefinition:
     ----------
     name: str
         The name of the dataset. (default: '.')
-    long_name: str
-        The entire name of the dataset. (default: '.')
+    long_name: str | None
+        The entire name of the dataset. (default: None)
     has_files: dict[str, bool]
         Indicate whether the dataset contains 'gaze', 'precomputed_events', and
         'precomputed_reading_measures'.
@@ -145,7 +145,7 @@ class DatasetDefinition:
     # pylint: disable=too-many-instance-attributes
     name: str = '.'
 
-    long_name: str = '.'
+    long_name: str | None = None
 
     has_files: dict[str, bool] = field(default_factory=dict)
 
diff --git a/src/pymovements/dataset/dataset_download.py b/src/pymovements/dataset/dataset_download.py
index c078787..e80696d 100644
--- a/src/pymovements/dataset/dataset_download.py
+++ b/src/pymovements/dataset/dataset_download.py
@@ -20,7 +20,6 @@
 """Provides private functions for downloading and extracting datasets."""
 from __future__ import annotations
 
-import logging
 import shutil
 from pathlib import Path
 from urllib.error import URLError
@@ -32,10 +31,6 @@ from pymovements.dataset.dataset_definition import DatasetDefinition
 from pymovements.dataset.dataset_paths import DatasetPaths
 
 
-logging.basicConfig(level=logging.INFO)
-logger = logging.getLogger(__name__)
-
-
 def download_dataset(
         definition: DatasetDefinition,
         paths: DatasetPaths,
@@ -82,15 +77,6 @@ def download_dataset(
     RuntimeError
         If downloading a resource failed for all given mirrors.
     """
-    disclaimer_text = f"""\
-You are downloading the {definition.long_name}. Please be aware that pymovements does not
-host or distribute any dataset resources and only provides a convenient interface to
-download the public dataset resources that were published by their respective authors.
-
-Please cite the referenced publication if you intend to use the dataset in your research.
-"""
-    logger.info(disclaimer_text)
-
     if definition.has_files['gaze']:
         if not definition.mirrors or not definition.mirrors['gaze']:
             mirrors = None


Test patch:
diff --git a/tests/unit/dataset/dataset_definition_test.py b/tests/unit/dataset/dataset_definition_test.py
index 64236ee..e501bb5 100644
--- a/tests/unit/dataset/dataset_definition_test.py
+++ b/tests/unit/dataset/dataset_definition_test.py
@@ -183,7 +183,7 @@ def test_dataset_definition_to_dict_expected(definition, expected_dict):
             True,
             {
                 'name': 'MyDatasetDefinition',
-                'long_name': '.',
+                'long_name': None,
                 'has_files': {},
                 'acceleration_columns': None,
                 'column_map': {},
@@ -227,7 +227,7 @@ def test_dataset_definition_to_dict_expected(definition, expected_dict):
             False,
             {
                 'name': 'MyDatasetDefinition',
-                'long_name': '.',
+                'long_name': None,
                 '_foobar': 'test',
                 'has_files': {},
                 'acceleration_columns': None,