API¶

This part of the documentation covers all the interfaces of Flask-Sustainable.

Interface¶

BaseHeader¶

class flask_sustainable.base.BaseHeader¶

Bases: object

Base class for all indicators and scores.

This class is an abstract class. It must be inherited by all classes that are indicators or scores.

abstract after_request(response)¶

Method called after the request.

This method will be called after each request. It can use the flask.g object to get the data stored in the before_request. It can also use the response object to modify the response.

This method is called in the same way as the after_request method of Flask.

Parameters: response (flask.Response) – The initial response object
Returns: The response object (modified or not)
Return type: flask.Response

abstract property name¶

Name of the header.

The name of the header that the client will ask through “Perf-“. This name will also be in the response of the request

The name must be a valid HTTP header name and must not contain any whitespace. Plus, it must be unique and don’t interfere with other headers. Finally, it must start with “Perf-”

This header will be used in theses scenarios:

(server side) In a OPTIONS response to indicate the available headers
(client side) In a request through the “Perf” header to indicate
the headers expected by the client.
(server side) In the response to indicate through the name header the value
of the header.

Returns: Name of the header
Return type: str

should_use()¶

Check if the indicator should be used.

The indicator/score should be used if the client ask for the header.

Returns: True if the indicator/score should be used, False otherwise
Return type: bool

Compression¶

class flask_sustainable.compress.Compression(response, accept_encodings=None)¶

Bases: object

Compress the response data when it’s possible.

This class is a wrapper around the flask.Response object. It adds the Content-Encoding header to the response. The response passed through this class is not modified.

To do this, it checks the Accept-Encoding header of the request. The best compression algorithm is chosen based on the Accept-Encoding header. etc.

response = flask.Response("Welcome!")
response = Compression(response, "deflate, gzip;q=1.0, *;q=0.5").compress()
response.headers["Content-Encoding"]
"gzip"

Initialize the Compression object.

If the accept_encodings is not given, it will be taken from the request If it’s given, we’ll use werkzeug.http.parse_accept_header to parse it

Parameters

response (flask.Response) – The response object
accept_encodings (str) – The Accept-Encoding header of the request (optional)

compress(check=False)¶

Compress the response data with the highest compression level available.

The best compression algorithm is chosen based on the Accept-Encoding header.

Example:

response = flask.Response("Welcome!")
response = Compression(response, "deflate, gzip;q=1.0, *;q=0.5").compress()
response.content_encoding
'gzip'

Parameters: check (bool) – If True, check if the compression is supported
Returns: The response object
Return type: flask.Response

static compress_data(algorithm, data, level=None)¶

Compress the data with the given algorithm.

This function raises an KeyError exception if the algorithm is not supported.

data = b"Welcome!"
Compression.compress_data("gzip", data)
b'\x1f\x8b\x08\x004\x0c\xe4b\x02\xff\x0bO\xcdI\xce\xcfMU\x04\x00\xd2\xb4B5\x08\x00\x00\x00'

Parameters

algorithm (str) – The algorithm to use, must be one of the supported algorithms
data (bytes) – The data to compress
level (int) – The compression level, if None, the default level is used

Returns

The compressed data

Return type

bytes

make_response(algorithm, check=True)¶

Make a response with the given algorithm.

This function change the reponse data and adds the Content-Encoding header.

Example:

response = flask.Response("Welcome!")
response.data
b'Welcome!'
response = Compression(response).make_response("gzip")
response.data
b'\x1f\x8b\x08\x004\x0c\xe4b\x02\xff\x0bO\xcdI\xce\xcfMU\x04\x00\xd2\xb4B5\x08\x00\x00\x00'
response.headers["Content-Encoding"]
'gzip'

Parameters

algorithm (str) – The algorithm to use, must be one of the supported algorithms
check (bool) – If True, check if the compression is supported (KeyError if not), defaults to True

Returns

The response object

Return type

flask.Response

Indicator¶

BaseIndicator¶

class flask_sustainable.base.BaseIndicator¶

Bases: BaseHeader

Base class for all indicators.

abstract after_request(response)¶

Method called after the request.

This method will be called after each request. It can use the flask.g object to get the data stored in the before_request. It can also use the response object to modify the response.

This method is called in the same way as the after_request method of Flask.

Parameters: response (flask.Response) – The initial response object
Returns: The response object (modified or not)
Return type: flask.Response

abstract before_request()¶

Method called before the request.

This method will be called before each request. It can be used to do some initialization.

A good example is to use the flask.g object to store some data. This data will be available in the after_request method.

This method is called in the same way as the flask.before_request() method of Flask.

Returns: None
Return type: None

abstract property name¶

Name of the header.

The name of the header that the client will ask through “Perf-“. This name will also be in the response of the request

