From 35469d4c3f2b830f4cab48471ba5ad202f143400 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Fri, 4 Oct 2024 18:50:15 +0200 Subject: [PATCH 1/3] docs(storage): add docs to in memory (#1262) --- .../data_storage/in_memory_storage.py | 50 ++++++++++++++++--- openfisca_tasks/lint.mk | 1 + 2 files changed, 45 insertions(+), 6 deletions(-) diff --git a/openfisca_core/data_storage/in_memory_storage.py b/openfisca_core/data_storage/in_memory_storage.py index 8e238722d..e6a5a866c 100644 --- a/openfisca_core/data_storage/in_memory_storage.py +++ b/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 diff --git a/openfisca_tasks/lint.mk b/openfisca_tasks/lint.mk index 646cf76d7..912d0567d 100644 --- a/openfisca_tasks/lint.mk +++ b/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 \ ; From 3639902af12699703c30eca869357119cc7cd7bc Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Fri, 4 Oct 2024 20:23:37 +0200 Subject: [PATCH 2/3] docs(storage): add docs to on disk (#1262) --- .../data_storage/on_disk_storage.py | 72 ++++++++++++++++--- 1 file changed, 64 insertions(+), 8 deletions(-) diff --git a/openfisca_core/data_storage/on_disk_storage.py b/openfisca_core/data_storage/on_disk_storage.py index 1b2ec3108..4b4075613 100644 --- a/openfisca_core/data_storage/on_disk_storage.py +++ b/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 From c4fd16395db9db77904637c2f956cf6a52a50baa Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Fri, 4 Oct 2024 20:27:53 +0200 Subject: [PATCH 3/3] chore: version bump (fixes #1262) --- CHANGELOG.md | 6 ++++++ setup.py | 2 +- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cca131d3b..b58b1a74d 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/setup.py b/setup.py index 030c80cd3..1e4a46479 100644 --- a/setup.py +++ b/setup.py @@ -70,7 +70,7 @@ setup( name="OpenFisca-Core", - version="42.0.5", + version="42.0.6", author="OpenFisca Team", author_email="contact@openfisca.org", classifiers=[