feat: improve Dataset API ergonomics and document new patterns

Add Dataset.data_path class property as shortcut for __dataset__.datapath,
make reference() accept dataset class as first positional arg, and add
reference.config() alias for prepare(). Update documentation accordingly.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: bpiwowar

docs/source/datasets.rst

@@ -72,6 +72,28 @@ Advantages of class-based definitions:
 3. **Auto-naming** --- resource names are auto-detected from class attribute names
 4. **Two-path safety** --- incomplete downloads never appear at the final path
 
+Dataset Utilities
+-----------------
+
+``Dataset.data_path``
+    A class property that returns the ``Path`` where this dataset's data is
+    stored on disk. This is a shortcut for ``MyDataset.__dataset__.datapath``:
+
+    .. code-block:: python
+
+        @dataset(url="http://example.com")
+        class Documents(Dataset):
+            ...
+
+        @dataset(url="http://example.com")
+        class MyTask(Dataset):
+            DOCS = reference(Documents)
+
+            def config(self) -> TaskData:
+                # Use Documents.data_path to locate sibling data
+                store_path = Documents.data_path / "docstore"
+                return TaskData.C(path=store_path)
+
 Resource Pipelines
 ------------------
 
@@ -221,10 +243,40 @@ HuggingFace Integration
     class Squad(QADataset):
         HF_DATA = HFDownloader("squad_data", "squad")
 
-Links to Other Datasets
-------------------------
+Referencing Other Datasets
+--------------------------
+
+Use :py:class:`~datamaestro.download.reference` to declare a dependency on
+another dataset class. The referenced dataset is prepared automatically when
+needed:
+
+.. code-block:: python
+
+    from datamaestro.download import reference
+
+    @dataset(url="http://example.com")
+    class MyTask(TaskData):
+        DOCUMENTS = reference(DocumentsDataset)
+
+        def config(self) -> TaskData:
+            return TaskData.C(
+                documents=self.DOCUMENTS.config(),
+            )
+
+Call ``.config()`` on the reference resource to obtain the referenced dataset's
+configuration object (this is equivalent to ``.prepare()``).
+
+.. note::
+
+    ``reference()`` accepts the dataset class as its first positional argument.
+    The older keyword form ``reference(reference=DocumentsDataset)`` still works
+    but is no longer necessary.
+
+Links to Other Datasets (by ID)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Use :py:func:`~datamaestro.download.links.links` to reference other datasets:
+Use :py:func:`~datamaestro.download.links.links` to reference datasets by their
+string ID rather than by class:
 
 .. code-block:: python
 

src/datamaestro/definitions.py

@@ -949,6 +949,10 @@ def config(self) -> ImageClassification:
                     train=IDX(path=self.TRAIN_IMAGES.path),
                     test=IDX(path=self.TEST_IMAGES.path),
                 )
+
+    Class-level convenience properties:
+
+    - ``MyDataset.data_path`` — shortcut for ``MyDataset.__dataset__.datapath``
     """
 
     @abstractmethod
@@ -964,6 +968,32 @@ def config(self) -> "Base":
         """
         ...
 
+    class _DataPath:
+        """Descriptor that provides ``Dataset.data_path`` as a class property.
+
+        Returns the ``datapath`` of the dataset wrapper (``__dataset__``),
+        which is the directory where downloaded data is stored.
+        """
+
+        def __set_name__(self, owner, name):
+            self.name = name
+
+        def __get__(self, obj, objtype=None):
+            cls = objtype if objtype is not None else type(obj)
+            dw = getattr(cls, "__dataset__", None)
+            if dw is None:
+                raise AttributeError(
+                    f"{cls.__name__} has no __dataset__; "
+                    "is the @dataset decorator applied?"
+                )
+            return dw.datapath
+
+    data_path: Path = _DataPath()
+    """Path to the directory where this dataset's downloaded data is stored.
+
+    Shortcut for ``MyDataset.__dataset__.datapath``.
+    """
+
 
 class metadataset(AbstractDataset):
     """Annotation for object/functions which are abstract dataset definitions

src/datamaestro/download/__init__.py

@@ -675,13 +675,32 @@ def __init_subclass__(cls):
 
 
 class reference(Resource):
-    """References another dataset instead of downloading."""
+    """References another dataset instead of downloading.
 
-    def __init__(self, varname=None, reference=None):
+    Usage::
+
+        # Positional form (preferred):
+        DOCS = reference(Documents)
+
+        # Keyword form:
+        DOCS = reference(reference=Documents)
+
+        # With explicit varname (rarely needed — auto-set from attribute name):
+        DOCS = reference(Documents, varname="docs")
+
+    In the ``config()`` method, call ``.config()`` (or ``.prepare()``)
+    to obtain the referenced dataset's prepared configuration::
+
+        def config(self) -> Adhoc:
+            return Adhoc.C(documents=self.DOCS.config())
+    """
+
+    def __init__(self, reference=None, *, varname=None):
         """
         Args:
-            varname: The name of the variable.
-            reference: Another dataset to reference.
+            reference: The dataset class (or wrapper) to reference.
+            varname: Explicit resource name (auto-set from class attribute
+                name if omitted).
         """
         super().__init__(varname=varname)
         assert reference is not None, "Reference cannot be null"
@@ -691,7 +710,7 @@ def _resolve_reference(self):
         """Resolve the reference to a DatasetWrapper.
 
         For class-based datasets, the reference is the class itself with
-        a __dataset__ attribute pointing to the DatasetWrapper.
+        a ``__dataset__`` attribute pointing to the DatasetWrapper.
         For function-based datasets, the reference is already a DatasetWrapper.
         """
         ref = self.reference
@@ -700,11 +719,32 @@ def _resolve_reference(self):
         return ref
 
     def prepare(self):
+        """Return the referenced dataset's prepared configuration.
+
+        Resolves the reference and calls the target dataset's
+        ``config()`` method (via ``_prepare()``).
+
+        Returns:
+            A Config instance — the result of the referenced dataset's
+            ``config()`` method.
+        """
         resolved = self._resolve_reference()
         if isinstance(resolved, AbstractDataset):
             return resolved._prepare()
         return resolved.prepare()
 
+    def config(self):
+        """Alias for :meth:`prepare` — returns the referenced dataset's config.
+
+        Preferred over ``prepare()`` for readability when used with
+        ``reference`` resources, since the return value is a configuration
+        object (not a file path)::
+
+            def config(self) -> Adhoc:
+                return Adhoc.C(documents=self.DOCS.config())
+        """
+        return self.prepare()
+
     def download(self, force=False):
         resolved = self._resolve_reference()
         if isinstance(resolved, AbstractDataset):