1#!/usr/bin/env python3
2#
3#   Copyright 2018 - The Android Open Source Project
4#
5#   Licensed under the Apache License, Version 2.0 (the "License");
6#   you may not use this file except in compliance with the License.
7#   You may obtain a copy of the License at
8#
9#       http://www.apache.org/licenses/LICENSE-2.0
10#
11#   Unless required by applicable law or agreed to in writing, software
12#   distributed under the License is distributed on an "AS IS" BASIS,
13#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14#   See the License for the specific language governing permissions and
15#   limitations under the License.
16import logging
17import sys
18
19from acts.controllers.android_device import AndroidDevice
20from acts.libs import version_selector
21
22
23class AndroidApi:
24    OLDEST = 0
25    MINIMUM = 0
26    L = 21
27    L_MR1 = 22
28    M = 23
29    N = 24
30    N_MR1 = 25
31    O = 26
32    O_MR1 = 27
33    P = 28
34    LATEST = sys.maxsize
35    MAX = sys.maxsize
36
37
38def android_api(min_api=AndroidApi.OLDEST, max_api=AndroidApi.LATEST):
39    """Decorates a function to only be called for the given API range.
40
41    Only gets called if the AndroidDevice in the args is within the specified
42    API range. Otherwise, a different function may be called instead. If the
43    API level is out of range, and no other function handles that API level, an
44    error is raise instead.
45
46    Note: In Python3.5 and below, the order of kwargs is not preserved. If your
47          function contains multiple AndroidDevices within the kwargs, and no
48          AndroidDevices within args, you are NOT guaranteed the first
49          AndroidDevice is the same one chosen each time the function runs. Due
50          to this, we do not check for AndroidDevices in kwargs.
51
52    Args:
53         min_api: The minimum API level. Can be an int or an AndroidApi value.
54         max_api: The maximum API level. Can be an int or an AndroidApi value.
55    """
56
57    def get_api_level(*args, **_):
58        for arg in args:
59            if isinstance(arg, AndroidDevice):
60                return arg.sdk_api_level()
61        logging.getLogger().error(
62            'An AndroidDevice was not found in the given '
63            'arguments.')
64        return None
65
66    return version_selector.set_version(get_api_level, min_api, max_api)
67