OpenFisca-Core-test 46.0.0__py3-none-any.whl

openfisca_web_api/loader/tax_benefit_system.py

@@ -0,0 +1,27 @@
+import importlib
+import logging
+import traceback
+from os import linesep
+
+log = logging.getLogger(__name__)
+
+
+def build_tax_benefit_system(country_package_name):
+    try:
+        country_package = importlib.import_module(country_package_name)
+    except ImportError:
+        message = linesep.join(
+            [
+                traceback.format_exc(),
+                f"Could not import module `{country_package_name}`.",
+                "Are you sure it is installed in your environment? If so, look at the stack trace above to determine the origin of this error.",
+                "See more at <https://github.com/openfisca/country-template#installing>.",
+                linesep,
+            ],
+        )
+        raise ValueError(message)
+    try:
+        return country_package.CountryTaxBenefitSystem()
+    except NameError:  # Gunicorn swallows NameErrors. Force printing the stack trace.
+        log.exception(traceback.format_exc())
+        raise

openfisca_web_api/loader/variables.py

@@ -0,0 +1,121 @@
+import datetime
+import inspect
+import textwrap
+
+from openfisca_core.indexed_enums import Enum
+from openfisca_core.variables import VALUE_TYPES
+
+
+def get_next_day(date):
+    parsed_date = date
+    next_day = parsed_date + datetime.timedelta(days=1)
+    return next_day.isoformat().split("T")[0]
+
+
+def get_default_value(variable):
+    default_value = variable.default_value
+    if isinstance(default_value, datetime.date):
+        return default_value.isoformat()
+
+    if isinstance(default_value, Enum):
+        return default_value.name
+
+    return default_value
+
+
+def build_source_url(
+    country_package_metadata,
+    source_file_path,
+    start_line_number,
+    source_code,
+):
+    nb_lines = source_code.count("\n")
+    return "{}/blob/{}{}#L{}-L{}".format(
+        country_package_metadata["repository_url"],
+        country_package_metadata["version"],
+        source_file_path,
+        start_line_number,
+        start_line_number + nb_lines - 1,
+    )
+
+
+def build_formula(formula, country_package_metadata, source_file_path):
+    source_code, start_line_number = inspect.getsourcelines(formula)
+
+    source_code = textwrap.dedent("".join(source_code))
+
+    api_formula = {
+        "source": build_source_url(
+            country_package_metadata,
+            source_file_path,
+            start_line_number,
+            source_code,
+        ),
+        "content": source_code,
+    }
+
+    if formula.__doc__:
+        api_formula["documentation"] = textwrap.dedent(formula.__doc__)
+
+    return api_formula
+
+
+def build_formulas(formulas, country_package_metadata, source_file_path):
+    return {
+        start_date: build_formula(formula, country_package_metadata, source_file_path)
+        for start_date, formula in formulas.items()
+    }
+
+
+def build_variable(variable, country_package_metadata):
+    (
+        source_file_path,
+        source_code,
+        start_line_number,
+    ) = variable.get_introspection_data()
+    result = {
+        "id": variable.name,
+        "description": variable.label,
+        "valueType": VALUE_TYPES[variable.value_type]["formatted_value_type"],
+        "defaultValue": get_default_value(variable),
+        "definitionPeriod": variable.definition_period.upper(),
+        "entity": variable.entity.key,
+    }
+
+    if source_code:
+        result["source"] = build_source_url(
+            country_package_metadata,
+            source_file_path,
+            start_line_number,
+            source_code,
+        )
+
+    if variable.documentation:
+        result["documentation"] = variable.documentation.strip()
+
+    if variable.reference:
+        result["references"] = variable.reference
+
+    if len(variable.formulas) > 0:
+        result["formulas"] = build_formulas(
+            variable.formulas,
+            country_package_metadata,
+            source_file_path,
+        )
+
+        if variable.end:
+            result["formulas"][get_next_day(variable.end)] = None
+
+    if variable.value_type == Enum:
+        result["possibleValues"] = {
+            item.name: item.value for item in list(variable.possible_values)
+        }
+
+    return result
+
+
+def build_variables(tax_benefit_system, country_package_metadata):
+    return {
+        name: build_variable(variable, country_package_metadata)
+        for name, variable in tax_benefit_system.variables.items()
+    }

openfisca_web_api/openAPI.yml

