Instruction:
Can you write a function in Python 3 where it
returns True if fn_or_cls has a parameter named by arg_name.

Response:
def _might_have_parameter(fn_or_cls, arg_name):
  """Returns True if `arg_name` might be a valid parameter for `fn_or_cls`.

  Specifically, this means that `fn_or_cls` either has a parameter named
  `arg_name`, or has a `**kwargs` parameter.

  Args:
    fn_or_cls: The function or class to check.
    arg_name: The name fo the parameter.

  Returns:
    Whether `arg_name` might be a valid argument of `fn`.
  """
  if inspect.isclass(fn_or_cls):
    fn = _find_class_construction_fn(fn_or_cls)
  else:
    fn = fn_or_cls

  while hasattr(fn, '__wrapped__'):
    fn = fn.__wrapped__
  arg_spec = _get_cached_arg_spec(fn)
  if six.PY3:
    if arg_spec.varkw:
      return True
    return arg_name in arg_spec.args or arg_name in arg_spec.kwonlyargs
  else:
    if arg_spec.keywords:
      return True
    return arg_name in arg_spec.args


Instruction:
Implement a function in Python 3 to
get cached argspec for fn.

Response:
def _get_cached_arg_spec(fn):
  """Gets cached argspec for `fn`."""

  arg_spec = _ARG_SPEC_CACHE.get(fn)
  if arg_spec is None:
    arg_spec_fn = inspect.getfullargspec if six.PY3 else inspect.getargspec
    try:
      arg_spec = arg_spec_fn(fn)
    except TypeError:
      # `fn` might be a callable object.
      arg_spec = arg_spec_fn(fn.__call__)
    _ARG_SPEC_CACHE[fn] = arg_spec
  return arg_spec


Instruction:
Can you implement a function in Python 3 that
returns the names of the supplied positional arguments to the given function.

Response:
def _get_supplied_positional_parameter_names(fn, args):
  """Returns the names of the supplied arguments to the given function."""
  arg_spec = _get_cached_arg_spec(fn)
  # May be shorter than len(args) if args contains vararg (*args) arguments.
  return arg_spec.args[:len(args)]


Instruction:
Given the following Python 3 function, write the documentation
def _get_all_positional_parameter_names(fn):
  arg_spec = _get_cached_arg_spec(fn)
  args = arg_spec.args
  if arg_spec.defaults:
    args = args[:-len(arg_spec.defaults)]
  return args

Response: Returns the names of all positional arguments to the given function.


Instruction:
Can you implement a function in Python 3 that
retrieves all default values for configurable parameters of a function.

Response:
def _get_default_configurable_parameter_values(fn, whitelist, blacklist):
  """Retrieve all default values for configurable parameters of a function.

  Any parameters included in the supplied blacklist, or not included in the
  supplied whitelist, are excluded.

  Args:
    fn: The function whose parameter values should be retrieved.
    whitelist: The whitelist (or `None`) associated with the function.
    blacklist: The blacklist (or `None`) associated with the function.

  Returns:
    A dictionary mapping configurable parameter names to their default values.
  """
  arg_vals = _ARG_DEFAULTS_CACHE.get(fn)
  if arg_vals is not None:
    return arg_vals.copy()

  # First, grab any default values not captured in the kwargs var.
  arg_spec = _get_cached_arg_spec(fn)
  if arg_spec.defaults:
    default_kwarg_names = arg_spec.args[-len(arg_spec.defaults):]
    arg_vals = dict(zip(default_kwarg_names, arg_spec.defaults))
  else:
    arg_vals = {}

  if six.PY3 and arg_spec.kwonlydefaults:
    arg_vals.update(arg_spec.kwonlydefaults)

  # Now, eliminate keywords that are blacklisted, or aren't whitelisted (if
  # there's a whitelist), or aren't representable as a literal value.
  for k in list(six.iterkeys(arg_vals)):
    whitelist_fail = whitelist and k not in whitelist
    blacklist_fail = blacklist and k in blacklist
    representable = _is_literally_representable(arg_vals[k])
    if whitelist_fail or blacklist_fail or not representable:
      del arg_vals[k]

  _ARG_DEFAULTS_CACHE[fn] = arg_vals
  return arg_vals.copy()


Instruction:
Create a Python 3 function to
open a new explicit configuration scope.

Response:
def config_scope(name_or_scope):
  """Opens a new configuration scope.

  Provides a context manager that opens a new explicit configuration
  scope. Explicit configuration scopes restrict parameter bindings to only
  certain sections of code that run within the scope. Scopes can be nested to
  arbitrary depth; any configurable functions called within a scope inherit
  parameters defined by higher level scopes.

  For example, suppose a function named `preprocess_images` is called in two
  places in a codebase: Once when loading data for a training task, and once
  when loading data for an evaluation task:

      def load_training_data():
        ...
        with gin.config_scope('train'):
          images = preprocess_images(images)
        ...

      def load_eval_data():
        ...
        with gin.config_scope('eval'):
          images = preprocess_images(images)
        ...

  By using a `config_scope` to wrap each invocation of `preprocess_images` as
  above, it is possible to use Gin to supply specific parameters to each. Here
  is a possible configuration for the above example:

      preprocess_images.crop_size = [64, 64]
      preprocess_images.normalize_image = True

      train/preprocess_images.crop_location = 'random'
      train/preprocess_images.random_flip_lr = True

      eval/preprocess_images.crop_location = 'center'

  The `crop_size` and `normalize_image` parameters above will be shared by both
  the `train` and `eval` invocations; only `train` will receive
  `random_flip_lr`, and the two invocations receive different values for
  `crop_location`.

  Passing `None` or `''` to `config_scope` will temporarily clear all currently
  active scopes (within the `with` block; they will be restored afterwards).

  Args:
    name_or_scope: A name for the config scope, or an existing scope (e.g.,
      captured from `with gin.config_scope(...) as scope`), or `None` to clear
      currently active scopes.

  Raises:
    ValueError: If `name_or_scope` is not a list, string, or None.

  Yields:
    The resulting config scope (a list of all active scope names, ordered from
    outermost to innermost).
  """
  try:
    valid_value = True
    if isinstance(name_or_scope, list):
      new_scope = name_or_scope
    elif name_or_scope and isinstance(name_or_scope, six.string_types):
      new_scope = current_scope()  # Returns a copy.
      new_scope.extend(name_or_scope.split('/'))
    else:
      valid_value = name_or_scope in (None, '')
      new_scope = []

    # Append new_scope first. It will be popped in the finally block if an
    # exception is raised below.
    _ACTIVE_SCOPES.append(new_scope)

    scopes_are_valid = map(config_parser.MODULE_RE.match, new_scope)
    if not valid_value or not all(scopes_are_valid):
      err_str = 'Invalid value for `name_or_scope`: {}.'
      raise ValueError(err_str.format(name_or_scope))

    yield new_scope
  finally:
    _ACTIVE_SCOPES.pop()


