docs(experimental): add docs (#1275)

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+### 43.1.2 [#1274](https://github.com/openfisca/openfisca-core/pull/1275)
+
+#### Documentation
+
+- Add docs to experimental
+
 ### 43.1.1 [#1282](https://github.com/openfisca/openfisca-core/pull/1282)
 
 #### Technical changes
@@ -8,8 +14,6 @@
 
 ## 43.1.0 [#1255](https://github.com/openfisca/openfisca-core/pull/1255)
 
-#### New features
-
 - Make `CoreEntity` public
   - Allows for more easily creating customised entities.
 
@@ -2575,7 +2579,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/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

@@ -22,6 +22,7 @@ lint-doc: \
 	lint-doc-commons \
 	lint-doc-data_storage \
 	lint-doc-entities \
+	lint-doc-experimental \
 	lint-doc-indexed_enums \
 	;
 
@@ -44,6 +45,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

setup.py

@@ -70,7 +70,7 @@
 
 setup(
     name="OpenFisca-Core",
-    version="43.1.1",
+    version="43.1.2",
     author="OpenFisca Team",
     author_email="contact@openfisca.org",
     classifiers=[

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