docs(experimental): add docs

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+### 42.2.1 [#1274](https://github.com/openfisca/openfisca-core/pull/1275)
+
+#### Documentation
+
+- Add docs to experimental
+
 ## 42.2.0 [#1255](https://github.com/openfisca/openfisca-core/pull/1255)
 
 #### New features
@@ -2578,7 +2584,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

setup.py

@@ -69,7 +69,7 @@
 
 setup(
  name="OpenFisca-Core",
- version="42.2.0",
+ version="42.2.1",
  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