Instruction:
Make a summary of the following Python 3 code
def _make_configurable(fn_or_cls,
                       name=None,
                       module=None,
                       whitelist=None,
                       blacklist=None,
                       subclass=False):
  """Wraps `fn_or_cls` to make it configurable.

  Infers the configurable name from `fn_or_cls.__name__` if necessary, and
  updates global state to keep track of configurable name <-> function
  mappings, as well as whitelisted and blacklisted parameters.

  Args:
    fn_or_cls: The function or class to decorate.
    name: A name for the configurable. If `None`, the name will be inferred from
      from `fn_or_cls`. The `name` may also include module components to be used
      for disambiguation (these will be appended to any components explicitly
      specified by `module`).
    module: The module to associate with the configurable, to help handle naming
      collisions. If `None`, `fn_or_cls.__module__` will be used (if no module
      is specified as part of `name`).
    whitelist: A whitelisted set of parameter names to supply values for.
    blacklist: A blacklisted set of parameter names not to supply values for.
    subclass: If `fn_or_cls` is a class and `subclass` is `True`, decorate by
      subclassing `fn_or_cls` and overriding its `__init__` method. If `False`,
      replace the existing `__init__` with a decorated version.

  Returns:
    A wrapped version of `fn_or_cls` that will take parameter values from the
    global configuration.

  Raises:
    RuntimeError: If the config is locked.
    ValueError: If a configurable with `name` (or the name of `fn_or_cls`)
      already exists, or if both a whitelist and blacklist are specified.
  """
  if config_is_locked():
    err_str = 'Attempted to add a new configurable after the config was locked.'
    raise RuntimeError(err_str)

  name = fn_or_cls.__name__ if name is None else name
  if config_parser.IDENTIFIER_RE.match(name):
    default_module = getattr(fn_or_cls, '__module__', None)
    module = default_module if module is None else module
  elif not config_parser.MODULE_RE.match(name):
    raise ValueError("Configurable name '{}' is invalid.".format(name))

  if module is not None and not config_parser.MODULE_RE.match(module):
    raise ValueError("Module '{}' is invalid.".format(module))

  selector = module + '.' + name if module else name
  if not _INTERACTIVE_MODE and selector in _REGISTRY:
    err_str = "A configurable matching '{}' already exists."
    raise ValueError(err_str.format(selector))

  if whitelist and blacklist:
    err_str = 'A whitelist or a blacklist can be specified, but not both.'
    raise ValueError(err_str)

  if whitelist and not isinstance(whitelist, (list, tuple)):
    raise TypeError('Whitelist should be a list or tuple.')

  if blacklist and not isinstance(blacklist, (list, tuple)):
    raise TypeError('Blacklist should be a list or tuple.')

  _validate_parameters(fn_or_cls, whitelist, 'whitelist')
  _validate_parameters(fn_or_cls, blacklist, 'blacklist')

  def apply_config(fn):
    """Wraps `fn` so that it obtains parameters from the configuration."""

    @six.wraps(fn)
    def wrapper(*args, **kwargs):
      """Supplies fn with parameter values from the configuration."""
      scope_components = current_scope()
      new_kwargs = {}
      for i in range(len(scope_components) + 1):
        partial_scope_str = '/'.join(scope_components[:i])
        new_kwargs.update(_CONFIG.get((partial_scope_str, selector), {}))
      gin_bound_args = list(new_kwargs.keys())
      scope_str = partial_scope_str

      arg_names = _get_supplied_positional_parameter_names(fn, args)

      for arg in args[len(arg_names):]:
        if arg is REQUIRED:
          raise ValueError(
              'gin.REQUIRED is not allowed for unnamed (vararg) parameters. If '
              'the function being called is wrapped by a non-Gin decorator, '
              'try explicitly providing argument names for positional '
              'parameters.')

      required_arg_names = []
      required_arg_indexes = []
      for i, arg in enumerate(args[:len(arg_names)]):
        if arg is REQUIRED:
          required_arg_names.append(arg_names[i])
          required_arg_indexes.append(i)

      required_kwargs = []
      for kwarg, value in six.iteritems(kwargs):
        if value is REQUIRED:
          required_kwargs.append(kwarg)

      # If the caller passed arguments as positional arguments that correspond
      # to a keyword arg in new_kwargs, remove the keyword argument from
      # new_kwargs to let the caller win and avoid throwing an error. Unless it
      # is an arg marked as REQUIRED.
      for arg_name in arg_names:
        if arg_name not in required_arg_names:
          new_kwargs.pop(arg_name, None)

      # Get default values for configurable parameters.
      operative_parameter_values = _get_default_configurable_parameter_values(
          fn, whitelist, blacklist)
      # Update with the values supplied via configuration.
      operative_parameter_values.update(new_kwargs)

      # Remove any values from the operative config that are overridden by the
      # caller. These can't be configured, so they won't be logged. We skip
      # values that are marked as REQUIRED.
      for k in arg_names:
        if k not in required_arg_names:
          operative_parameter_values.pop(k, None)
      for k in kwargs:
        if k not in required_kwargs:
          operative_parameter_values.pop(k, None)

      # An update is performed in case another caller of this same configurable
      # object has supplied a different set of arguments. By doing an update, a
      # Gin-supplied or default value will be present if it was used (not
      # overridden by the caller) at least once.
      _OPERATIVE_CONFIG.setdefault((scope_str, selector), {}).update(
          operative_parameter_values)

      # We call deepcopy for two reasons: First, to prevent the called function
      # from modifying any of the values in `_CONFIG` through references passed
      # in via `new_kwargs`; Second, to facilitate evaluation of any
      # `ConfigurableReference` instances buried somewhere inside
      # `new_kwargs`. See the docstring on `ConfigurableReference.__deepcopy__`
      # above for more details on the dark magic happening here.
      new_kwargs = copy.deepcopy(new_kwargs)

      # Validate args marked as REQUIRED have been bound in the Gin config.
      missing_required_params = []
      new_args = list(args)
      for i, arg_name in zip(required_arg_indexes, required_arg_names):
        if arg_name not in new_kwargs:
          missing_required_params.append(arg_name)
        else:
          new_args[i] = new_kwargs.pop(arg_name)

      # Validate kwargs marked as REQUIRED have been bound in the Gin config.
      for kwarg in required_kwargs:
        if kwarg not in new_kwargs:
          missing_required_params.append(kwarg)
        else:
          # Remove from kwargs and let the new_kwargs value be used.
          kwargs.pop(kwarg)

      if missing_required_params:
        err_str = 'Required bindings for `{}` not provided in config: {}'
        minimal_selector = _REGISTRY.minimal_selector(selector)
        err_str = err_str.format(minimal_selector, missing_required_params)
        raise RuntimeError(err_str)

      # Now, update with the caller-supplied `kwargs`, allowing the caller to
      # have the final say on keyword argument values.
      new_kwargs.update(kwargs)

      try:
        return fn(*new_args, **new_kwargs)
      except Exception as e:  # pylint: disable=broad-except
        err_str = ''
        if isinstance(e, TypeError):
          all_arg_names = _get_all_positional_parameter_names(fn)
          if len(new_args) < len(all_arg_names):
            unbound_positional_args = list(
                set(all_arg_names[len(new_args):]) - set(new_kwargs))
            if unbound_positional_args:
              caller_supplied_args = list(
                  set(arg_names + list(kwargs)) -
                  set(required_arg_names + list(required_kwargs)))
              fmt = ('\n  No values supplied by Gin or caller for arguments: {}'
                     '\n  Gin had values bound for: {gin_bound_args}'
                     '\n  Caller supplied values for: {caller_supplied_args}')
              canonicalize = lambda x: list(map(str, sorted(x)))
              err_str += fmt.format(
                  canonicalize(unbound_positional_args),
                  gin_bound_args=canonicalize(gin_bound_args),
                  caller_supplied_args=canonicalize(caller_supplied_args))
        err_str += "\n  In call to configurable '{}' ({}){}"
        scope_info = " in scope '{}'".format(scope_str) if scope_str else ''
        err_str = err_str.format(name, fn, scope_info)
        utils.augment_exception_message_and_reraise(e, err_str)

    return wrapper

  decorated_fn_or_cls = _decorate_fn_or_cls(
      apply_config, fn_or_cls, subclass=subclass)

  _REGISTRY[selector] = Configurable(
      decorated_fn_or_cls,
      name=name,
      module=module,
      whitelist=whitelist,
      blacklist=blacklist,
      selector=selector)
  return decorated_fn_or_cls

Response: Wraps fn_or_cls to make a configurable.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def external_configurable(fn_or_cls,
                          name=None,
                          module=None,
                          whitelist=None,
                          blacklist=None):
  """Allow referencing/configuring an external class or function.

  This alerts Gin to the existence of the class or function `fn_or_cls` in the
  event that it can't be easily annotated with `@configurable` (for instance, if
  it is from another project). This allows `fn_or_cls` to be configured and
  referenced (using the `@name` notation) via parameter binding strings.

  Note that only calls to the return value of this function or resulting from
  references to `fn_or_cls` made through binding strings (configurations) will
  have their parameters injected by Gin---explicit calls to `fn_or_cls` directly
  won't have any parameter bindings applied.

  Args:
    fn_or_cls: The external function or class that should be made configurable.
    name: The configurable name to be associated with `fn_or_cls`. The name may
      also include module components to be used for disambiguation (these will
      be appended to any components explicitly specified by `module`).
    module: The module to associate with the configurable, to help handle naming
      collisions. By default, `fn_or_cls.__module__` will be used (if no
      module is specified as part of the name).
    whitelist: A whitelist of parameter names to allow configuration for.
    blacklist: A blacklist of parameter names not to allow configuration for.

  Returns:
    A decorated version of `fn_or_cls` that permits parameter binding. For
    functions, this is just a wrapped version of the function. For classes, this
    is a carefully constructed subclass of `fn_or_cls` designed to behave nearly
    identically (even under many type inspection operations) save for the
    addition of parameter binding.
  """
  return _make_configurable(
      fn_or_cls,
      name=name,
      module=module,
      whitelist=whitelist,
      blacklist=blacklist,
      subclass=True)

Response: Allow referencing or configuring an external function or class or function.


Instruction:
Given the following Python 3 function, write the documentation
def operative_config_str(max_line_length=80, continuation_indent=4):
  def format_binding(key, value):
    """Pretty print the given key/value pair."""
    formatted_val = pprint.pformat(
        value, width=(max_line_length - continuation_indent))
    formatted_val_lines = formatted_val.split('\n')
    if (len(formatted_val_lines) == 1 and
        len(key + formatted_val) <= max_line_length):
      output = '{} = {}'.format(key, formatted_val)
    else:
      indented_formatted_val = '\n'.join(
          [' ' * continuation_indent + line for line in formatted_val_lines])
      output = '{} = \\\n{}'.format(key, indented_formatted_val)
    return output

  def sort_key(key_tuple):
    """Sort configurable selector/innermost scopes, ignoring case."""
    scope, selector = key_tuple[0]
    parts = selector.lower().split('.')[::-1] + scope.lower().split('/')[::-1]
    return '/'.join(parts)

  # Build the output as an array of formatted Gin statements. Each statement may
  # span multiple lines. Imports are first, followed by macros, and finally all
  # other bindings sorted in alphabetical order by configurable name.
  formatted_statements = [
      'import {}'.format(module) for module in sorted(_IMPORTED_MODULES)
  ]
  if formatted_statements:
    formatted_statements.append('')

  macros = {}
  for (scope, selector), config in six.iteritems(_OPERATIVE_CONFIG):
    if _REGISTRY[selector].fn_or_cls == macro:
      macros[scope, selector] = config
  if macros:
    formatted_statements.append('# Macros:')
    formatted_statements.append('# ' + '=' * (max_line_length - 2))
  for (name, _), config in sorted(macros.items(), key=sort_key):
    binding = format_binding(name, config['value'])
    formatted_statements.append(binding)
  if macros:
    formatted_statements.append('')

  sorted_items = sorted(_OPERATIVE_CONFIG.items(), key=sort_key)
  for (scope, selector), config in sorted_items:
    configurable_ = _REGISTRY[selector]

    fn = configurable_.fn_or_cls
    if fn == macro or fn == _retrieve_constant:
      continue

    minimal_selector = _REGISTRY.minimal_selector(configurable_.selector)
    scoped_selector = (scope + '/' if scope else '') + minimal_selector
    parameters = [(k, v) for k, v in six.iteritems(config)
                  if _is_literally_representable(v)]
    formatted_statements.append('# Parameters for {}:'.format(scoped_selector))
    formatted_statements.append('# ' + '=' * (max_line_length - 2))
    for arg, val in sorted(parameters):
      binding = format_binding('{}.{}'.format(scoped_selector, arg), val)
      formatted_statements.append(binding)
    if not parameters:
      formatted_statements.append('# None.')
    formatted_statements.append('')

  return '\n'.join(formatted_statements)

Response: Return the operative configuration string that can be used by a program.


