Align the API and add better documentation. (#488)

Author: marcenacp

python/mlcroissant/mlcroissant/_src/datasets.py

@@ -39,12 +39,15 @@ class Dataset:
     """Python representation of a Croissant dataset.
 
     Args:
-        file: A JSON object or a path to a Croissant file (string or pathlib.Path).
-        operations: The operation graph class. None by default.
+        jsonld: A JSON object or a path to a Croissant file (URL, str or pathlib.Path).
         debug: Whether to print debug hints. False by default.
+        mapping: Mapping filename->filepath as a Python dict[str, str] to handle manual
+            downloads. If `document.csv` is the FileObject and you downloaded it to
+            `~/Downloads/document.csv`, you can specify `mapping={"document.csv":
+            "~/Downloads/document.csv"}`.,
     """
 
-    file: epath.PathLike | str | dict[str, Any] | None
+    jsonld: epath.PathLike | str | dict[str, Any] | None
     operations: OperationGraph = dataclasses.field(init=False)
     metadata: Metadata = dataclasses.field(init=False)
     debug: bool = False
@@ -54,10 +57,10 @@ def __post_init__(self):
         """Runs the static analysis of `file`."""
         ctx = Context()
         ctx.mapping = _expand_mapping(self.mapping)
-        if isinstance(self.file, dict):
-            self.metadata = Metadata.from_json(ctx=ctx, json_=self.file)
-        elif self.file is not None:
-            self.metadata = Metadata.from_file(ctx=ctx, file=self.file)
+        if isinstance(self.jsonld, dict):
+            self.metadata = Metadata.from_json(ctx=ctx, json_=self.jsonld)
+        elif self.jsonld is not None:
+            self.metadata = Metadata.from_file(ctx=ctx, file=self.jsonld)
         else:
             return
         # Draw the structure graph for debugging purposes.
@@ -71,7 +74,7 @@ def __post_init__(self):
     @classmethod
     def from_metadata(cls, metadata: Metadata) -> Dataset:
         """Creates a new `Dataset` from a `Metadata`."""
-        dataset = Dataset(file=None)
+        dataset = Dataset(jsonld=None)
         dataset.metadata = metadata
         dataset.operations = get_operations(metadata.ctx, metadata)
         return dataset

python/mlcroissant/mlcroissant/_src/torch/torch_adapter/dataloader.py

@@ -55,9 +55,9 @@ def apply_data_type_transformation(
 class LoaderFactory:
     """Used to create loaders and get metadata."""
 
-    def __init__(self, file: str):
+    def __init__(self, jsonld: str):
         """Initialize LoaderFactory with a Croissant file."""
-        self.file = file
+        self.jsonld = jsonld
 
     def _get_row_processor(self, specification: LoaderSpecificationTypes):
         """Remap columns types to desired type."""
@@ -78,7 +78,7 @@ def as_datapipe(
         if dp is None:
             raise NotImplementedError(INSTALL_MESSAGE)
 
-        dataset = Dataset(file=self.file)
+        dataset = Dataset(jsonld=self.jsonld)
         records = dataset.records(record_set=record_set)
         datapipe = dp.iter.IterableWrapper(records)
         if specification:

python/mlcroissant/recipes/PyTorch_FLORES200.ipynb

@@ -100,7 +100,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "ta_factory = mlc.torch.LoaderFactory(file=\"../../../datasets/flores-200/metadata.json\")\n",
+    "ta_factory = mlc.torch.LoaderFactory(jsonld=\"../../../datasets/flores-200/metadata.json\")\n",
     "specification = {\n",
     "    \"translation\": mlc.torch.LoaderSpecificationDataType.INFER,\n",
     "    \"language\": mlc.torch.LoaderSpecificationDataType.INFER,\n",

python/mlcroissant/recipes/bounding-boxes.ipynb

@@ -123,8 +123,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "file = epath.Path(\"croissant.json\")\n",
-    "with file.open(\"w\") as f:\n",
+    "jsonld = epath.Path(\"croissant.json\")\n",
+    "with jsonld.open(\"w\") as f:\n",
     "    f.write(json.dumps(metadata.to_json(), indent=2))\n",
     "\n",
     "!grep -C 7 -n \"cr:BoundingBox\" croissant.json"
@@ -147,7 +147,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "dataset = mlc.Dataset(file=file)\n",
+    "dataset = mlc.Dataset(jsonld=jsonld)\n",
     "records = dataset.records(record_set=record_set)\n",
     "record = next(iter(records))\n",
     "print(\"The first record:\")\n",

python/mlcroissant/recipes/introduction.ipynb

@@ -274,7 +274,7 @@
     {
       "cell_type": "code",
       "source": [
-        "dataset = mlc.Dataset(file=\"croissant.json\")"
+        "dataset = mlc.Dataset(jsonld=\"croissant.json\")"
       ],
       "metadata": {
         "id": "_JNyQFuAEiIs"