• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Copyright 2018 The Bazel Authors. All rights reserved.
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at
6#
7#    http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
14
15"""Starlark module for working with partial function objects.
16
17Partial function objects allow some parameters are bound before the call.
18
19Similar to https://docs.python.org/3/library/functools.html#functools.partial.
20"""
21
22def _call(partial, *args, **kwargs):
23    """Calls a partial created using `make`.
24
25    Args:
26      partial: The partial to be called.
27      *args: Additional positional arguments to be appended to the ones given to
28             make.
29      **kwargs: Additional keyword arguments to augment and override the ones
30                given to make.
31
32    Returns:
33      Whatever the function in the partial returns.
34    """
35    function_args = partial.args + args
36    function_kwargs = dict(partial.kwargs)
37    function_kwargs.update(kwargs)
38    return partial.function(*function_args, **function_kwargs)
39
40def _make(func, *args, **kwargs):
41    """Creates a partial that can be called using `call`.
42
43    A partial can have args assigned to it at the make site, and can have args
44    passed to it at the call sites.
45
46    A partial 'function' can be defined with positional args and kwargs:
47
48      # function with no args
49      def function1():
50        ...
51
52      # function with 2 args
53      def function2(arg1, arg2):
54        ...
55
56      # function with 2 args and keyword args
57      def function3(arg1, arg2, x, y):
58        ...
59
60    The positional args passed to the function are the args passed into make
61    followed by any additional positional args given to call. The below example
62    illustrates a function with two positional arguments where one is supplied by
63    make and the other by call:
64
65      # function demonstrating 1 arg at make site, and 1 arg at call site
66      def _foo(make_arg1, func_arg1):
67      print(make_arg1 + " " + func_arg1 + "!")
68
69    For example:
70
71      hi_func = partial.make(_foo, "Hello")
72      bye_func = partial.make(_foo, "Goodbye")
73      partial.call(hi_func, "Jennifer")
74      partial.call(hi_func, "Dave")
75      partial.call(bye_func, "Jennifer")
76      partial.call(bye_func, "Dave")
77
78    prints:
79
80      "Hello, Jennifer!"
81      "Hello, Dave!"
82      "Goodbye, Jennifer!"
83      "Goodbye, Dave!"
84
85    The keyword args given to the function are the kwargs passed into make
86    unioned with the keyword args given to call. In case of a conflict, the
87    keyword args given to call take precedence. This allows you to set a default
88    value for keyword arguments and override it at the call site.
89
90    Example with a make site arg, a call site arg, a make site kwarg and a
91    call site kwarg:
92
93      def _foo(make_arg1, call_arg1, make_location, call_location):
94        print(make_arg1 + " is from " + make_location + " and " +
95              call_arg1 + " is from " + call_location + "!")
96
97      func = partial.make(_foo, "Ben", make_location="Hollywood")
98      partial.call(func, "Jennifer", call_location="Denver")
99
100    Prints "Ben is from Hollywood and Jennifer is from Denver!".
101
102      partial.call(func, "Jennifer", make_location="LA", call_location="Denver")
103
104    Prints "Ben is from LA and Jennifer is from Denver!".
105
106    Note that keyword args may not overlap with positional args, regardless of
107    whether they are given during the make or call step. For instance, you can't
108    do:
109
110    def foo(x):
111      pass
112
113    func = partial.make(foo, 1)
114    partial.call(func, x=2)
115
116    Args:
117      func: The function to be called.
118      *args: Positional arguments to be passed to function.
119      **kwargs: Keyword arguments to be passed to function. Note that these can
120                be overridden at the call sites.
121
122    Returns:
123      A new `partial` that can be called using `call`
124    """
125    return struct(function = func, args = args, kwargs = kwargs)
126
127partial = struct(
128    make = _make,
129    call = _call,
130)
131