flexmeasures.api.common.utils.deprecation_utils

Functions

flexmeasures.api.common.utils.deprecation_utils.deprecate_blueprint(blueprint: Blueprint, deprecation_date: pd.Timestamp | str | None = None, deprecation_link: str | None = None, sunset_date: pd.Timestamp | str | None = None, sunset_link: str | None = None, **kwargs)

Deprecates every route on a blueprint by adding the “Deprecation” header with a deprecation date.

Also logs a warning when a deprecated endpoint is called.

>>> from flask import Flask, Blueprint
>>> app = Flask('some_app')
>>> deprecated_bp = Blueprint('API version 1', 'v1_bp')
>>> deprecate_blueprint(
...     deprecated_bp,
...     deprecation_date="2022-12-14",
...     deprecation_link="https://flexmeasures.readthedocs.io/some-deprecation-notice",
...     sunset_date="2023-02-01",
...     sunset_link="https://flexmeasures.readthedocs.io/some-sunset-notice",
... )
>>> app.register_blueprint(deprecated_bp, url_prefix='/v1')
Parameters:

  • blueprint – The blueprint to be deprecated

  • deprecation_date – date indicating when the API endpoint was deprecated, used for the “Deprecation” header if no date is given, defaults to “true” see https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-deprecation-header#section-2-1

  • deprecation_link – url providing more information about the deprecation

  • sunset_date – date indicating when the API endpoint is likely to become unresponsive

  • sunset_link – url providing more information about the sunset

References

flexmeasures.api.common.utils.deprecation_utils.deprecate_fields(fields: str | list[str], deprecation_date: pd.Timestamp | str | None = None, deprecation_link: str | None = None, sunset_date: pd.Timestamp | str | None = None, sunset_link: str | None = None)

Deprecates a field (or fields) on a route by adding the “Deprecation” header with a deprecation date.

Also logs a warning when a deprecated field is used.

>>> from flask_classful import route
>>> from marshmallow import fields
>>> from webargs.flaskparser import use_kwargs
>>> @route("/item/", methods=["POST"])
... @use_kwargs(
...     {
...         "color": fields.String(),
...         "length": fields.String(),
...     }
... )
... def post_item(color, length):
...     deprecate_field(
...         "color",
...         deprecation_date="2022-12-14",
...         deprecation_link="https://flexmeasures.readthedocs.io/some-deprecation-notice",
...         sunset_date="2023-02-01",
...         sunset_link="https://flexmeasures.readthedocs.io/some-sunset-notice",
...     )
Parameters:

  • fields – The fields (as a list of strings) to be deprecated

  • deprecation_date – date indicating when the field was deprecated, used for the “Deprecation” header if no date is given, defaults to “true” see https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-deprecation-header#section-2-1

  • deprecation_link – url providing more information about the deprecation

  • sunset_date – date indicating when the field is likely to become unresponsive

  • sunset_link – url providing more information about the sunset

References

flexmeasures.api.common.utils.deprecation_utils.override_from_config(setting: Any, config_setting_name: str) → Any

Override setting by config setting, unless the latter is None or is missing.

flexmeasures.api.common.utils.deprecation_utils.sunset_blueprint(blueprint, api_version_being_sunset: str, sunset_link: str, api_version_upgrade_to: str = '3.0', rollback_possible: bool = True, **kwargs)

Sunsets every route on a blueprint by returning 410 (Gone) responses, if sunset is active.

Whether the sunset is active can be toggled using the config setting “FLEXMEASURES_API_SUNSET_ACTIVE”. If the sunset is inactive, this function will not affect any requests in this blueprint. If the endpoint implementations have been removed, set rollback_possible=False.

Errors will be logged by utils.error_utils.error_handling_router.