Initial checkin of gin.Config class and required utilities.

gin/local/__init__.py

@@ -0,0 +1,19 @@
+# coding=utf-8
+# Copyright 2020 The Gin-Config Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Init file for the `gin.local` package."""
+
+from gin.local.config import bind
+from gin.local.config import Config

gin/local/config.py

@@ -0,0 +1,191 @@
+# coding=utf-8
+# Copyright 2020 The Gin-Config Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Defines the `gin.Config` class and associated functions."""
+
+import copy
+import inspect
+from typing import Any, Callable, Dict, Optional
+
+from gin.local import partial
+
+import tree
+
+
+class ConfigState:
+  """Encapsulates state associated with a `Config`.
+
+  This is separated out into its own class to avoid any possibility of name
+  collisions when assigning parameters to a `Config` instance.
+  """
+
+  def __init__(self, fn_or_cls: Callable[..., Any]):
+    self.fn_or_cls = fn_or_cls
+    self.signature = inspect.signature(fn_or_cls)
+    self.has_kwargs = any(  # Used to disable param name validation.
+        param.kind == inspect.Parameter.VAR_KEYWORD
+        for param in self.signature.parameters.values())
+    self.call = False
+
+  def validate(self, arg_name, unused_value):
+    """Validates `arg_name` to ensure it is a parameter of `self.fn_or_cls`."""
+    if not self.has_kwargs and arg_name not in self.signature.parameters:
+      raise TypeError(f"No argument named '{arg_name}' in {self.fn_or_cls}.")
+
+
+class Config:
+  """Captures configuration for a specific function or class.
+
+  This class represents the configuration for a given function or class,
+  exposing configured parameters as mutable attributes. For example, for a class
+
+      TestClass:
+
+        def __init__(self, arg, kwarg=None):
+          self.arg = arg
+          self.kwarg = kwarg
+
+  a configuration may (for instance) be accomplished via
+
+      class_config = Config(TestClass, kwarg='kwarg')
+      class_config.arg = 1
+
+  This `Config` instance may then be passed to the `bind` function to obtain
+  a "partial class" with values bound for the `arg` and `kwarg` parameters of
+  the test class constructor:
+
+      partial_class = bind(class_config)
+      instance = partial_class()
+      assert instance.arg == 'arg'
+      assert instance.kwarg == 'kwarg'
+
+  A given `Config` instance may be "called" to make it an "instance
+  configuration". This will have the effect that when `bind` is called, the
+  result of calling the corresponding partial will be provided instead of the
+  partial itself:
+
+      instance_config = class_config()
+      instance = bind(instance_config)
+      assert instance.arg == 'arg'
+      assert instance.kwarg == 'kwarg'
+
+  The instance config becomes separated from the class config, so any further
+  changes to `class_config` are not reflected by `instance_config` (and vice
+  versa).
+  """
+
+  __state__: ConfigState  # Lets pytype know about the __state__ attribute.
+
+  def __init__(self, fn_or_cls: Callable[..., Any], *args, **kwargs):
+    """Initialize for `fn_or_cls`, optionally specifying parameters.
+
+    Args:
+      fn_or_cls: The function or class to configure.
+      *args: Any positional arguments to configure for `fn_or_cls`.
+      **kwargs: Any keyword arguments to configure for `fn_or_cls`.
+    """
+    super().__setattr__('__state__', ConfigState(fn_or_cls))
+    signature = self.__state__.signature
+    bound_arguments = signature.bind_partial(*args, **kwargs)
+    for name, value in bound_arguments.arguments.items():
+      if signature.parameters[name].kind == inspect.Parameter.POSITIONAL_ONLY:
+        raise ValueError('Positional only arguments not supported.')
+      if signature.parameters[name].kind == inspect.Parameter.VAR_POSITIONAL:
+        raise ValueError('Variable positional arguments not supported.')
+      setattr(self, name, value)
+
+  # Providing this pass-through method prevents spurious pytype errors.
+  def __getattr__(self, name: str):
+    """Get parameter with given `name`."""
+    super().__getattribute__(name)
+
+  def __setattr__(self, name: str, value: Any):
+    """Sets parameter `name` to `value`."""
+    self.__state__.validate(name, value)  # Make sure it's a valid param name.
+    super().__setattr__(name, value)
+
+  def __repr__(self):
+    formatted_fn_or_cls = self.__state__.fn_or_cls.__qualname__
+    formatted_params = [f'{k}={v}' for k, v in params(self).items()]
+    return f"Config[{formatted_fn_or_cls}]({', '.join(formatted_params)})"
+
+  def __copy__(self):
+    config_copy = object.__new__(type(self))
+    new_dict = copy.copy(self.__dict__)
+    new_dict['__state__'] = copy.deepcopy(self.__state__)
+    config_copy.__dict__.update(new_dict)
+    return config_copy
+
+  def __call__(self):
+    """Creates a "called" copy of this `Config` instance."""
+    if self.__state__.call:
+      raise ValueError('The config has already been marked as called.')
+    new_config = copy.copy(self)
+    new_config.__state__.call = True
+    return new_config
+
+
+def params(config: Config):
+  """Returns a dictionary of the parameters specified by `config`."""
+  return {
+      name: value for name, value in vars(config).items() if name != '__state__'
+  }
+
+
+def bind(config: Config, memo: Optional[Dict[Config, Any]] = None) -> Any:
+  """Binds `config`, returning a `partial` with bound parameters.
+
+  This is the core function for turning a `Config` into a (partially) bound
+  object. It recursively walks through `config`'s parameters, binding any nested
+  `Config` instances. The returned result is a callable `partial` with all
+  config parameters set.
+
+  If the same `Config` instance is seen multiple times during traversal of the
+  configuration tree, `bind` is called only once (for the first instance
+  encountered), and the result is reused for subsequent copies of the instance.
+  This is achieved via the `memo` dictionary (similar to `deepcopy`). This has
+  the effect that for configured class instances, each separate config instance
+  is in one-to-one correspondence with an actual instance of the configured
+  class after calling `bind` (shared config instances <=> shared class
+  instances).
+
+  Args:
+    config: A `Config` instance to bind.
+    memo: An optional dictionary mapping `Config` instances to their "bound"
+      values. This is used to map shared instances of a "instantiated" `Config`
+      in the configuration tree to a single shared object instance/value after
+      binding. If an empty dictionary is supplied, it will be filled with a
+      mapping of all `Config` instances in the full tree reachable from `config`
+      to their corresponding partial or instance values.
+
+  Returns:
+    The bound version of `config`.
+  """
+  memo = {} if memo is None else memo
+
+  def map_fn(leaf):
+    return bind(leaf, memo) if isinstance(leaf, Config) else leaf
+
+  if config not in memo:
+    kwargs = {}
+    for name, value in params(config).items():
+      value = tree.map_structure(map_fn, value)
+      kwargs[name] = value
+    state = config.__state__
+    bindings = state.signature.bind_partial(**kwargs)
+    result = partial.partial(state.fn_or_cls, *bindings.args, **bindings.kwargs)
+    memo[config] = result() if state.call else result
+
+  return memo[config]