Instruction:
Given the following Python 3 function, write the documentation
def parse_config(bindings, skip_unknown=False):
  if isinstance(bindings, (list, tuple)):
    bindings = '\n'.join(bindings)

  _validate_skip_unknown(skip_unknown)
  if isinstance(skip_unknown, (list, tuple)):
    skip_unknown = set(skip_unknown)

  parser = config_parser.ConfigParser(bindings, ParserDelegate(skip_unknown))
  for statement in parser:
    if isinstance(statement, config_parser.BindingStatement):
      scope, selector, arg_name, value, location = statement
      if not arg_name:
        macro_name = '{}/{}'.format(scope, selector) if scope else selector
        with utils.try_with_location(location):
          bind_parameter((macro_name, 'gin.macro', 'value'), value)
        continue
      if not _should_skip(selector, skip_unknown):
        with utils.try_with_location(location):
          bind_parameter((scope, selector, arg_name), value)
    elif isinstance(statement, config_parser.ImportStatement):
      if skip_unknown:
        try:
          __import__(statement.module)
          _IMPORTED_MODULES.add(statement.module)
        except ImportError:
          log_str = 'Skipping import of unknown module `%s` (skip_unknown=%r).'
          logging.info(log_str, statement.module, skip_unknown)
      else:
        with utils.try_with_location(statement.location):
          __import__(statement.module)
        _IMPORTED_MODULES.add(statement.module)
    elif isinstance(statement, config_parser.IncludeStatement):
      with utils.try_with_location(statement.location):
        parse_config_file(statement.filename, skip_unknown)
    else:
      raise AssertionError('Unrecognized statement type {}.'.format(statement))

Response: Parses a file string or list of parameter bindings and sets the global configuration of the configurable functions.


Instruction:
How would you explain what the following Python 3 function does
def register_file_reader(*args):
  def do_registration(file_reader_fn, is_readable_fn):
    if file_reader_fn not in list(zip(*_FILE_READERS))[0]:
      _FILE_READERS.append((file_reader_fn, is_readable_fn))

  if len(args) == 1:  # It's a decorator.
    return functools.partial(do_registration, is_readable_fn=args[0])
  elif len(args) == 2:
    do_registration(*args)
  else:  # 0 or > 2 arguments supplied.
    err_str = 'register_file_reader() takes 1 or 2 arguments ({} given)'
    raise TypeError(err_str.format(len(args)))

Response: Register a file reader for use in parse_config_file.


Instruction:
How would you code a function in Python 3 to
parse a Gin config file.

Response:
def parse_config_file(config_file, skip_unknown=False):
  """Parse a Gin config file.

  Args:
    config_file: The path to a Gin config file.
    skip_unknown: A boolean indicating whether unknown configurables and imports
      should be skipped instead of causing errors (alternatively a list of
      configurable names to skip if unknown). See `parse_config` for additional
      details.

  Raises:
    IOError: If `config_file` cannot be read using any register file reader.
  """
  for reader, existence_check in _FILE_READERS:
    if existence_check(config_file):
      with reader(config_file) as f:
        parse_config(f, skip_unknown=skip_unknown)
        return
  raise IOError('Unable to open file: {}'.format(config_file))


Instruction:
Write a Python 3 script for
parsing a list of config files followed by extra Gin bindings.

Response:
def parse_config_files_and_bindings(config_files,
                                    bindings,
                                    finalize_config=True,
                                    skip_unknown=False):
  """Parse a list of config files followed by extra Gin bindings.

  This function is equivalent to:

      for config_file in config_files:
        gin.parse_config_file(config_file, skip_configurables)
      gin.parse_config(bindings, skip_configurables)
      if finalize_config:
        gin.finalize()

  Args:
    config_files: A list of paths to the Gin config files.
    bindings: A list of individual parameter binding strings.
    finalize_config: Whether to finalize the config after parsing and binding
      (defaults to True).
    skip_unknown: A boolean indicating whether unknown configurables and imports
      should be skipped instead of causing errors (alternatively a list of
      configurable names to skip if unknown). See `parse_config` for additional
      details.
  """
  if config_files is None:
    config_files = []
  if bindings is None:
    bindings = ''
  for config_file in config_files:
    parse_config_file(config_file, skip_unknown)
  parse_config(bindings, skip_unknown)
  if finalize_config:
    finalize()


Instruction:
How would you implement a function in Python 3 that
parses and return a single Gin value.

Response:
def parse_value(value):
  """Parse and return a single Gin value."""
  if not isinstance(value, six.string_types):
    raise ValueError('value ({}) should be a string type.'.format(value))
  return config_parser.ConfigParser(value, ParserDelegate()).parse_value()


Instruction:
Here you have a function in Python 3, explain what it does
def finalize():
  if config_is_locked():
    raise RuntimeError('Finalize called twice (config already locked).')

  bindings = {}
  for hook in _FINALIZE_HOOKS:
    new_bindings = hook(_CONFIG)
    if new_bindings is not None:
      for key, value in six.iteritems(new_bindings):
        pbk = ParsedBindingKey(key)
        if pbk in bindings:
          err_str = 'Received conflicting updates when running {}.'
          raise ValueError(err_str.format(hook))
        bindings[pbk] = value

  for pbk, value in six.iteritems(bindings):
    bind_parameter(pbk, value)

  _set_config_is_locked(True)

Response: A function that should be called after parsing all Gin config files.


Instruction:
Can you create a Python 3 function that
provides an iterator over all values in a nested structure.

Response:
def _iterate_flattened_values(value):
  """Provides an iterator over all values in a nested structure."""
  if isinstance(value, six.string_types):
    yield value
    return

  if isinstance(value, collections.Mapping):
    value = collections.ValuesView(value)

  if isinstance(value, collections.Iterable):
    for nested_value in value:
      for nested_nested_value in _iterate_flattened_values(nested_value):
        yield nested_nested_value

  yield value


Instruction:
How would you implement a function in Python 3 that
returns an iterator over all the references in the given config.

Response:
def iterate_references(config, to=None):
  """Provides an iterator over references in the given config.

  Args:
    config: A dictionary mapping scoped configurable names to argument bindings.
    to: If supplied, only yield references whose `configurable_fn` matches `to`.

  Yields:
    `ConfigurableReference` instances within `config`, maybe restricted to those
    matching the `to` parameter if it is supplied.
  """
  for value in _iterate_flattened_values(config):
    if isinstance(value, ConfigurableReference):
      if to is None or value.configurable.fn_or_cls == to:
        yield value


Instruction:
Implement a Python 3 function for
creating a constant that can be referenced from gin config files.

Response:
def constant(name, value):
  """Creates a constant that can be referenced from gin config files.

  After calling this function in Python, the constant can be referenced from
  within a Gin config file using the macro syntax. For example, in Python:

      gin.constant('THE_ANSWER', 42)

  Then, in a Gin config file:

      meaning.of_life = %THE_ANSWER

  Note that any Python object can be used as the value of a constant (including
  objects not representable as Gin literals). Values will be stored until
  program termination in a Gin-internal dictionary, so avoid creating constants
  with values that should have a limited lifetime.

  Optionally, a disambiguating module may be prefixed onto the constant
  name. For instance:

      gin.constant('some.modules.PI', 3.14159)

  Args:
    name: The name of the constant, possibly prepended by one or more
      disambiguating module components separated by periods. An macro with this
      name (including the modules) will be created.
    value: The value of the constant. This can be anything (including objects
      not representable as Gin literals). The value will be stored and returned
      whenever the constant is referenced.

  Raises:
    ValueError: If the constant's selector is invalid, or a constant with the
      given selector already exists.
  """
  if not config_parser.MODULE_RE.match(name):
    raise ValueError("Invalid constant selector '{}'.".format(name))

  if _CONSTANTS.matching_selectors(name):
    err_str = "Constants matching selector '{}' already exist ({})."
    raise ValueError(err_str.format(name, _CONSTANTS.matching_selectors(name)))

  _CONSTANTS[name] = value


Instruction:
Given the following Python 3 function, write the documentation
def find_unknown_references_hook(config):
  additional_msg_fmt = " In binding for '{}'."
  for (scope, selector), param_bindings in six.iteritems(config):
    for param_name, param_value in six.iteritems(param_bindings):
      for maybe_unknown in _iterate_flattened_values(param_value):
        if isinstance(maybe_unknown, _UnknownConfigurableReference):
          scope_str = scope + '/' if scope else ''
          min_selector = _REGISTRY.minimal_selector(selector)
          binding_key = '{}{}.{}'.format(scope_str, min_selector, param_name)
          additional_msg = additional_msg_fmt.format(binding_key)
          _raise_unknown_reference_error(maybe_unknown, additional_msg)

Response: Hook to find unknown configurables.


Instruction:
How would you code a function in Python 3 to
retrieve all selectors matching the given partial_selector.

Response:
def matching_selectors(self, partial_selector):
    """Retrieves all selectors matching `partial_selector`.

    For instance, if "one.a.b" and "two.a.b" are stored in a `SelectorMap`, both
    `matching_selectors('b')` and `matching_selectors('a.b')` will return them.

    In the event that `partial_selector` exactly matches an existing complete
    selector, only that complete selector is returned. For instance, if
    "a.b.c.d" and "c.d" are stored, `matching_selectors('c.d')` will return only
    `['c.d']`, while `matching_selectors('d')` will return both.

    Args:
      partial_selector: The partial selector to find matches for.

    Returns:
      A list of selectors matching `partial_selector`.
    """
    if partial_selector in self._selector_map:
      return [partial_selector]

    selector_components = partial_selector.split('.')
    node = self._selector_tree

    for component in reversed(selector_components):
      if component not in node:
        return []
      node = node[component]

    selectors = []
    dfs_stack = [node]
    while dfs_stack:
      node = dfs_stack.pop().copy()
      selector = node.pop(_TERMINAL_KEY, None)
      dfs_stack.extend(node.values())
      if selector:
        selectors.append(selector)

    return selectors


Instruction:
Write a Python 3 script to
get a value matching the given partial_selector.

Response:
def get_match(self, partial_selector, default=None):
    """Gets a (single) value matching `partial_selector`.

    If the partial_selector exactly matches a complete selector, the value
    associated with the complete selector is returned.

    Args:
      partial_selector: The partial selector to find values for.
      default: A default value to return if nothing matches `partial_selector`.

    Returns:
      The value associated with `partial_selector` if it exists, else `default`.

    Raises:
      KeyError: If `partial_selector` matches more than one selector in the map.
    """
    matching_selectors = self.matching_selectors(partial_selector)
    if not matching_selectors:
      return default
    if len(matching_selectors) > 1:
      err_str = "Ambiguous selector '{}', matches {}."
      raise KeyError(err_str.format(partial_selector, matching_selectors))
    return self._selector_map[matching_selectors[0]]


Instruction:
Explain what the following Python 3 code does
def get_all_matches(self, partial_selector):
    matching_selectors = self.matching_selectors(partial_selector)
    return [self._selector_map[selector] for selector in matching_selectors]

