From df69d4cbbaa7cc995f99bfc7def6079d03ac4808 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Fri, 11 Oct 2024 01:18:22 +0200 Subject: [PATCH] docs(exp): add docs to experimental (#1274) --- CHANGELOG.md | 2 +- openfisca_core/__init__.py | 36 ++++++++++++++++ openfisca_core/experimental/__init__.py | 31 ++++---------- .../_errors.py} | 3 ++ openfisca_core/experimental/_memory_config.py | 42 +++++++++++++++++++ openfisca_core/experimental/memory_config.py | 28 ------------- openfisca_core/formula_helpers.py | 9 ---- openfisca_core/memory_config.py | 9 ---- openfisca_core/rates.py | 9 ---- openfisca_core/simulation_builder.py | 16 ------- openfisca_core/tools/test_runner.py | 2 +- openfisca_core/warnings/__init__.py | 1 - openfisca_tasks/lint.mk | 2 + openfisca_tasks/test_code.mk | 1 + openfisca_web_api/handlers.py | 2 +- setup.cfg | 2 + tests/core/test_holders.py | 2 +- tests/core/variables/test_variables.py | 2 +- 18 files changed, 99 insertions(+), 100 deletions(-) rename openfisca_core/{warnings/memory_warning.py => experimental/_errors.py} (69%) create mode 100644 openfisca_core/experimental/_memory_config.py delete mode 100644 openfisca_core/experimental/memory_config.py delete mode 100644 openfisca_core/formula_helpers.py delete mode 100644 openfisca_core/memory_config.py delete mode 100644 openfisca_core/rates.py delete mode 100644 openfisca_core/simulation_builder.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 96ceee5b0d..aa6de8956d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2564,7 +2564,7 @@ Add `--only-variables` and `--ignore-variables` options to `openfisca-run-test` For instance: ``` -from openfisca_core.memory_config import MemoryConfig +from openfisca_core.experimental import MemoryConfig simulation = ... # create a Simulation object diff --git a/openfisca_core/__init__.py b/openfisca_core/__init__.py index e69de29bb2..cea2665243 100644 --- a/openfisca_core/__init__.py +++ b/openfisca_core/__init__.py @@ -0,0 +1,36 @@ +"""The most widely adopted free and open-source engine to write rules as code.""" + +from openfisca_core.commons import ( + apply_thresholds, + average_rate, + concat, + marginal_rate, + switch, +) + +from . import types +from .experimental import MemoryConfig +from .simulations import ( + Simulation, + SimulationBuilder, + calculate_output_add, + calculate_output_divide, + check_type, + transform_to_strict_syntax, +) + +__all__ = [ + "MemoryConfig", + "Simulation", + "SimulationBuilder", + "apply_thresholds", + "average_rate", + "calculate_output_add", + "calculate_output_divide", + "check_type", + "concat", + "marginal_rate", + "switch", + "transform_to_strict_syntax", + "types", +] diff --git a/openfisca_core/experimental/__init__.py b/openfisca_core/experimental/__init__.py index 83faabe2bb..07114cdd27 100644 --- a/openfisca_core/experimental/__init__.py +++ b/openfisca_core/experimental/__init__.py @@ -1,24 +1,9 @@ -# Transitional imports to ensure non-breaking changes. -# Could be deprecated in the next major release. -# -# How imports are being used today: -# -# >>> from openfisca_core.module import symbol -# -# The previous example provokes cyclic dependency problems -# that prevent us from modularizing the different components -# of the library so to make them easier to test and to maintain. -# -# How could them be used after the next major release: -# -# >>> from openfisca_core import module -# >>> module.symbol() -# -# And for classes: -# -# >>> from openfisca_core.module import Symbol -# >>> Symbol() -# -# See: https://www.python.org/dev/peps/pep-0008/#imports +"""Experimental features of OpenFisca-Core.""" -from .memory_config import MemoryConfig # noqa: F401 +from ._errors import MemoryConfigWarning +from ._memory_config import MemoryConfig + +__all__ = [ + "MemoryConfig", + "MemoryConfigWarning", +] diff --git a/openfisca_core/warnings/memory_warning.py b/openfisca_core/experimental/_errors.py similarity index 69% rename from openfisca_core/warnings/memory_warning.py rename to openfisca_core/experimental/_errors.py index 23e82bf3e0..6957e36c26 100644 --- a/openfisca_core/warnings/memory_warning.py +++ b/openfisca_core/experimental/_errors.py @@ -1,2 +1,5 @@ class MemoryConfigWarning(UserWarning): """Custom warning for MemoryConfig.""" + + +__all__ = ["MemoryConfigWarning"] diff --git a/openfisca_core/experimental/_memory_config.py b/openfisca_core/experimental/_memory_config.py new file mode 100644 index 0000000000..6fba790e90 --- /dev/null +++ b/openfisca_core/experimental/_memory_config.py @@ -0,0 +1,42 @@ +from __future__ import annotations + +from collections.abc import Iterable + +import warnings + +from ._errors import MemoryConfigWarning + + +class MemoryConfig: + """Experimental memory configuration.""" + + #: Maximum memory occupation allowed. + max_memory_occupation: float + + #: Priority variables. + priority_variables: frozenset[str] + + #: Variables to drop. + variables_to_drop: frozenset[str] + + def __init__( + self, + max_memory_occupation: str | float, + priority_variables: Iterable[str] = frozenset(), + variables_to_drop: Iterable[str] = frozenset(), + ) -> None: + message = [ + "Memory configuration is a feature that is still currently under " + "experimentation. You are very welcome to use it and send us " + "precious feedback, but keep in mind that the way it is used might " + "change without any major version bump.", + ] + warnings.warn(" ".join(message), MemoryConfigWarning, stacklevel=2) + + self.max_memory_occupation = float(max_memory_occupation) + if self.max_memory_occupation > 1: + msg = "max_memory_occupation must be <= 1" + raise ValueError(msg) + self.max_memory_occupation_pc = self.max_memory_occupation * 100 + self.priority_variables = frozenset(priority_variables) + self.variables_to_drop = frozenset(variables_to_drop) diff --git a/openfisca_core/experimental/memory_config.py b/openfisca_core/experimental/memory_config.py deleted file mode 100644 index fec38e3a54..0000000000 --- a/openfisca_core/experimental/memory_config.py +++ /dev/null @@ -1,28 +0,0 @@ -import warnings - -from openfisca_core.warnings import MemoryConfigWarning - - -class MemoryConfig: - def __init__( - self, - max_memory_occupation, - priority_variables=None, - variables_to_drop=None, - ) -> None: - message = [ - "Memory configuration is a feature that is still currently under experimentation.", - "You are very welcome to use it and send us precious feedback,", - "but keep in mind that the way it is used might change without any major version bump.", - ] - warnings.warn(" ".join(message), MemoryConfigWarning, stacklevel=2) - - self.max_memory_occupation = float(max_memory_occupation) - if self.max_memory_occupation > 1: - msg = "max_memory_occupation must be <= 1" - raise ValueError(msg) - self.max_memory_occupation_pc = self.max_memory_occupation * 100 - self.priority_variables = ( - set(priority_variables) if priority_variables else set() - ) - self.variables_to_drop = set(variables_to_drop) if variables_to_drop else set() diff --git a/openfisca_core/formula_helpers.py b/openfisca_core/formula_helpers.py deleted file mode 100644 index e0c755348e..0000000000 --- a/openfisca_core/formula_helpers.py +++ /dev/null @@ -1,9 +0,0 @@ -# The formula_helpers module has been deprecated since X.X.X, -# and will be removed in the future. -# -# The helpers have been moved to the commons module. -# -# The following are transitional imports to ensure non-breaking changes. -# Could be deprecated in the next major release. - -from openfisca_core.commons import apply_thresholds, concat, switch # noqa: F401 diff --git a/openfisca_core/memory_config.py b/openfisca_core/memory_config.py deleted file mode 100644 index 18c4cebcdc..0000000000 --- a/openfisca_core/memory_config.py +++ /dev/null @@ -1,9 +0,0 @@ -# The memory config module has been deprecated since X.X.X, -# and will be removed in the future. -# -# Module's contents have been moved to the experimental module. -# -# The following are transitional imports to ensure non-breaking changes. -# Could be deprecated in the next major release. - -from openfisca_core.experimental import MemoryConfig # noqa: F401 diff --git a/openfisca_core/rates.py b/openfisca_core/rates.py deleted file mode 100644 index 9dfbbefcf0..0000000000 --- a/openfisca_core/rates.py +++ /dev/null @@ -1,9 +0,0 @@ -# The formula_helpers module has been deprecated since X.X.X, -# and will be removed in the future. -# -# The helpers have been moved to the commons module. -# -# The following are transitional imports to ensure non-breaking changes. -# Could be deprecated in the next major release. - -from openfisca_core.commons import average_rate, marginal_rate # noqa: F401 diff --git a/openfisca_core/simulation_builder.py b/openfisca_core/simulation_builder.py deleted file mode 100644 index 189bba3bcb..0000000000 --- a/openfisca_core/simulation_builder.py +++ /dev/null @@ -1,16 +0,0 @@ -# The simulation builder module has been deprecated since X.X.X, -# and will be removed in the future. -# -# Module's contents have been moved to the simulation module. -# -# The following are transitional imports to ensure non-breaking changes. -# Could be deprecated in the next major release. - -from openfisca_core.simulations import ( # noqa: F401 - Simulation, - SimulationBuilder, - calculate_output_add, - calculate_output_divide, - check_type, - transform_to_strict_syntax, -) diff --git a/openfisca_core/tools/test_runner.py b/openfisca_core/tools/test_runner.py index fcb5572b79..1f7b603b6a 100644 --- a/openfisca_core/tools/test_runner.py +++ b/openfisca_core/tools/test_runner.py @@ -17,7 +17,7 @@ import pytest from openfisca_core.errors import SituationParsingError, VariableNotFound -from openfisca_core.simulation_builder import SimulationBuilder +from openfisca_core.simulations import SimulationBuilder from openfisca_core.tools import assert_near from openfisca_core.warnings import LibYAMLWarning diff --git a/openfisca_core/warnings/__init__.py b/openfisca_core/warnings/__init__.py index 9e450c8702..3397fb52de 100644 --- a/openfisca_core/warnings/__init__.py +++ b/openfisca_core/warnings/__init__.py @@ -22,5 +22,4 @@ # See: https://www.python.org/dev/peps/pep-0008/#imports from .libyaml_warning import LibYAMLWarning # noqa: F401 -from .memory_warning import MemoryConfigWarning # noqa: F401 from .tempfile_warning import TempfileWarning # noqa: F401 diff --git a/openfisca_tasks/lint.mk b/openfisca_tasks/lint.mk index f5fdbc7ce9..4c3e8869d0 100644 --- a/openfisca_tasks/lint.mk +++ b/openfisca_tasks/lint.mk @@ -21,6 +21,7 @@ lint-doc: \ lint-doc-commons \ lint-doc-data_storage \ lint-doc-entities \ + lint-doc-experimental \ lint-doc-indexed_enums \ ; @@ -43,6 +44,7 @@ check-types: @python -m mypy \ openfisca_core/commons \ openfisca_core/data_storage \ + openfisca_core/experimental \ openfisca_core/entities \ openfisca_core/periods \ openfisca_core/types.py diff --git a/openfisca_tasks/test_code.mk b/openfisca_tasks/test_code.mk index 6a27f1b9cb..4f8f843c97 100644 --- a/openfisca_tasks/test_code.mk +++ b/openfisca_tasks/test_code.mk @@ -38,6 +38,7 @@ test-core: $(shell git ls-files "*test_*.py") @python -m pytest --capture=no \ openfisca_core/commons \ openfisca_core/data_storage \ + openfisca_core/experimental \ openfisca_core/entities \ openfisca_core/holders \ openfisca_core/indexed_enums \ diff --git a/openfisca_web_api/handlers.py b/openfisca_web_api/handlers.py index 2f6fc4403a..59d035eb57 100644 --- a/openfisca_web_api/handlers.py +++ b/openfisca_web_api/handlers.py @@ -1,7 +1,7 @@ import dpath.util from openfisca_core.indexed_enums import Enum -from openfisca_core.simulation_builder import SimulationBuilder +from openfisca_core.simulations import SimulationBuilder def calculate(tax_benefit_system, input_data: dict) -> dict: diff --git a/setup.cfg b/setup.cfg index 23760bcce8..e55b01ba7c 100644 --- a/setup.cfg +++ b/setup.cfg @@ -27,7 +27,9 @@ ignore = in-place = true include-in-doctest = openfisca_core/commons + openfisca_core/data_storage openfisca_core/entities + openfisca_core/experimental openfisca_core/holders openfisca_core/indexed_enums openfisca_core/periods diff --git a/tests/core/test_holders.py b/tests/core/test_holders.py index c72d053ad6..b784aea41b 100644 --- a/tests/core/test_holders.py +++ b/tests/core/test_holders.py @@ -6,8 +6,8 @@ from openfisca_core import holders, periods, tools from openfisca_core.errors import PeriodMismatchError +from openfisca_core.experimental import MemoryConfig from openfisca_core.holders import Holder -from openfisca_core.memory_config import MemoryConfig from openfisca_core.periods import DateUnit from openfisca_core.simulations import SimulationBuilder diff --git a/tests/core/variables/test_variables.py b/tests/core/variables/test_variables.py index d5d85a70d9..54030b8563 100644 --- a/tests/core/variables/test_variables.py +++ b/tests/core/variables/test_variables.py @@ -7,7 +7,7 @@ from openfisca_country_template.entities import Person from openfisca_core.periods import DateUnit -from openfisca_core.simulation_builder import SimulationBuilder +from openfisca_core.simulations import SimulationBuilder from openfisca_core.tools import assert_near from openfisca_core.variables import Variable