docs(exp): add docs to experimental (#1274)

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
 

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",
+]

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",
+]

openfisca_core/warnings/memory_warning.py → openfisca_core/experimental/_errors.py

@@ -1,2 +1,5 @@
 class MemoryConfigWarning(UserWarning):
     """Custom warning for MemoryConfig."""
+
+
+__all__ = ["MemoryConfigWarning"]

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)

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
 

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

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

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 \

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:

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

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
 

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