Response: Returns all values matching partial_selector as a list.


Instruction:
Write a Python 3 script for
returning the minimal selector that uniquely matches the given complete_selector.

Response:
def minimal_selector(self, complete_selector):
    """Returns the minimal selector that uniquely matches `complete_selector`.

    Args:
      complete_selector: A complete selector stored in the map.

    Returns:
      A partial selector that unambiguously matches `complete_selector`.

    Raises:
      KeyError: If `complete_selector` is not in the map.
    """
    if complete_selector not in self._selector_map:
      raise KeyError("No value with selector '{}'.".format(complete_selector))

    selector_components = complete_selector.split('.')
    node = self._selector_tree

    start = None
    for i, component in enumerate(reversed(selector_components)):
      if len(node) == 1:
        if start is None:
          start = -i  # Negative index, since we're iterating in reverse.
      else:
        start = None
      node = node[component]

    if len(node) > 1:  # The selector is a substring of another selector.
      return complete_selector
    return '.'.join(selector_components[start:])


Instruction:
How would you explain what the following Python 3 function does
def sp_search_query(query):

    result = []

    for (field, values) in query.items():
        field = SEARCH_FIELD_MAP.get(field, field)
        if field is None:
            continue

        for value in values:
            if field == 'year':
                value = _transform_year(value)
                if value is not None:
                    result.append('%s:%d' % (field, value))
            elif field == 'any':
                result.append('"%s"' % value)
            else:
                result.append('%s:"%s"' % (field, value))

    return ' '.join(result)

Response: Translate a Mopidy search query to a Spotify search query


Instruction:
Given the following Python 3 function, write the documentation
def _parse_retry_after(self, response):
        value = response.headers.get('Retry-After')

        if not value:
            seconds = 0
        elif re.match(r'^\s*[0-9]+\s*$', value):
            seconds = int(value)
        else:
            date_tuple = email.utils.parsedate(value)
            if date_tuple is None:
                seconds = 0
            else:
                seconds = time.mktime(date_tuple) - time.time()
        return max(0, seconds)

Response: Parse Retry - After header from response.


Instruction:
How would you code a function in Python 3 to
validate new property value before setting it.

Response:
def validate_value(self, value):
        """
        Validate new property value before setting it.

        value -- New value
        """
        if 'readOnly' in self.metadata and self.metadata['readOnly']:
            raise PropertyError('Read-only property')

        try:
            validate(value, self.metadata)
        except ValidationError:
            raise PropertyError('Invalid property value')


Instruction:
Can you tell what is the following Python 3 function doing
def as_property_description(self):
        description = deepcopy(self.metadata)

        if 'links' not in description:
            description['links'] = []

        description['links'].append(
            {
                'rel': 'property',
                'href': self.href_prefix + self.href,
            }
        )
        return description

Response: Returns the property description as a dictionary describing the property.


Instruction:
Explain what the following Python 3 code does
def set_value(self, value):
        self.validate_value(value)
        self.value.set(value)

Response: Set the current value of the property.


Instruction:
Implement a Python 3 function for
getting the thing at the given index.

Response:
def get_thing(self, idx):
        """
        Get the thing at the given index.

        idx -- the index
        """
        try:
            idx = int(idx)
        except ValueError:
            return None

        if idx < 0 or idx >= len(self.things):
            return None

        return self.things[idx]


Instruction:
Can you write a function in Python 3 where it
initializes the object with the given list of Things managed by this server.

Response:
def initialize(self, things, hosts):
        """
        Initialize the handler.

        things -- list of Things managed by this server
        hosts -- list of allowed hostnames
        """
        self.things = things
        self.hosts = hosts


Instruction:
Write a Python 3 function that can
set the default headers for all requests.

Response:
def set_default_headers(self, *args, **kwargs):
        """Set the default headers for all requests."""
        self.set_header('Access-Control-Allow-Origin', '*')
        self.set_header('Access-Control-Allow-Headers',
                        'Origin, X-Requested-With, Content-Type, Accept')
        self.set_header('Access-Control-Allow-Methods',
                        'GET, HEAD, PUT, POST, DELETE')


Instruction:
Write a Python 3 function for
handling a GET request.

Response:
def get(self):
        """
        Handle a GET request.

        property_name -- the name of the property from the URL path
        """
        self.set_header('Content-Type', 'application/json')
        ws_href = '{}://{}'.format(
            'wss' if self.request.protocol == 'https' else 'ws',
            self.request.headers.get('Host', '')
        )

        descriptions = []
        for thing in self.things.get_things():
            description = thing.as_thing_description()
            description['links'].append({
                'rel': 'alternate',
                'href': '{}{}'.format(ws_href, thing.get_href()),
            })
            descriptions.append(description)

        self.write(json.dumps(descriptions))


Instruction:
Can you implement a function in Python 3 that
handles a GET request including websocket requests.

Response:
def get(self, thing_id='0'):
        """
        Handle a GET request, including websocket requests.

        thing_id -- ID of the thing this request is for
        """
        self.thing = self.get_thing(thing_id)
        if self.thing is None:
            self.set_status(404)
            self.finish()
            return

        if self.request.headers.get('Upgrade', '').lower() == 'websocket':
            yield tornado.websocket.WebSocketHandler.get(self)
            return

        self.set_header('Content-Type', 'application/json')
        ws_href = '{}://{}'.format(
            'wss' if self.request.protocol == 'https' else 'ws',
            self.request.headers.get('Host', '')
        )

        description = self.thing.as_thing_description()
        description['links'].append({
            'rel': 'alternate',
            'href': '{}{}'.format(ws_href, self.thing.get_href()),
        })

        self.write(json.dumps(description))
        self.finish()


Instruction:
How would you implement a function in Python 3 that
handles an incoming message.

Response:
def on_message(self, message):
        """
        Handle an incoming message.

        message -- message to handle
        """
        try:
            message = json.loads(message)
        except ValueError:
            try:
                self.write_message(json.dumps({
                    'messageType': 'error',
                    'data': {
                        'status': '400 Bad Request',
                        'message': 'Parsing request failed',
                    },
                }))
            except tornado.websocket.WebSocketClosedError:
                pass

            return

        if 'messageType' not in message or 'data' not in message:
            try:
                self.write_message(json.dumps({
                    'messageType': 'error',
                    'data': {
                        'status': '400 Bad Request',
                        'message': 'Invalid message',
                    },
                }))
            except tornado.websocket.WebSocketClosedError:
                pass

            return

        msg_type = message['messageType']
        if msg_type == 'setProperty':
            for property_name, property_value in message['data'].items():
                try:
                    self.thing.set_property(property_name, property_value)
                except PropertyError as e:
                    self.write_message(json.dumps({
                        'messageType': 'error',
                        'data': {
                            'status': '400 Bad Request',
                            'message': str(e),
                        },
                    }))
        elif msg_type == 'requestAction':
            for action_name, action_params in message['data'].items():
                input_ = None
                if 'input' in action_params:
                    input_ = action_params['input']

                action = self.thing.perform_action(action_name, input_)
                if action:
                    tornado.ioloop.IOLoop.current().spawn_callback(
                        perform_action,
                        action,
                    )
                else:
                    self.write_message(json.dumps({
                        'messageType': 'error',
                        'data': {
                            'status': '400 Bad Request',
                            'message': 'Invalid action request',
                            'request': message,
                        },
                    }))
        elif msg_type == 'addEventSubscription':
            for event_name in message['data'].keys():
                self.thing.add_event_subscriber(event_name, self)
        else:
            try:
                self.write_message(json.dumps({
                    'messageType': 'error',
                    'data': {
                        'status': '400 Bad Request',
                        'message': 'Unknown messageType: ' + msg_type,
                        'request': message,
                    },
                }))
            except tornado.websocket.WebSocketClosedError:
                pass


Instruction:
Can you generate the documentation for the following Python 3 function
def get(self, thing_id='0', property_name=None):
        thing = self.get_thing(thing_id)
        if thing is None:
            self.set_status(404)
            return

        if thing.has_property(property_name):
            self.set_header('Content-Type', 'application/json')
            self.write(json.dumps({
                property_name: thing.get_property(property_name),
            }))
        else:
            self.set_status(404)

Response: Handle a GET request.


Instruction:
How would you implement a function in Python 3 that
handles a PUT request for a specific thing.

Response:
def put(self, thing_id='0', property_name=None):
        """
        Handle a PUT request.

        thing_id -- ID of the thing this request is for
        property_name -- the name of the property from the URL path
        """
        thing = self.get_thing(thing_id)
        if thing is None:
            self.set_status(404)
            return

        try:
            args = json.loads(self.request.body.decode())
        except ValueError:
            self.set_status(400)
            return

        if property_name not in args:
            self.set_status(400)
            return

        if thing.has_property(property_name):
            try:
                thing.set_property(property_name, args[property_name])
            except PropertyError:
                self.set_status(400)
                return

            self.set_header('Content-Type', 'application/json')
            self.write(json.dumps({
                property_name: thing.get_property(property_name),
            }))
        else:
            self.set_status(404)


Instruction:
Write a Python 3 script for
handling a POST request.

Response:
def post(self, thing_id='0'):
        """
        Handle a POST request.

        thing_id -- ID of the thing this request is for
        """
        thing = self.get_thing(thing_id)
        if thing is None:
            self.set_status(404)
            return

        try:
            message = json.loads(self.request.body.decode())
        except ValueError:
            self.set_status(400)
            return

        response = {}
        for action_name, action_params in message.items():
            input_ = None
            if 'input' in action_params:
                input_ = action_params['input']

            action = thing.perform_action(action_name, input_)
            if action:
                response.update(action.as_action_description())

                # Start the action
                tornado.ioloop.IOLoop.current().spawn_callback(
                    perform_action,
                    action,
                )

        self.set_status(201)
        self.write(json.dumps(response))


Instruction:
Here you have a function in Python 3, explain what it does
def get(self, thing_id='0', action_name=None, action_id=None):
        thing = self.get_thing(thing_id)
        if thing is None:
            self.set_status(404)
            return

        action = thing.get_action(action_name, action_id)
        if action is None:
            self.set_status(404)
            return

        self.set_header('Content-Type', 'application/json')
        self.write(json.dumps(action.as_action_description()))