The name must be a valid HTTP header name and must not contain any whitespace. Plus, it must be unique and don’t interfere with other headers. Finally, it must start with “Perf-”

This header will be used in theses scenarios:

(server side) In a OPTIONS response to indicate the available headers
(client side) In a request through the “Perf” header to indicate
the headers expected by the client.
(server side) In the response to indicate through the name header the value
of the header.

Returns: Name of the header
Return type: str

should_use()¶

Check if the indicator should be used.

The indicator/score should be used if the client ask for the header.

Returns: True if the indicator/score should be used, False otherwise
Return type: bool

Implementation of BaseIndicator¶

This module represents examples of indicator implementation.

For more information about an indicator, see BaseIndicator class.

class flask_sustainable.indicator.PerfCPU¶

Bases: BaseIndicator

Indicator that measure the CPU time of the request.

When the request is done, the response will contain a header named “Perf-CPU” with the CPU time of the request in milliseconds.

The CPU time is the time spent by the process that is different from the execution time.

Example

from flask_sustainable import Sustainable
from flask_sustainable.indicator import PerfCPU

app = flask.Flask(__name__)
sustainable = Sustainable(app)
sustainable.add_indicator(PerfCPU())

after_request(response)¶

Method called after the request.

This method will be called after each request. It can use the flask.g object to get the data stored in the before_request. It can also use the response object to modify the response.

This method is called in the same way as the after_request method of Flask.

Parameters: response (flask.Response) – The initial response object
Returns: The response object (modified or not)
Return type: flask.Response

before_request()¶

Method called before the request.

This method will be called before each request. It can be used to do some initialization.

A good example is to use the flask.g object to store some data. This data will be available in the after_request method.

This method is called in the same way as the flask.before_request() method of Flask.

Returns: None
Return type: None

should_use()¶

Check if the indicator should be used.

The indicator/score should be used if the client ask for the header.

Returns: True if the indicator/score should be used, False otherwise
Return type: bool

class flask_sustainable.indicator.PerfEnergy¶

Bases: BaseIndicator

Indicator that measure the energy usage of the request.

When the request is done, the response will contain a header named “Perf-Energy” with the energy usage of the request in watt-seconds.

after_request(response)¶

Method called after the request.

This method will be called after each request. It can use the flask.g object to get the data stored in the before_request. It can also use the response object to modify the response.

This method is called in the same way as the after_request method of Flask.

Parameters: response (flask.Response) – The initial response object
Returns: The response object (modified or not)
Return type: flask.Response

before_request()¶

Method called before the request.

This method will be called before each request. It can be used to do some initialization.

A good example is to use the flask.g object to store some data. This data will be available in the after_request method.

This method is called in the same way as the flask.before_request() method of Flask.

Returns: None
Return type: None

should_use()¶

Check if the indicator should be used.

The indicator/score should be used if the client ask for the header.

Returns: True if the indicator/score should be used, False otherwise
Return type: bool

class flask_sustainable.indicator.PerfPower¶

Bases: BaseIndicator

Indicator that measure the power usage of the request.

When the request is done, the response will contain a header named “Perf-Power” with the power usage of the request in watt.

after_request(response)¶

Method called after the request.

This method will be called after each request. It can use the flask.g object to get the data stored in the before_request. It can also use the response object to modify the response.

This method is called in the same way as the after_request method of Flask.

Parameters: response (flask.Response) – The initial response object
Returns: The response object (modified or not)
Return type: flask.Response

before_request()¶

Method called before the request.

This method will be called before each request. It can be used to do some initialization.

A good example is to use the flask.g object to store some data. This data will be available in the after_request method.

This method is called in the same way as the flask.before_request() method of Flask.

Returns: None
Return type: None

should_use()¶

Check if the indicator should be used.

The indicator/score should be used if the client ask for the header.

Returns: True if the indicator/score should be used, False otherwise
Return type: bool

class flask_sustainable.indicator.PerfRAM¶

Bases: BaseIndicator

Indicator that measure the RAM usage of the request.

When the request is done, the response will contain a header named “Perf-RAM” with the RAM usage of the request in megabytes.

Example

from flask_sustainable import Sustainable
from flask_sustainable.indicator import PerfRAM

app = flask.Flask(__name__)
sustainable = Sustainable(app)
sustainable.add_indicator(PerfRAM())

after_request(response)¶

Method called after the request.

This method will be called after each request. It can use the flask.g object to get the data stored in the before_request. It can also use the response object to modify the response.

This method is called in the same way as the after_request method of Flask.

Parameters: response (flask.Response) – The initial response object
Returns: The response object (modified or not)
Return type: flask.Response

before_request()¶

Method called before the request.

This method will be called before each request. It can be used to do some initialization.

