1# Copyright 2017 The TensorFlow Authors. All Rights Reserved.
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at
6#
7#     http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
14# ==============================================================================
15"""Python wrappers for Datasets and Iterators."""
16from __future__ import absolute_import
17from __future__ import division
18from __future__ import print_function
19
20import numpy as np
21
22from tensorflow.python.data.experimental.ops import get_single_element as experimental_get_single_element
23from tensorflow.python.data.ops import dataset_ops
24from tensorflow.python.util import deprecation
25
26
27@deprecation.deprecated(None,
28                        "Use `tf.data.experimental.get_single_element(...)`.")
29def get_single_element(dataset):
30  """Returns the single element in `dataset` as a nested structure of tensors.
31
32  This function enables you to use a `tf.data.Dataset` in a stateless
33  "tensor-in tensor-out" expression, without creating a `tf.data.Iterator`.
34  This can be useful when your preprocessing transformations are expressed
35  as a `Dataset`, and you want to use the transformation at serving time.
36  For example:
37
38  ```python
39  input_batch = tf.placeholder(tf.string, shape=[BATCH_SIZE])
40
41  def preprocessing_fn(input_str):
42    # ...
43    return image, label
44
45  dataset = (tf.data.Dataset.from_tensor_slices(input_batch)
46             .map(preprocessing_fn, num_parallel_calls=BATCH_SIZE)
47             .batch(BATCH_SIZE))
48
49  image_batch, label_batch = tf.contrib.data.get_single_element(dataset)
50  ```
51
52  Args:
53    dataset: A `tf.data.Dataset` object containing a single element.
54
55  Returns:
56    A nested structure of `tf.Tensor` objects, corresponding to the single
57    element of `dataset`.
58
59  Raises:
60    TypeError: if `dataset` is not a `tf.data.Dataset` object.
61    InvalidArgumentError (at runtime): if `dataset` does not contain exactly
62      one element.
63  """
64  return experimental_get_single_element.get_single_element(dataset)
65
66
67@deprecation.deprecated(None, "Use `tf.data.Dataset.reduce(...)`.")
68def reduce_dataset(dataset, reducer):
69  """Returns the result of reducing the `dataset` using `reducer`.
70
71  Args:
72    dataset: A `tf.data.Dataset` object.
73    reducer: A `tf.contrib.data.Reducer` object representing the reduce logic.
74
75  Returns:
76    A nested structure of `tf.Tensor` objects, corresponding to the result
77    of reducing `dataset` using `reducer`.
78
79  Raises:
80    TypeError: if `dataset` is not a `tf.data.Dataset` object.
81  """
82  if not isinstance(dataset, dataset_ops.Dataset):
83    raise TypeError("`dataset` must be a `tf.data.Dataset` object.")
84
85  return dataset.reduce(reducer.init_func(np.int64(0)), reducer.reduce_func)
86