Response: Handle a GET request.


Instruction:
How would you explain what the following Python 3 function does
def put(self, thing_id='0', action_name=None, action_id=None):
        thing = self.get_thing(thing_id)
        if thing is None:
            self.set_status(404)
            return

        self.set_status(200)

Response: Handle a PUT request.


Instruction:
Given the following Python 3 function, write the documentation
def delete(self, thing_id='0', action_name=None, action_id=None):
        thing = self.get_thing(thing_id)
        if thing is None:
            self.set_status(404)
            return

        if thing.remove_action(action_name, action_id):
            self.set_status(204)
        else:
            self.set_status(404)

Response: Handle a DELETE request.


Instruction:
Explain what the following Python 3 code does
def get(self, thing_id='0'):
        thing = self.get_thing(thing_id)
        if thing is None:
            self.set_status(404)
            return

        self.set_header('Content-Type', 'application/json')
        self.write(json.dumps(thing.get_event_descriptions()))

Response: Handle a GET request.


Instruction:
Here you have a function in Python 3, explain what it does
def start(self):
        self.service_info = ServiceInfo(
            '_webthing._tcp.local.',
            '{}._webthing._tcp.local.'.format(self.name),
            address=socket.inet_aton(get_ip()),
            port=self.port,
            properties={
                'path': '/',
            },
            server='{}.local.'.format(socket.gethostname()))
        self.zeroconf = Zeroconf()
        self.zeroconf.register_service(self.service_info)

        self.server.listen(self.port)
        tornado.ioloop.IOLoop.current().start()

Response: Start listening for incoming connections.


Instruction:
Can you tell what is the following Python 3 function doing
def stop(self):
        self.zeroconf.unregister_service(self.service_info)
        self.zeroconf.close()
        self.server.stop()

Response: Stop listening for new services.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def as_action_description(self):
        description = {
            self.name: {
                'href': self.href_prefix + self.href,
                'timeRequested': self.time_requested,
                'status': self.status,
            },
        }

        if self.input is not None:
            description[self.name]['input'] = self.input

        if self.time_completed is not None:
            description[self.name]['timeCompleted'] = self.time_completed

        return description

Response: Returns the action description as a dictionary.


Instruction:
Here you have a function in Python 3, explain what it does
def start(self):
        self.status = 'pending'
        self.thing.action_notify(self)
        self.perform_action()
        self.finish()

Response: Start performing the action.


Instruction:
Can you generate the documentation for the following Python 3 function
def finish(self):
        self.status = 'completed'
        self.time_completed = timestamp()
        self.thing.action_notify(self)

Response: Finish performing the action.


Instruction:
Create a Python 3 function to
return the event description as a dictionary.

Response:
def as_event_description(self):
        """
        Get the event description.

        Returns a dictionary describing the event.
        """
        description = {
            self.name: {
                'timestamp': self.time,
            },
        }

        if self.data is not None:
            description[self.name]['data'] = self.data

        return description


Instruction:
Here you have a function in Python 3, explain what it does
def get_ip():
    s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
    try:
        s.connect(('10.255.255.255', 1))
        ip = s.getsockname()[0]
    except (socket.error, IndexError):
        ip = '127.0.0.1'
    finally:
        s.close()

    return ip

Response: Get the default IP address.


Instruction:
Write a Python 3 function that can
get all IP addresses.

Response:
def get_addresses():
    """
    Get all IP addresses.

    Returns list of addresses.
    """
    addresses = set()

    for iface in ifaddr.get_adapters():
        for addr in iface.ips:
            # Filter out link-local addresses.
            if addr.is_IPv4:
                ip = addr.ip

                if not ip.startswith('169.254.'):
                    addresses.add(ip)
            elif addr.is_IPv6:
                # Sometimes, IPv6 addresses will have the interface name
                # appended, e.g. %eth0. Handle that.
                ip = addr.ip[0].split('%')[0].lower()

                if not ip.startswith('fe80:'):
                    addresses.add('[{}]'.format(ip))

    return sorted(list(addresses))


Instruction:
Here you have a function in Python 3, explain what it does
def set(self, value):
        if self.value_forwarder is not None:
            self.value_forwarder(value)

        self.notify_of_external_update(value)

Response: Set a new value for this thing.


Instruction:
Explain what the following Python 3 code does
def notify_of_external_update(self, value):
        if value is not None and value != self.last_value:
            self.last_value = value
            self.emit('update', value)

Response: Notify observers of a new value.


Instruction:
Here you have a function in Python 3, explain what it does
def as_thing_description(self):
        thing = {
            'name': self.name,
            'href': self.href_prefix if self.href_prefix else '/',
            '@context': self.context,
            '@type': self.type,
            'properties': self.get_property_descriptions(),
            'actions': {},
            'events': {},
            'links': [
                {
                    'rel': 'properties',
                    'href': '{}/properties'.format(self.href_prefix),
                },
                {
                    'rel': 'actions',
                    'href': '{}/actions'.format(self.href_prefix),
                },
                {
                    'rel': 'events',
                    'href': '{}/events'.format(self.href_prefix),
                },
            ],
        }

        for name, action in self.available_actions.items():
            thing['actions'][name] = action['metadata']
            thing['actions'][name]['links'] = [
                {
                    'rel': 'action',
                    'href': '{}/actions/{}'.format(self.href_prefix, name),
                },
            ]

        for name, event in self.available_events.items():
            thing['events'][name] = event['metadata']
            thing['events'][name]['links'] = [
                {
                    'rel': 'event',
                    'href': '{}/events/{}'.format(self.href_prefix, name),
                },
            ]

        if self.ui_href is not None:
            thing['links'].append({
                'rel': 'alternate',
                'mediaType': 'text/html',
                'href': self.ui_href,
            })

        if self.description:
            thing['description'] = self.description

        return thing

Response: Returns the state as a Thing Description.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def set_href_prefix(self, prefix):
        self.href_prefix = prefix

        for property_ in self.properties.values():
            property_.set_href_prefix(prefix)

        for action_name in self.actions.keys():
            for action in self.actions[action_name]:
                action.set_href_prefix(prefix)

Response: Sets the prefix of any hrefs associated with this thing.


Instruction:
How would you code a function in Python 3 to
get the properties as a dictionary.

Response:
def get_property_descriptions(self):
        """
        Get the thing's properties as a dictionary.

        Returns the properties as a dictionary, i.e. name -> description.
        """
        return {k: v.as_property_description()
                for k, v in self.properties.items()}


Instruction:
Given the following Python 3 function, write the documentation
def get_action_descriptions(self, action_name=None):
        descriptions = []

        if action_name is None:
            for name in self.actions:
                for action in self.actions[name]:
                    descriptions.append(action.as_action_description())
        elif action_name in self.actions:
            for action in self.actions[action_name]:
                descriptions.append(action.as_action_description())

        return descriptions

Response: Returns the list of action descriptions for the thing.


Instruction:
Given the following Python 3 function, write the documentation
def get_event_descriptions(self, event_name=None):
        if event_name is None:
            return [e.as_event_description() for e in self.events]
        else:
            return [e.as_event_description()
                    for e in self.events if e.get_name() == event_name]

Response: Returns the event descriptions for the given event name.


Instruction:
Implement a function in Python 3 to
add a property to this thing.

Response:
def add_property(self, property_):
        """
        Add a property to this thing.

        property_ -- property to add
        """
        property_.set_href_prefix(self.href_prefix)
        self.properties[property_.name] = property_


Instruction:
Given the following Python 3 function, write the documentation
def remove_property(self, property_):
        if property_.name in self.properties:
            del self.properties[property_.name]

Response: Removes a property from this thing.


Instruction:
How would you explain what the following Python 3 function does
def get_property(self, property_name):
        prop = self.find_property(property_name)
        if prop:
            return prop.get_value()

        return None

Response: Get a property s value.


Instruction:
Write a Python 3 script to
get a mapping of all properties and their values.

Response:
def get_properties(self):
        """
        Get a mapping of all properties and their values.

        Returns a dictionary of property_name -> value.
        """
        return {prop.get_name(): prop.get_value()
                for prop in self.properties.values()}


Instruction:
Write a Python 3 script for
setting a property value.

Response:
def set_property(self, property_name, value):
        """
        Set a property value.

        property_name -- name of the property to set
        value -- value to set
        """
        prop = self.find_property(property_name)
        if not prop:
            return

        prop.set_value(value)


Instruction:
Can you generate the documentation for the following Python 3 function
def get_action(self, action_name, action_id):
        if action_name not in self.actions:
            return None

        for action in self.actions[action_name]:
            if action.id == action_id:
                return action

        return None

Response: Get an action from the list of available actions.


Instruction:
Can you generate the documentation for the following Python 3 function
def add_event(self, event):
        self.events.append(event)
        self.event_notify(event)

Response: Add a new event and notify subscribers.


Instruction:
How would you explain what the following Python 3 function does
def add_available_event(self, name, metadata):
        if metadata is None:
            metadata = {}

        self.available_events[name] = {
            'metadata': metadata,
            'subscribers': set(),
        }

Response: Add an available event.


Instruction:
How would you explain what the following Python 3 function does
def perform_action(self, action_name, input_=None):
        if action_name not in self.available_actions:
            return None

        action_type = self.available_actions[action_name]

        if 'input' in action_type['metadata']:
            try:
                validate(input_, action_type['metadata']['input'])
            except ValidationError:
                return None

        action = action_type['class'](self, input_=input_)
        action.set_href_prefix(self.href_prefix)
        self.action_notify(action)
        self.actions[action_name].append(action)
        return action

Response: Perform an action on the thing.


Instruction:
Write a Python 3 script to
remove an existing action.

Response:
def remove_action(self, action_name, action_id):
        """
        Remove an existing action.

        action_name -- name of the action
        action_id -- ID of the action

        Returns a boolean indicating the presence of the action.
        """
        action = self.get_action(action_name, action_id)
        if action is None:
            return False

        action.cancel()
        self.actions[action_name].remove(action)
        return True


Instruction:
Write a Python 3 script for
adding an available action.

Response:
def add_available_action(self, name, metadata, cls):
        """
        Add an available action.

        name -- name of the action
        metadata -- action metadata, i.e. type, description, etc., as a dict
        cls -- class to instantiate for this action
        """
        if metadata is None:
            metadata = {}

        self.available_actions[name] = {
            'metadata': metadata,
            'class': cls,
        }
        self.actions[name] = []