@@ -0,0 +1,434 @@
+openapi: "3.0.0"
+
+info:
+  title: "{COUNTRY_PACKAGE_NAME} Web API"
+  description: "The OpenFisca Web API lets you get up-to-date information and formulas included in the {COUNTRY_PACKAGE_NAME} legislation."
+  version: "{COUNTRY_PACKAGE_VERSION}"
+  termsOfService: "https://openfisca.org/doc/licence.html"
+  contact:
+    email: "contact@openfisca.org"
+  license:
+    name: "AGPL"
+    url: "https://www.gnu.org/licenses/agpl-3.0"
+
+tags:
+  - name: "Parameters"
+    description: "A parameter is a numeric property of the legislation that can evolve over time."
+    externalDocs:
+      description: "Parameters documentation"
+      url: "https://openfisca.org/doc/key-concepts/parameters.html"
+
+  - name: "Variables"
+    description: "A variable depends on a person, or an entity (e.g. zip code, salary, income tax)."
+    externalDocs:
+      description: "Variables documentation"
+      url: "https://openfisca.org/doc/key-concepts/variables.html"
+
+  - name: "Entities"
+    description: "An entity is a person of a group of individuals (such as a household)."
+    externalDocs:
+      description: "Entities documentation"
+      url: "https://openfisca.org/doc/key-concepts/person,_entities,_role.html"
+
+  - name: "Calculations"
+
+  - name: "Documentation"
+
+components:
+  schemas:
+    Parameter:
+      type: "object"
+      properties:
+        values:
+          $ref: "#/components/schemas/Values"
+        brackets:
+          type: "object"
+          additionalProperties:
+            $ref: "#/components/schemas/Brackets"
+        subparams:
+          type: "object"
+          additionalProperties:
+            type: "object"
+            properties:
+              definition:
+                type: "string"
+        metadata:
+          type: "object"
+        description:
+          type: "string"
+        id:
+          type: "integer"
+          format: "string"
+        source:
+          type: "string"
+
+    Parameters:
+      type: "object"
+      additionalProperties:
+        type: "object"
+        properties:
+          description:
+            type: "string"
+          href:
+            type: "string"
+
+    Variable:
+      type: "object"
+      properties:
+        defaultValue:
+          type: "string"
+        definitionPeriod:
+          type: "string"
+          enum:
+            - "MONTH"
+            - "YEAR"
+            - "ETERNITY"
+        description:
+          type: "string"
+        entity:
+          type: "string"
+        formulas:
+          type: "object"
+          additionalProperties:
+            $ref: "#/components/schemas/Formula"
+        id:
+          type: "string"
+        reference:
+          type: "array"
+          items:
+            type: "string"
+        source:
+          type: "string"
+        valueType:
+          type: "string"
+          enum:
+            - "Int"
+            - "Float"
+            - "Boolean"
+            - "Date"
+            - "String"
+
+    Variables:
+      type: "object"
+      additionalProperties:
+        type: "object"
+        properties:
+          description:
+            type: "string"
+          href:
+            type: "string"
+
+    Formula:
+      type: "object"
+      properties:
+        content:
+          type: "string"
+        source:
+          type: "string"
+
+    Brackets:
+      type: "object"
+      additionalProperties:
+        type: "number"
+        format: "float"
+
+    Values:
+      description: "All keys are ISO dates. Values can be numbers, booleans, or arrays of a single type (number, boolean or string)."
+      type: "object"
+      additionalProperties:
+        $ref: "#/components/schemas/Value"
+      # propertyNames:  # this keyword is part of JSON Schema but is not supported in OpenAPI v3.0.0
+      # pattern: "^[12][0-9]{3}-[01][0-9]-[0-3][0-9]$"  # all keys are ISO dates
+
+    Value:
+      oneOf:
+      - type: "boolean"
+      - type: "number"
+        format: "float"
+      - type: "array"
+        items:
+          oneOf:
+          - type: "string"
+          - type: "number"
+
+    Entities:
+      type: "object"
+      properties:
+        description:
+          type: "string"
+        documentation:
+          type: "string"
+        plural:
+          type: "string"
+        roles:
+          type: "object"
+          additionalProperties:
+            $ref: "#/components/schemas/Roles"
+
+    Roles:
+      type: "object"
+      properties:
+        description:
+          type: "string"
+        max:
+          type: "integer"
+        plural:
+          type: "string"
+
+    Trace:
+      type: "object"
+      properties:
+        requestedCalculations:
+          type: "array"
+          items:
+            type: "string"
+        entitiesDescription:
+          type: "object"
+          additionalProperties: false  # Will be dynamically added by the Web API
+        trace:
+          type: "object"
+          additionalProperties:
+            type: "object"
+            properties:
+              value:
+                type: "array"
+                items: {}
+              dependencies:
+                type: "array"
+                items:
+                  type: "string"
+              parameters:
+                type: "object"
+                additionalProperties:
+                  type: "object"
+
+  headers:
+    Country-Package:
+      description: "The name of the country package currently loaded in this API server"
+      schema:
+        type: "string"
+
+    Country-Package-Version:
+      description: "The version of the country package currently loaded in this API server"
+      schema:
+        type: "string"
+        pattern: "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:-((?:0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$"  # adapted from https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string
+
+paths:
+  /calculate:
+    post:
+      summary: "Run a simulation"
+      tags:
+      - "Calculations"
+      operationId: "calculate"
+      requestBody:
+        description: "Describe the situation (persons and entities). Add the variable you wish to calculate in the proper entity, with null as the value. Learn more in our official documentation: https://openfisca.org/doc/openfisca-web-api/input-output-data.html"
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/SituationInput"
+      responses:
+        200:
+          description: "The calculation result is sent back in the response body"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SituationOutput"
+          headers:
+            Country-Package:
+              $ref: "#/components/headers/Country-Package"
+            Country-Package-Version:
+              $ref: "#/components/headers/Country-Package-Version"
+        404:
+          description: "A variable mentioned in the input situation does not exist in the loaded tax and benefit system. Details are sent back in the response body"
+          headers:
+            Country-Package:
+              $ref: "#/components/headers/Country-Package"
+            Country-Package-Version:
+              $ref: "#/components/headers/Country-Package-Version"
+        400:
+          description: "The request is invalid. Details about the error are sent back in the response body"
+          headers:
+            Country-Package:
+              $ref: "#/components/headers/Country-Package"
+            Country-Package-Version:
+              $ref: "#/components/headers/Country-Package-Version"
+
+  /parameters:
+    get:
+      tags:
+      - "Parameters"
+      summary: "List all available parameters"
+      operationId: "getParameters"
+      responses:
+        200:
+          description: "The list of parameters is sent back in the response body"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Parameters"
+          headers:
+            Country-Package:
+              $ref: "#/components/headers/Country-Package"
+            Country-Package-Version:
+              $ref: "#/components/headers/Country-Package-Version"
+
+  /parameter/{parameterID}:
+    get:
+      tags:
+      - "Parameters"
+      summary: "Get information about a specific parameter"
+      operationId: "getParameter"
+      parameters:
+      - name: "parameterID"
+        in: "path"
+        description: "ID of parameter. IDs can be obtained by enumerating the /parameters endpoint"
+        required: true
+        schema:
+          type: "string"
+      responses:
+        200:
+          description: "The requested parameter's information is sent back in the response body"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Parameter"
+          headers:
+            Country-Package:
+              $ref: "#/components/headers/Country-Package"
+            Country-Package-Version:
+              $ref: "#/components/headers/Country-Package-Version"
+        404:
+          description: "The requested parameter does not exist"
+          headers:
+            Country-Package:
+              $ref: "#/components/headers/Country-Package"
+            Country-Package-Version:
+              $ref: "#/components/headers/Country-Package-Version"
+
+  /variables:
+    get:
+      tags:
+      - "Variables"
+      summary: "List all available variables"
+      operationId: "getVariables"
+      responses:
+        200:
+          description: "The list of variables is sent back in the response body"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Variables"
+          headers:
+            Country-Package:
+              $ref: "#/components/headers/Country-Package"
+            Country-Package-Version:
+              $ref: "#/components/headers/Country-Package-Version"
+
+  /variable/{variableID}:
+    get:
+      tags:
+      - "Variables"
+      summary: "Get information about a specific variable"
+      operationId: "getVariable"
+      parameters:
+      - name: "variableID"
+        in: "path"
+        description: "ID of a variable. IDs can be obtained by enumerating the /variables endpoint."
+        required: true
+        schema:
+          type: "string"
+      responses:
+        200:
+          description: "The requested variable's information is sent back in the response body"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Variable"
+          headers:
+            Country-Package:
+              $ref: "#/components/headers/Country-Package"
+            Country-Package-Version:
+              $ref: "#/components/headers/Country-Package-Version"
+        404:
+          description: "The requested variable does not exist"
+          headers:
+            Country-Package:
+              $ref: "#/components/headers/Country-Package"
+            Country-Package-Version:
+              $ref: "#/components/headers/Country-Package-Version"
+
+  /entities:
+    get:
+      tags:
+      - "Entities"
+      summary: "List all available Entities"
+      operationId: "getEntities"
+      responses:
+        200:
+          description: "The list of the entities as well as their information is sent back in the response body"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Entities"
+          headers:
+            Country-Package:
+              $ref: "#/components/headers/Country-Package"
+            Country-Package-Version:
+              $ref: "#/components/headers/Country-Package-Version"
+
+  /trace:
+    post:
+      summary: "Explore a simulation's steps in details."
+      tags:
+      - "Calculations"
+      operationId: "trace"
+      requestBody:
+        description: "Describe the situation (persons and entities). Add the variable you wish to calculate in the proper entity, with null as the value."
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/SituationInput"
+      responses:
+        200:
+          description: "The calculation details are sent back in the response body"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Trace"
+          headers:
+            Country-Package:
+              $ref: "#/components/headers/Country-Package"
+            Country-Package-Version:
+              $ref: "#/components/headers/Country-Package-Version"
+        404:
+          description: "A variable mentioned in the input situation does not exist in the loaded tax and benefit system. Details are sent back in the response body"
+          headers:
+            Country-Package:
+              $ref: "#/components/headers/Country-Package"
+            Country-Package-Version:
+              $ref: "#/components/headers/Country-Package-Version"
+        400:
+          description: "The request is invalid. Details about the error are sent back in the response body"
+          headers:
+            Country-Package:
+              $ref: "#/components/headers/Country-Package"
+            Country-Package-Version:
+              $ref: "#/components/headers/Country-Package-Version"
+
+  /spec:
+    get:
+      summary: "Provide the API documentation in an OpenAPI format"
+      tags:
+      - "Documentation"
+      operationId: "spec"
+      responses:
+        200:
+          description: "The API documentation is sent back in the response body"
+          headers:
+            Country-Package:
+              $ref: "#/components/headers/Country-Package"
+            Country-Package-Version:
+              $ref: "#/components/headers/Country-Package-Version"