A good example is to use the flask.g object to store some data. This data will be available in the after_request method.

This method is called in the same way as the flask.before_request() method of Flask.

Returns: None
Return type: None

should_use()¶

Check if the indicator should be used.

The indicator/score should be used if the client ask for the header.

Returns: True if the indicator/score should be used, False otherwise
Return type: bool

class flask_sustainable.indicator.PerfTime¶

Bases: BaseIndicator

Indicator that measure the time of the request.

When the request is done, the response will contain a header named “Perf-Time” with the time of the request in milliseconds.

Example

from flask_sustainable import Sustainable
from flask_sustainable.indicator import PerfTime

app = flask.Flask(__name__)
sustainable = Sustainable(app)
sustainable.add_indicator(PerfTime())

after_request(response)¶

Method called after the request.

This method will be called after each request. It can use the flask.g object to get the data stored in the before_request. It can also use the response object to modify the response.

This method is called in the same way as the after_request method of Flask.

Parameters: response (flask.Response) – The initial response object
Returns: The response object (modified or not)
Return type: flask.Response

before_request()¶

Method called before the request.

This method will be called before each request. It can be used to do some initialization.

A good example is to use the flask.g object to store some data. This data will be available in the after_request method.

This method is called in the same way as the flask.before_request() method of Flask.

Returns: None
Return type: None

should_use()¶

Check if the indicator should be used.

The indicator/score should be used if the client ask for the header.

Returns: True if the indicator/score should be used, False otherwise
Return type: bool

Score¶

BaseScore¶

class flask_sustainable.base.BaseScore¶

Bases: BaseHeader

Base class for all scores.

A score is executed after all indicators.

The name of the score must follow Perf-ScoreX where X is a int > 0.

The result of a score is called a score. A score don’t have a before_request() because his execution comes at last.

Indeed, because all indicators are already used, we can call them to get the score. It’s possible that a score is not requested by the user, it will not be available at the score level.

It’s the responsibility of the implementation to verify whether the indicator is present in the headers. If an indicator is required and is not present, the function after_request must return none and not raise an exception. It would not be appropriate to add a header if the calculation is not possible.

Example:

class Example(BaseScore):
    name: str = "Perf-Score1"

    def after_request(self, response):
        indicator = response.headers.get("Perf-Example")
        if not indicator:
            return
        return indicator ** 2

abstract after_request(response)¶

Method called after the request.

This method will be called after each request. It can use the flask.g object to get the data stored in the before_request. It can also use the response object to modify the response.

This method is called in the same way as the after_request method of Flask.

Parameters: response (flask.Response) – The initial response object
Returns: The response object (modified or not)
Return type: flask.Response

abstract property name¶

Name of the header.

The name of the header that the client will ask through “Perf-“. This name will also be in the response of the request

The name must be a valid HTTP header name and must not contain any whitespace. Plus, it must be unique and don’t interfere with other headers. Finally, it must start with “Perf-”

This header will be used in theses scenarios:

(server side) In a OPTIONS response to indicate the available headers
(client side) In a request through the “Perf” header to indicate
the headers expected by the client.
(server side) In the response to indicate through the name header the value
of the header.

Returns: Name of the header
Return type: str

should_use()¶

Check if the indicator should be used.

The indicator/score should be used if the client ask for the header.

Returns: True if the indicator/score should be used, False otherwise
Return type: bool

Implementation of BaseScore¶

This module represents examples of score implementation.

For more information about what a score, see BaseScore class.

class flask_sustainable.score.PerfScoreCO2¶

Bases: BaseScore

Score that measure the CO2 emissions of the request.

When the request is done, the response will contain a header named “Perf-Score-1” with an equivalent of CO2 emissions of the request in kilograms.

The CO2 emissions are the emissions of the process that is different from the execution time.

Example

from flask_sustainable import Sustainable
from flask_sustainable.score import PerfScoreCO2

app = flask.Flask(__name__)
sustainable = Sustainable(app)
sustainable.add_score(PerfScoreCO2())

after_request(response)¶

Method called after the request.

This method will be called after each request. It can use the flask.g object to get the data stored in the before_request. It can also use the response object to modify the response.

This method is called in the same way as the after_request method of Flask.

Parameters: response (flask.Response) – The initial response object
Returns: The response object (modified or not)
Return type: flask.Response

should_use()¶

Check if the indicator should be used.

The indicator/score should be used if the client ask for the header.

Returns: True if the indicator/score should be used, False otherwise
Return type: bool

API¶

Interface¶

BaseHeader¶

Compression¶

Indicator¶

BaseIndicator¶

Implementation of BaseIndicator¶

Score¶

BaseScore¶

Implementation of BaseScore¶

Contents

Navigation