Instruction:
Given the following Python 3 function, write the documentation
def remove_subscriber(self, ws):
        if ws in self.subscribers:
            self.subscribers.remove(ws)

        for name in self.available_events:
            self.remove_event_subscriber(name, ws)

Response:
Remove a websocket subscriber.

        ws -- the websocket


Instruction:
Can you implement a function in Python 3 that
adds a new websocket subscriber to an event.

Response:
def add_event_subscriber(self, name, ws):
        """
        Add a new websocket subscriber to an event.

        name -- name of the event
        ws -- the websocket
        """
        if name in self.available_events:
            self.available_events[name]['subscribers'].add(ws)


Instruction:
Write a Python 3 function for
removing a websocket subscriber from an event.

Response:
def remove_event_subscriber(self, name, ws):
        """
        Remove a websocket subscriber from an event.

        name -- name of the event
        ws -- the websocket
        """
        if name in self.available_events and \
                ws in self.available_events[name]['subscribers']:
            self.available_events[name]['subscribers'].remove(ws)


Instruction:
Explain what the following Python 3 code does
def property_notify(self, property_):
        message = json.dumps({
            'messageType': 'propertyStatus',
            'data': {
                property_.name: property_.get_value(),
            }
        })

        for subscriber in list(self.subscribers):
            try:
                subscriber.write_message(message)
            except tornado.websocket.WebSocketClosedError:
                pass

Response: Notify all subscribers of a property change.


Instruction:
Create a Python 3 function to
notify all subscribers of an action status change.

Response:
def action_notify(self, action):
        """
        Notify all subscribers of an action status change.

        action -- the action whose status changed
        """
        message = json.dumps({
            'messageType': 'actionStatus',
            'data': action.as_action_description(),
        })

        for subscriber in list(self.subscribers):
            try:
                subscriber.write_message(message)
            except tornado.websocket.WebSocketClosedError:
                pass


Instruction:
Implement a function in Python 3 to
notify all subscribers of an event.

Response:
def event_notify(self, event):
        """
        Notify all subscribers of an event.

        event -- the event that occurred
        """
        if event.name not in self.available_events:
            return

        message = json.dumps({
            'messageType': 'event',
            'data': event.as_event_description(),
        })

        for subscriber in self.available_events[event.name]['subscribers']:
            try:
                subscriber.write_message(message)
            except tornado.websocket.WebSocketClosedError:
                pass


Instruction:
Explain what the following Python 3 code does
def update(self, **fields):

        # build up the query to execute
        self._for_write = True
        if django.VERSION >= (2, 0):
            query = self.query.chain(UpdateQuery)
        else:
            query = self.query.clone(UpdateQuery)
        query._annotations = None
        query.add_update_values(fields)

        # build the compiler for for the query
        connection = django.db.connections[self.db]
        compiler = PostgresReturningUpdateCompiler(query, connection, self.db)

        # execute the query
        with transaction.atomic(using=self.db, savepoint=False):
            rows = compiler.execute_sql(CURSOR)
        self._result_cache = None

        # send out a signal for each row
        for row in rows:
            signals.update.send(self.model, pk=row[0])

        # the original update(..) returns the amount of rows
        # affected, let's do the same
        return len(rows)

Response: Updates all rows that match the filter. Returns the number of rows affected.


Instruction:
How would you code a function in Python 3 to
set the action to take when attempting to insert or create a new row.

Response:
def on_conflict(self, fields: List[Union[str, Tuple[str]]], action, index_predicate: str=None):
        """Sets the action to take when conflicts arise when attempting
        to insert/create a new row.

        Arguments:
            fields:
                The fields the conflicts can occur in.

            action:
                The action to take when the conflict occurs.

            index_predicate:
                The index predicate to satisfy an arbiter partial index (i.e. what partial index to use for checking
                conflicts)
        """

        self.conflict_target = fields
        self.conflict_action = action
        self.index_predicate = index_predicate

        return self


Instruction:
Write a Python 3 script for
creating multiple new records in the database.

Response:
def bulk_insert(self, rows, return_model=False):
        """Creates multiple new records in the database.

        This allows specifying custom conflict behavior using .on_conflict().
        If no special behavior was specified, this uses the normal Django create(..)

        Arguments:
            rows:
                An array of dictionaries, where each dictionary
                describes the fields to insert.

            return_model (default: False):
                If model instances should be returned rather than
                just dicts.

        Returns:
            A list of either the dicts of the rows inserted, including the pk or
            the models of the rows inserted with defaults for any fields not specified
        """

        if self.conflict_target or self.conflict_action:
            compiler = self._build_insert_compiler(rows)
            objs = compiler.execute_sql(return_id=True)
            if return_model:
                return [self.model(**dict(r, **k)) for r, k in zip(rows, objs)]
            else:
                return [dict(r, **k) for r, k in zip(rows, objs)]

        # no special action required, use the standard Django bulk_create(..)
        return super().bulk_create([self.model(**fields) for fields in rows])


Instruction:
Given the following Python 3 function, write the documentation
def insert(self, **fields):

        if self.conflict_target or self.conflict_action:
            compiler = self._build_insert_compiler([fields])
            rows = compiler.execute_sql(return_id=True)

            pk_field_name = self.model._meta.pk.name
            return rows[0][pk_field_name]

        # no special action required, use the standard Django create(..)
        return super().create(**fields).pk

Response: Creates a new record in the database.


Instruction:
Can you tell what is the following Python 3 function doing
def insert_and_get(self, **fields):

        if not self.conflict_target and not self.conflict_action:
            # no special action required, use the standard Django create(..)
            return super().create(**fields)

        compiler = self._build_insert_compiler([fields])
        rows = compiler.execute_sql(return_id=False)

        columns = rows[0]

        # get a list of columns that are officially part of the model and preserve the fact that the attribute name
        # might be different than the database column name
        model_columns = {}
        for field in self.model._meta.local_concrete_fields:
            model_columns[field.column] = field.attname

        # strip out any columns/fields returned by the db that
        # are not present in the model
        model_init_fields = {}
        for column_name, column_value in columns.items():
            try:
                model_init_fields[model_columns[column_name]] = column_value
            except KeyError:
                pass

        return self.model(**model_init_fields)

Response: Creates a new record in the database and then gets the entire record.


Instruction:
Implement a Python 3 function for
creating a new record or updates an existing one.

Response:
def upsert(self, conflict_target: List, fields: Dict, index_predicate: str=None) -> int:
        """Creates a new record or updates the existing one
        with the specified data.

        Arguments:
            conflict_target:
                Fields to pass into the ON CONFLICT clause.

            fields:
                Fields to insert/update.

            index_predicate:
                The index predicate to satisfy an arbiter partial index (i.e. what partial index to use for checking
                conflicts)

        Returns:
            The primary key of the row that was created/updated.
        """

        self.on_conflict(conflict_target, ConflictAction.UPDATE, index_predicate)
        return self.insert(**fields)


Instruction:
Write a Python 3 function for
creating a new record or updates the existing one and then gets the row.

Response:
def upsert_and_get(self, conflict_target: List, fields: Dict, index_predicate: str=None):
        """Creates a new record or updates the existing one
        with the specified data and then gets the row.

        Arguments:
            conflict_target:
                Fields to pass into the ON CONFLICT clause.

            fields:
                Fields to insert/update.

            index_predicate:
                The index predicate to satisfy an arbiter partial index (i.e. what partial index to use for checking
                conflicts)

        Returns:
            The model instance representing the row
            that was created/updated.
        """

        self.on_conflict(conflict_target, ConflictAction.UPDATE, index_predicate)
        return self.insert_and_get(**fields)


Instruction:
Here you have a function in Python 3, explain what it does
def bulk_upsert(self, conflict_target: List, rows: List[Dict], index_predicate: str=None):

        if not rows or len(rows) <= 0:
            return

        self.on_conflict(conflict_target, ConflictAction.UPDATE, index_predicate)
        return self.bulk_insert(rows)

Response: Bulk upserts the specified data into the existing records or updates the existing records.


Instruction:
Explain what the following Python 3 code does
def _build_insert_compiler(self, rows: List[Dict]):

        # create model objects, we also have to detect cases
        # such as:
        #   [dict(first_name='swen'), dict(fist_name='swen', last_name='kooij')]
        # we need to be certain that each row specifies the exact same
        # amount of fields/columns
        objs = []
        field_count = len(rows[0])
        for index, row in enumerate(rows):
            if field_count != len(row):
                raise SuspiciousOperation((
                    'In bulk upserts, you cannot have rows with different field '
                    'configurations. Row {0} has a different field config than '
                    'the first row.'
                ).format(index))

            objs.append(self.model(**row))

        # indicate this query is going to perform write
        self._for_write = True

        # get the fields to be used during update/insert
        insert_fields, update_fields = self._get_upsert_fields(rows[0])

        # build a normal insert query
        query = PostgresInsertQuery(self.model)
        query.conflict_action = self.conflict_action
        query.conflict_target = self.conflict_target
        query.index_predicate = self.index_predicate
        query.values(objs, insert_fields, update_fields)

        # use the postgresql insert query compiler to transform the insert
        # into an special postgresql insert
        connection = django.db.connections[self.db]
        compiler = PostgresInsertCompiler(query, connection, self.db)

        return compiler

Response: Builds the SQL compiler for an insert query.


Instruction:
Given the following Python 3 function, write the documentation
def _is_magical_field(self, model_instance, field, is_insert: bool):

        # does this field modify someting upon insert?
        old_value = getattr(model_instance, field.name, None)
        field.pre_save(model_instance, is_insert)
        new_value = getattr(model_instance, field.name, None)

        return old_value != new_value

Response: Verifies whether this field is magical.


Instruction:
Write a Python 3 script to
get the fields to use in an upsert. This some nice magic. We'll split the fields into a group of "insert fields" and "update fields": INSERT INTO bla ("val1", "val2") ON CONFLICT DO UPDATE SET val1 = EXCLUDED.val1 ^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^ insert_fields update_fields Often, fields appear in both lists. But, for example, a :see:DateTime field with `auto_now_add=True` set, will only appear in "insert_fields", since it won't be set on existing rows. Other than that, the user specificies a list of fields in the upsert() call. That migt not be all fields. The user could decide to leave out optional fields. If we end up doing an update, we don't want to overwrite those non-specified fields. We cannot just take the list of fields the user specifies, because as mentioned, some fields make modifications to the model on their own. We'll have to detect which fields make modifications and include them in the list of insert/update fields.