openfisca_web_api/scripts/serve.py

@@ -0,0 +1,99 @@
+import logging
+import sys
+
+from openfisca_core.scripts import build_tax_benefit_system
+from openfisca_web_api.app import create_app
+from openfisca_web_api.errors import handle_import_error
+
+try:
+    from gunicorn import config
+    from gunicorn.app.base import BaseApplication
+except ImportError as error:
+    handle_import_error(error)
+
+
+"""
+    Define the `openfisca serve` command line interface.
+"""
+
+DEFAULT_PORT = "5000"
+HOST = "127.0.0.1"
+DEFAULT_WORKERS_NUMBER = "3"
+DEFAULT_TIMEOUT = 1200
+
+
+log = logging.getLogger(__name__)
+
+
+def read_user_configuration(default_configuration, command_line_parser):
+    configuration = default_configuration
+    args, unknown_args = command_line_parser.parse_known_args()
+
+    if args.configuration_file:
+        file_configuration = {}
+        with open(args.configuration_file) as file:
+            exec(file.read(), {}, file_configuration)
+
+        # Configuration file overloads default configuration
+        update(configuration, file_configuration)
+
+    # Command line configuration overloads all configuration
+    gunicorn_parser = config.Config().parser()
+    configuration = update(configuration, vars(args))
+    configuration = update(
+        configuration,
+        vars(gunicorn_parser.parse_args(unknown_args)),
+    )
+    if configuration["args"]:
+        command_line_parser.print_help()
+        log.error("Unexpected positional argument {}".format(configuration["args"]))
+        sys.exit(1)
+
+    return configuration
+
+
+def update(configuration, new_options):
+    for key, value in new_options.items():
+        if value is not None:
+            configuration[key] = value
+            if key == "port":
+                configuration["bind"] = configuration["bind"][:-4] + str(
+                    configuration["port"],
+                )
+    return configuration
+
+
+class OpenFiscaWebAPIApplication(BaseApplication):
+    def __init__(self, options) -> None:
+        self.options = options
+        super().__init__()
+
+    def load_config(self) -> None:
+        for key, value in self.options.items():
+            if key in self.cfg.settings:
+                self.cfg.set(key.lower(), value)
+
+    def load(self):
+        tax_benefit_system = build_tax_benefit_system(
+            self.options.get("country_package"),
+            self.options.get("extensions"),
+            self.options.get("reforms"),
+        )
+        return create_app(
+            tax_benefit_system,
+            self.options.get("tracker_url"),
+            self.options.get("tracker_idsite"),
+            self.options.get("tracker_token"),
+            self.options.get("welcome_message"),
+        )
+
+
+def main(parser) -> None:
+    configuration = {
+        "port": DEFAULT_PORT,
+        "bind": f"{HOST}:{DEFAULT_PORT}",
+        "workers": DEFAULT_WORKERS_NUMBER,
+        "timeout": DEFAULT_TIMEOUT,
+    }
+    configuration = read_user_configuration(configuration, parser)
+    OpenFiscaWebAPIApplication(configuration).run()