gin/local/partial.py

@@ -0,0 +1,117 @@
+# coding=utf-8
+# Copyright 2020 The Gin-Config Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Defines a generic `partial` that works for both classes and functions."""
+
+import functools
+import inspect
+
+from typing import Any, Callable, Type
+
+
+def _make_meta_call_wrapper(cls: Type[object]):
+  """Creates a pickle-compatible wrapper for `type(cls).__call__`.
+
+  This function works in tandem with `_decorate_fn_or_cls` below. It wraps
+  `type(cls).__call__`, which is in general responsible for creating a new
+  instance of `cls` or one of its subclasses. In cases where the to-be-created
+  class is Gin's dynamically-subclassed version of `cls`, the wrapper here
+  instead returns an instance of `cls`, which isn't a dynamic subclass and more
+  generally doesn't have any Gin-related magic applied. This means the instance
+  is compatible with pickling, and is totally transparent to any inspections by
+  user code (since it really is an instance of the original type).
+
+  Args:
+    cls: The class whose metaclass's call method should be wrapped.
+
+  Returns:
+    A wrapped version of the `type(cls).__call__`.
+  """
+  cls_meta = type(cls)
+
+  @functools.wraps(cls_meta.__call__)
+  def meta_call_wrapper(new_cls: Type[object], *args, **kwargs):
+    # If `new_cls` (the to-be-created class) is a direct subclass of `cls`, we
+    # can be sure that it's Gin's dynamically created subclass. In this case,
+    # we directly create an instance of `cls` instead. Otherwise, some further
+    # dynamic subclassing by user code has likely occurred, and we just create
+    # an instance of `new_cls` to avoid issues. This instance is likely not
+    # compatible with pickle, but that's generally true of dynamically created
+    # subclasses and would require some user workaround with or without Gin.
+    if new_cls.__bases__ == (cls,):
+      new_cls = cls
+    return cls_meta.__call__(new_cls, *args, **kwargs)
+
+  return meta_call_wrapper
+
+
+def partialclass(cls, *args, **kwargs):
+  """Creates a class with partially-specified parameters.
+
+  This class should generally behave interchangeably with `cls` in most
+  settings. The method used here is to create a dynamic subclass of `cls`, with
+  a metaclass which is itself a dynamic subclass of `cls`'s metaclass. This
+  metaclass supplies partial parameters to `cls` during instance creation, with
+  that result that constructing a `partial_cls` yields actual instances of
+  `cls`.
+
+  The returned `partial_cls` will have the following properties:
+
+    - `issubclass(partial_cls, cls) == True`
+    - `issubclass(cls, partial_cls) == False`
+    - `isinstance(partial_cls, type(cls)) == True`
+    - `type(partial_cls(...)) == cls`
+
+  Args:
+    cls: The class to partially specify parameters for.
+    *args: Positional parameters to provide when constructing `cls`.
+    **kwargs: Keyword arguments to provide when constructing `cls`.
+
+  Returns:
+    A dynamic subclass of `cls`, with parameters partially specified.
+  """
+  cls_meta = type(cls)
+  meta_call = _make_meta_call_wrapper(cls)  # See this for more details.
+  # Construct a new metaclass, subclassing the one from `cls`, supplying our
+  # decorated `__call__`. Most often this is just subclassing Python's `type`,
+  # but when `cls` has a custom metaclass set, this ensures that it will
+  # continue to work properly.
+  decorating_meta = type(cls_meta)(cls_meta.__name__, (cls_meta,), {
+      '__call__': functools.partialmethod(meta_call, *args, **kwargs),
+  })
+  # Now we construct our class. This is a subclass of `cls`, but only with
+  # wrapper-related overrides, since currying parameters is all handled via the
+  # metaclass's `__call__` method. Note that we let '__annotations__' simply get
+  # forwarded to the base class, since creating a new type doesn't set this
+  # attribute by default.
+  overrides = {
+      attr: getattr(cls, attr)
+      for attr in ('__module__', '__name__', '__qualname__', '__doc__')
+  }
+  # If `cls` won't have a `__dict__` attribute, disable `__dict__` creation on
+  # our subclass as well. This seems like generally correct behavior, and also
+  # prevents errors that can arise under some very specific circumstances due
+  # to a CPython bug in type creation.
+  if getattr(cls, '__dictoffset__', None) == 0:
+    overrides['__slots__'] = ()
+  # Finally, create the partial class using the metaclass created above.
+  return decorating_meta(cls.__name__, (cls,), overrides)
+
+
+def partial(fn_or_cls: Callable[..., Any], *args, **kwargs):
+  if inspect.isclass(fn_or_cls):
+    return partialclass(fn_or_cls, *args, **kwargs)
+  else:
+    return functools.partial(fn_or_cls, *args, **kwargs)