Response:
def _get_upsert_fields(self, kwargs):
        """Gets the fields to use in an upsert.

        This some nice magic. We'll split the fields into
        a group of "insert fields" and "update fields":

        INSERT INTO bla ("val1", "val2") ON CONFLICT DO UPDATE SET val1 = EXCLUDED.val1

                         ^^^^^^^^^^^^^^                            ^^^^^^^^^^^^^^^^^^^^
                         insert_fields                                 update_fields

        Often, fields appear in both lists. But, for example,
        a :see:DateTime field with `auto_now_add=True` set, will
        only appear in "insert_fields", since it won't be set
        on existing rows.

        Other than that, the user specificies a list of fields
        in the upsert() call. That migt not be all fields. The
        user could decide to leave out optional fields. If we
        end up doing an update, we don't want to overwrite
        those non-specified fields.

        We cannot just take the list of fields the user
        specifies, because as mentioned, some fields
        make modifications to the model on their own.

        We'll have to detect which fields make modifications
        and include them in the list of insert/update fields.
        """

        model_instance = self.model(**kwargs)
        insert_fields = []
        update_fields = []

        for field in model_instance._meta.local_concrete_fields:
            has_default = field.default != NOT_PROVIDED
            if (field.name in kwargs or field.column in kwargs):
                insert_fields.append(field)
                update_fields.append(field)
                continue
            elif has_default:
                insert_fields.append(field)
                continue

            # special handling for 'pk' which always refers to
            # the primary key, so if we the user specifies `pk`
            # instead of a concrete field, we have to handle that
            if field.primary_key is True and 'pk' in kwargs:
                insert_fields.append(field)
                update_fields.append(field)
                continue

            if self._is_magical_field(model_instance, field, is_insert=True):
                insert_fields.append(field)

            if self._is_magical_field(model_instance, field, is_insert=False):
                update_fields.append(field)

        return insert_fields, update_fields


Instruction:
Can you create a Python 3 function that
sets the action to take when attempting to insert or create a new row.

Response:
def on_conflict(self, fields: List[Union[str, Tuple[str]]], action, index_predicate: str=None):
        """Sets the action to take when conflicts arise when attempting
        to insert/create a new row.

        Arguments:
            fields:
                The fields the conflicts can occur in.

            action:
                The action to take when the conflict occurs.

            index_predicate:
                The index predicate to satisfy an arbiter partial index.
        """
        return self.get_queryset().on_conflict(fields, action, index_predicate)


Instruction:
Create a Python 3 function to
create a new record or updates the existing one with the specified data.

Response:
def upsert(self, conflict_target: List, fields: Dict, index_predicate: str=None) -> int:
        """Creates a new record or updates the existing one
        with the specified data.

        Arguments:
            conflict_target:
                Fields to pass into the ON CONFLICT clause.

            fields:
                Fields to insert/update.

            index_predicate:
                The index predicate to satisfy an arbiter partial index.

        Returns:
            The primary key of the row that was created/updated.
        """

        return self.get_queryset().upsert(conflict_target, fields, index_predicate)


Instruction:
Can you generate the documentation for the following Python 3 function
def upsert_and_get(self, conflict_target: List, fields: Dict, index_predicate: str=None):

        return self.get_queryset().upsert_and_get(conflict_target, fields, index_predicate)

Response:
Creates a new record or updates the existing one
            with the specified data and then gets the row.


Instruction:
How would you explain what the following Python 3 function does
def bulk_upsert(self, conflict_target: List, rows: List[Dict], index_predicate: str=None):

        return self.get_queryset().bulk_upsert(conflict_target, rows, index_predicate)

Response: Bulk upserts the specified data into the specified set of records or updates the existing records.


Instruction:
Explain what the following Python 3 code does
def _on_model_save(sender, **kwargs):

        created, instance = kwargs['created'], kwargs['instance']

        if created:
            signals.create.send(sender, pk=instance.pk)
        else:
            signals.update.send(sender, pk=instance.pk)

Response: When a model gets created or updated send signals.


Instruction:
Here you have a function in Python 3, explain what it does
def _on_model_delete(sender, **kwargs):

        instance = kwargs['instance']
        signals.delete.send(sender, pk=instance.pk)

Response: When a model gets deleted send a signal to the user that the related object is deleted.


Instruction:
Can you tell what is the following Python 3 function doing
def IsNotNone(*fields, default=None):

    when_clauses = [
        expressions.When(
            ~expressions.Q(**{field: None}),
            then=expressions.F(field)
        )
        for field in reversed(fields)
    ]

    return expressions.Case(
        *when_clauses,
        default=expressions.Value(default),
        output_field=CharField()
    )

Response: Selects whichever field is not None.


Instruction:
Can you write a function in Python 3 where it
resolves expressions inside the dictionary.

Response:
def resolve_expression(self, *args, **kwargs):
        """Resolves expressions inside the dictionary."""

        result = dict()
        for key, value in self.value.items():
            if hasattr(value, 'resolve_expression'):
                result[key] = value.resolve_expression(
                    *args, **kwargs)
            else:
                result[key] = value

        return HStoreValue(result)


Instruction:
Here you have a function in Python 3, explain what it does
def as_sql(self, compiler, connection):

        result = []
        for key, value in self.value.items():
            if hasattr(value, 'as_sql'):
                sql, params = value.as_sql(compiler, connection)
                result.append('hstore(\'%s\', %s)' % (
                    key, sql % params))
            elif value is not None:
                result.append('hstore(\'%s\', \'%s\')' % ((
                    key, value)))
            else:
                result.append('hstore(\'%s\', NULL)' % key)

        return '%s' % ' || '.join(result), []

Response: Compiles the HStore value into SQL.


Instruction:
Can you create a Python 3 function that
compiles this expression into SQL.

Response:
def as_sql(self, compiler, connection):
        """Compiles this expression into SQL."""

        qn = compiler.quote_name_unless_alias
        return "%s.%s->'%s'" % (qn(self.alias), qn(self.target.column), self.hstore_key), []


Instruction:
Explain what the following Python 3 code does
def relabeled_clone(self, relabels):

        return self.__class__(
            relabels.get(self.alias, self.alias),
            self.target,
            self.hstore_key,
            self.output_field
        )

Response: Gets a re - labeled clone of this expression.


Instruction:
Write a Python 3 function that can
resolve the expression into a HStoreColumn expression.

Response:
def resolve_expression(self, *args, **kwargs) -> HStoreColumn:
        """Resolves the expression into a :see:HStoreColumn expression."""

        original_expression = super().resolve_expression(*args, **kwargs)
        expression = HStoreColumn(
            original_expression.alias,
            original_expression.target,
            self.key
        )
        return expression


Instruction:
How would you explain what the following Python 3 function does
def as_sql(self, compiler, connection):

        sql, params = super().as_sql(compiler, connection)
        return 'EXTRACT(epoch FROM {})'.format(sql), params

Response: Compiles this expression into SQL.


Instruction:
Can you tell what is the following Python 3 function doing
def rename_annotations(self, annotations) -> None:

        for old_name, new_name in annotations.items():
            annotation = self.annotations.get(old_name)

            if not annotation:
                raise SuspiciousOperation((
                    'Cannot rename annotation "{old_name}" to "{new_name}", because there'
                    ' is no annotation named "{old_name}".'
                ).format(old_name=old_name, new_name=new_name))

            self._annotations = OrderedDict(
                [(new_name, v) if k == old_name else (k, v) for k, v in self._annotations.items()])

            if django.VERSION < (2, 0):
                self.set_annotation_mask(
                    (new_name if v == old_name else v for v in (self.annotation_select_mask or [])))

Response: Renames the aliases for the specified annotations.


Instruction:
Create a Python 3 function for
adding an extra condition to an existing JOIN.

Response:
def add_join_conditions(self, conditions: Dict[str, Any]) -> None:
        """Adds an extra condition to an existing JOIN.

        This allows you to for example do:

            INNER JOIN othertable ON (mytable.id = othertable.other_id AND [extra conditions])

        This does not work if nothing else in your query doesn't already generate the
        initial join in the first place.
        """

        alias = self.get_initial_alias()
        opts = self.get_meta()

        for name, value in conditions.items():
            parts = name.split(LOOKUP_SEP)
            join_info = self.setup_joins(parts, opts, alias, allow_many=True)
            self.trim_joins(join_info[1], join_info[3], join_info[4])

            target_table = join_info[3][-1]
            field = join_info[1][-1]
            join = self.alias_map.get(target_table)

            if not join:
                raise SuspiciousOperation((
                    'Cannot add an extra join condition for "%s", there\'s no'
                    ' existing join to add it to.'
                ) % target_table)

            # convert the Join object into a ConditionalJoin object, which
            # allows us to add the extra condition
            if not isinstance(join, ConditionalJoin):
                self.alias_map[target_table] = ConditionalJoin.from_join(join)
                join = self.alias_map[target_table]

            join.add_condition(field, value)


Instruction:
Implement a function in Python 3 to
add the given field names to the select set.

Response:
def add_fields(self, field_names: List[str], allow_m2m: bool=True) -> bool:
        """
        Adds the given (model) fields to the select set. The field names are
        added in the order specified.

        This overrides the base class's add_fields method. This is called by
        the .values() or .values_list() method of the query set. It instructs
        the ORM to only select certain values. A lot of processing is neccesarry
        because it can be used to easily do joins. For example, `my_fk__name` pulls
        in the `name` field in foreign key `my_fk`.

        In our case, we want to be able to do `title__en`, where `title` is a HStoreField
        and `en` a key. This doesn't really involve a join. We iterate over the specified
        field names and filter out the ones that refer to HStoreField and compile it into
        an expression which is added to the list of to be selected fields using `self.add_select`.
        """

        alias = self.get_initial_alias()
        opts = self.get_meta()
        cols = []
        for name in field_names:
            parts = name.split(LOOKUP_SEP)

            # it cannot be a special hstore thing if there's no __ in it
            if len(parts) > 1:
                column_name, hstore_key = parts[:2]
                is_hstore, field = self._is_hstore_field(column_name)
                if is_hstore:
                    cols.append(
                        HStoreColumn(self.model._meta.db_table or self.model.name, field, hstore_key)
                    )
                    continue

            join_info = self.setup_joins(parts, opts, alias, allow_many=allow_m2m)
            targets, final_alias, joins = self.trim_joins(
                join_info[1], join_info[3], join_info[4]
            )

            for target in targets:
                cols.append(target.get_col(final_alias))
        if cols:
            self.set_select(cols)


