docs(storage): fix data_storage docs (#1263)

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+### 42.0.6 [#1263](https://github.com/openfisca/openfisca-core/pull/1263)
+
+#### Documentation
+
+- Fix docs of the `data_storage` module
+
 ### 42.0.5 [#1261](https://github.com/openfisca/openfisca-core/pull/1261)
 
 #### Technical changes

openfisca_core/data_storage/in_memory_storage.py

@@ -5,14 +5,32 @@
 
 
 class InMemoryStorage:
-    """Storing and retrieving calculated vectors in memory."""
+    """Storing and retrieving calculated vectors in memory.
+
+    Args:
+        is_eternal: Whether the storage is eternal.
+
+    """
+
+    #: Whether the storage is eternal.
+    is_eternal: bool
+
+    #: A dictionary containing data that has been stored in memory.
+    _arrays: dict
 
     def __init__(self, is_eternal=False) -> None:
         self._arrays = {}
         self.is_eternal = is_eternal
 
     def get(self, period):
-        """
+        """Retrieve the data for the specified period from memory.
+
+        Args:
+            period: The period for which data should be retrieved.
+
+        Returns:
+            The data for the specified period, or None if no data is available.
+
         Examples:
             >>> import numpy
 
@@ -40,7 +58,12 @@ def get(self, period):
         return values
 
     def put(self, value, period) -> None:
-        """
+        """Store the specified data in memory for the specified period.
+
+        Args:
+            value: The data to store
+            period: The period for which the data should be stored.
+
         Examples:
             >>> import numpy
 
@@ -65,7 +88,14 @@ def put(self, value, period) -> None:
         self._arrays[period] = value
 
     def delete(self, period=None) -> None:
-        """
+        """Delete the data for the specified period from memory.
+
+        Args:
+            period: The period for which data should be deleted.
+
+        Note:
+            If ``period`` is specified, all data will be deleted.
+
         Examples:
             >>> import numpy
 
@@ -108,7 +138,11 @@ def delete(self, period=None) -> None:
         }
 
     def get_known_periods(self):
-        """
+        """List of storage's known periods.
+
+        Returns:
+            A sequence containing the storage's known periods.
+
         Examples:
             >>> from openfisca_core import data_storage, periods
 
@@ -128,7 +162,11 @@ def get_known_periods(self):
         return self._arrays.keys()
 
     def get_memory_usage(self):
-        """
+        """Memory usage of the storage.
+
+        Returns:
+            A dictionary representing the storage's memory usage.
+
         Examples:
             >>> from openfisca_core import data_storage
 

openfisca_core/data_storage/on_disk_storage.py

@@ -9,7 +9,29 @@
 
 
 class OnDiskStorage:
-    """Storing and retrieving calculated vectors on disk."""
+    """Storing and retrieving calculated vectors on disk.
+
+    Args:
+        storage_dir: Path to store calculated vectors.
+        is_eternal: Whether the storage is eternal.
+        preserve_storage_dir: Whether to preserve the storage directory.
+
+    """
+
+    #: A dictionary containing data that has been stored on disk.
+    storage_dir: str
+
+    #: Whether the storage is eternal.
+    is_eternal: bool
+
+    #: Whether to preserve the storage directory.
+    preserve_storage_dir: bool
+
+    #: Mapping of file paths to possible Enum values.
+    _enums: dict
+
+    #: Mapping of periods to file paths.
+    _files: dict
 
     def __init__(
         self, storage_dir, is_eternal=False, preserve_storage_dir=False
@@ -21,8 +43,19 @@ def __init__(
         self.storage_dir = storage_dir
 
     def _decode_file(self, file):
-        """
-        Examples
+        """Decode a file by loading its contents as a ``numpy`` array.
+
+        Args:
+            file: Path to the file to be decoded.
+
+        Returns:
+            ``numpy`` array or ``EnumArray`` representing the data in the file.
+
+        Note:
+            If the file is associated with ``Enum`` values, the array is
+            converted back to an ``EnumArray`` object.
+
+        Examples:
             >>> import tempfile
 
             >>> import numpy
@@ -54,7 +87,15 @@ def _decode_file(self, file):
         return numpy.load(file)
 
     def get(self, period):
-        """
+        """Retrieve the data for the specified period from disk.
+
+        Args:
+            period: The period for which data should be retrieved.
+
+        Returns:
+            A ``numpy`` array or ``EnumArray`` representing the vector for the
+            specified period, or ``None`` if no vector is stored.
+
         Examples:
             >>> import tempfile
 
@@ -84,7 +125,12 @@ def get(self, period):
         return self._decode_file(values)
 
     def put(self, value, period) -> None:
-        """
+        """Store the specified data on disk for the specified period.
+
+        Args:
+            value: The data to store
+            period: The period for which the data should be stored.
+
         Examples:
             >>> import tempfile
 
@@ -117,7 +163,12 @@ def put(self, value, period) -> None:
         self._files[period] = path
 
     def delete(self, period=None) -> None:
-        """
+        """Delete the data for the specified period from disk.
+
+        Args:
+            period: The period for which data should be deleted. If not
+                specified, all data will be deleted.
+
         Examples:
             >>> import tempfile
 
@@ -165,7 +216,11 @@ def delete(self, period=None) -> None:
             }
 
     def get_known_periods(self):
-        """
+        """List of storage's known periods.
+
+        Returns:
+            A sequence containing the storage's known periods.
+
         Examples:
             >>> import tempfile
 
@@ -192,7 +247,8 @@ def get_known_periods(self):
         return self._files.keys()
 
     def restore(self) -> None:
-        """
+        """Restore the storage from disk.
+
         Examples:
             >>> import tempfile
 

openfisca_tasks/lint.mk

@@ -19,6 +19,7 @@ check-style: $(shell git ls-files "*.py" "*.pyi")
 ## Run linters to check for syntax and style errors in the doc.
 lint-doc: \
 	lint-doc-commons \
+	lint-doc-data_storage \
 	lint-doc-entities \
 	;
 

setup.py

@@ -70,7 +70,7 @@
 
 setup(
     name="OpenFisca-Core",
-    version="42.0.5",
+    version="42.0.6",
     author="OpenFisca Team",
     author_email="[email protected]",
     classifiers=[