Instruction:
Make a summary of the following Python 3 code
def _is_hstore_field(self, field_name: str) -> Tuple[bool, Optional[models.Field]]:

        field_instance = None
        for field in self.model._meta.local_concrete_fields:
            if field.name == field_name or field.column == field_name:
                field_instance = field
                break

        return isinstance(field_instance, HStoreField), field_instance

Response: Returns whether the field with the specified name is a HStoreField and the HStoreField instance if it is.


Instruction:
Here you have a function in Python 3, explain what it does
def values(self, objs: List, insert_fields: List, update_fields: List=[]):

        self.insert_values(insert_fields, objs, raw=False)
        self.update_fields = update_fields

Response: Sets the values to be used in this query.


Instruction:
Can you create a Python 3 function that
runs when a new model is created.

Response:
def create_model(self, model):
        """Ran when a new model is created."""

        for field in model._meta.local_fields:
            if not isinstance(field, HStoreField):
                continue

            self.add_field(model, field)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def delete_model(self, model):

        for field in model._meta.local_fields:
            if not isinstance(field, HStoreField):
                continue

            self.remove_field(model, field)

Response: Ran when a model is being deleted.


Instruction:
Write a Python 3 function that can
run when the name of a model is changed.

Response:
def alter_db_table(self, model, old_db_table, new_db_table):
        """Ran when the name of a model is changed."""

        for field in model._meta.local_fields:
            if not isinstance(field, HStoreField):
                continue

            for key in self._iterate_required_keys(field):
                self._rename_hstore_required(
                    old_db_table,
                    new_db_table,
                    field,
                    field,
                    key
                )


Instruction:
How would you explain what the following Python 3 function does
def add_field(self, model, field):

        for key in self._iterate_required_keys(field):
            self._create_hstore_required(
                model._meta.db_table,
                field,
                key
            )

Response: Ran when a field is added to a model.


Instruction:
Write a Python 3 function for
running when a field is removed from a model.

Response:
def remove_field(self, model, field):
        """Ran when a field is removed from a model."""

        for key in self._iterate_required_keys(field):
            self._drop_hstore_required(
                model._meta.db_table,
                field,
                key
            )


Instruction:
Write a Python 3 function that can
run when the configuration on a field has changed.

Response:
def alter_field(self, model, old_field, new_field, strict=False):
        """Ran when the configuration on a field changed."""

        is_old_field_hstore = isinstance(old_field, HStoreField)
        is_new_field_hstore = isinstance(new_field, HStoreField)

        if not is_old_field_hstore and not is_new_field_hstore:
            return

        old_required = getattr(old_field, 'required', []) or []
        new_required = getattr(new_field, 'required', []) or []

        # handle field renames before moving on
        if str(old_field.column) != str(new_field.column):
            for key in self._iterate_required_keys(old_field):
                self._rename_hstore_required(
                    model._meta.db_table,
                    model._meta.db_table,
                    old_field,
                    new_field,
                    key
                )

        # drop the constraints for keys that have been removed
        for key in old_required:
            if key not in new_required:
                self._drop_hstore_required(
                    model._meta.db_table,
                    old_field,
                    key
                )

        # create new constraints for keys that have been added
        for key in new_required:
            if key not in old_required:
                self._create_hstore_required(
                    model._meta.db_table,
                    new_field,
                    key
                )


Instruction:
How would you code a function in Python 3 to
create a REQUIRED CONSTRAINT for the specified hstore key.

Response:
def _create_hstore_required(self, table_name, field, key):
        """Creates a REQUIRED CONSTRAINT for the specified hstore key."""

        name = self._required_constraint_name(
            table_name, field, key)

        sql = self.sql_hstore_required_create.format(
            name=self.quote_name(name),
            table=self.quote_name(table_name),
            field=self.quote_name(field.column),
            key=key
        )
        self.execute(sql)


Instruction:
How would you implement a function in Python 3 that
renames an existing REQUIRED CONSTRAINT for the specified hstore key.

Response:
def _rename_hstore_required(self, old_table_name, new_table_name,
                                old_field, new_field, key):
        """Renames an existing REQUIRED CONSTRAINT for the specified
        hstore key."""

        old_name = self._required_constraint_name(
            old_table_name, old_field, key)
        new_name = self._required_constraint_name(
            new_table_name, new_field, key)

        sql = self.sql_hstore_required_rename.format(
            table=self.quote_name(new_table_name),
            old_name=self.quote_name(old_name),
            new_name=self.quote_name(new_name)
        )
        self.execute(sql)


Instruction:
Create a Python 3 function for
dropping a REQUIRED CONSTRAINT for the specified hstore key.

Response:
def _drop_hstore_required(self, table_name, field, key):
        """Drops a REQUIRED CONSTRAINT for the specified hstore key."""

        name = self._required_constraint_name(
            table_name, field, key)

        sql = self.sql_hstore_required_drop.format(
            table=self.quote_name(table_name),
            name=self.quote_name(name)
        )
        self.execute(sql)


Instruction:
Can you generate the documentation for the following Python 3 function
def _required_constraint_name(table: str, field, key):

        return '{table}_{field}_required_{postfix}'.format(
            table=table,
            field=field.column,
            postfix=key
        )

Response:
Gets the name for a CONSTRAINT that applies
            to a single hstore key.


Instruction:
Write a Python 3 function that can
create the actual SQL used when applying the migration.

Response:
def create_sql(self, model, schema_editor, using=''):
        """Creates the actual SQL used when applying the migration."""
        if django.VERSION >= (2, 0):
            statement = super().create_sql(model, schema_editor, using)
            statement.template = self.sql_create_index
            statement.parts['condition'] = self.condition
            return statement
        else:
            sql_create_index = self.sql_create_index
            sql_parameters = {
                **Index.get_sql_create_template_values(self, model, schema_editor, using),
                'condition': self.condition
            }
            return sql_create_index % sql_parameters


Instruction:
How would you explain what the following Python 3 function does
def deconstruct(self):
        path = '%s.%s' % (self.__class__.__module__, self.__class__.__name__)
        path = path.replace('django.db.models.indexes', 'django.db.models')
        return path, (), {'fields': self.fields, 'name': self.name, 'condition': self.condition}

Response: Serializes the : see : ConditionalUniqueIndex for the migrations file.


Instruction:
Implement a Python 3 function for
creating a custom setup. py command.

Response:
def create_command(text, commands):
    """Creates a custom setup.py command."""

    class CustomCommand(BaseCommand):
        description = text

        def run(self):
            for cmd in commands:
                subprocess.check_call(cmd)

    return CustomCommand


Instruction:
Write a Python 3 script to
return the base class for the custom database back - end.

Response:
def _get_backend_base():
    """Gets the base class for the custom database back-end.

    This should be the Django PostgreSQL back-end. However,
    some people are already using a custom back-end from
    another package. We are nice people and expose an option
    that allows them to configure the back-end we base upon.

    As long as the specified base eventually also has
    the PostgreSQL back-end as a base, then everything should
    work as intended.
    """
    base_class_name = getattr(
        settings,
        'POSTGRES_EXTRA_DB_BACKEND_BASE',
        'django.db.backends.postgresql'
    )

    base_class_module = importlib.import_module(base_class_name + '.base')
    base_class = getattr(base_class_module, 'DatabaseWrapper', None)

    if not base_class:
        raise ImproperlyConfigured((
            '\'%s\' is not a valid database back-end.'
            ' The module does not define a DatabaseWrapper class.'
            ' Check the value of POSTGRES_EXTRA_DB_BACKEND_BASE.'
        ) % base_class_name)

    if isinstance(base_class, Psycopg2DatabaseWrapper):
        raise ImproperlyConfigured((
            '\'%s\' is not a valid database back-end.'
            ' It does inherit from the PostgreSQL back-end.'
            ' Check the value of POSTGRES_EXTRA_DB_BACKEND_BASE.'
        ) % base_class_name)

    return base_class


Instruction:
Can you write a function in Python 3 where it
runs when a new model is created.

Response:
def create_model(self, model):
        """Ran when a new model is created."""

        super().create_model(model)

        for mixin in self.post_processing_mixins:
            mixin.create_model(model)


Instruction:
Can you write a function in Python 3 where it
runs when a model is being deleted.

Response:
def delete_model(self, model):
        """Ran when a model is being deleted."""

        for mixin in self.post_processing_mixins:
            mixin.delete_model(model)

        super().delete_model(model)


Instruction:
How would you explain what the following Python 3 function does
def alter_db_table(self, model, old_db_table, new_db_table):

        super(SchemaEditor, self).alter_db_table(
            model, old_db_table, new_db_table
        )

        for mixin in self.post_processing_mixins:
            mixin.alter_db_table(
                model,
                old_db_table,
                new_db_table
            )

Response: Ran when the name of a model is changed.


Instruction:
Can you tell what is the following Python 3 function doing
def add_field(self, model, field):

        super(SchemaEditor, self).add_field(model, field)

        for mixin in self.post_processing_mixins:
            mixin.add_field(model, field)

Response: Ran when a field is added to a model.


Instruction:
Can you generate the documentation for the following Python 3 function
def remove_field(self, model, field):

        for mixin in self.post_processing_mixins:
            mixin.remove_field(model, field)

        super(SchemaEditor, self).remove_field(model, field)

Response: Ran when a field is removed from a model.


Instruction:
Here you have a function in Python 3, explain what it does
def alter_field(self, model, old_field, new_field, strict=False):

        super(SchemaEditor, self).alter_field(
            model, old_field, new_field, strict
        )

        for mixin in self.post_processing_mixins:
            mixin.alter_field(
                model, old_field, new_field, strict
            )

Response: Ran when the configuration on a field changed.