tensorbored 2.21.0rc1769983804__py3-none-any.whl

tensorbored/compat/tensorflow_stub/tensor_shape.py

@@ -0,0 +1,1035 @@
+# Copyright 2015 The TensorFlow Authors. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""Helper classes for tensor shape inference."""
+
+# pytype: skip-file
+
+from . import compat, dtypes
+from tensorbored.compat.proto import tensor_shape_pb2
+
+
+# @tf_export("Dimension")
+class Dimension:
+    """Represents the value of one dimension in a TensorShape."""
+
+    def __init__(self, value):
+        """Creates a new Dimension with the given value."""
+        if value is None:
+            self._value = None
+        elif isinstance(value, dtypes.DType):
+            raise TypeError("Cannot convert %s to Dimension" % value)
+        else:
+            self._value = int(value)
+            if (
+                not isinstance(value, compat.bytes_or_text_types)
+                and self._value != value
+            ):
+                raise ValueError("Ambiguous dimension: %s" % value)
+            if self._value < 0:
+                raise ValueError("Dimension %d must be >= 0" % self._value)
+
+    def __repr__(self):
+        return "Dimension(%s)" % repr(self._value)
+
+    def __str__(self):
+        value = self._value
+        return "?" if value is None else str(value)
+
+    def __eq__(self, other):
+        """Returns true if `other` has the same known value as this
+        Dimension."""
+        try:
+            other = as_dimension(other)
+        except (TypeError, ValueError):
+            return NotImplemented
+        if self._value is None or other.value is None:
+            return None
+        return self._value == other.value
+
+    def __ne__(self, other):
+        """Returns true if `other` has a different known value from `self`."""
+        try:
+            other = as_dimension(other)
+        except (TypeError, ValueError):
+            return NotImplemented
+        if self._value is None or other.value is None:
+            return None
+        return self._value != other.value
+
+    def __int__(self):
+        return self._value
+
+    # This is needed for Windows.
+    # See https://github.com/tensorflow/tensorflow/pull/9780
+    def __long__(self):
+        return self._value
+
+    def __index__(self):
+        # Allow use in Python 3 range
+        return self._value
+
+    @property
+    def value(self):
+        """The value of this dimension, or None if it is unknown."""
+        return self._value
+
+    def is_convertible_with(self, other):
+        """Returns true if `other` is convertible with this Dimension.
+
+        Two known Dimensions are convertible if they have the same value.
+        An unknown Dimension is convertible with all other Dimensions.
+
+        Args:
+          other: Another Dimension.
+
+        Returns:
+          True if this Dimension and `other` are convertible.
+        """
+        other = as_dimension(other)
+        return (
+            self._value is None
+            or other.value is None
+            or self._value == other.value
+        )
+
+    def assert_is_convertible_with(self, other):
+        """Raises an exception if `other` is not convertible with this
+        Dimension.
+
+        Args:
+          other: Another Dimension.
+
+        Raises:
+          ValueError: If `self` and `other` are not convertible (see
+            is_convertible_with).
+        """
+        if not self.is_convertible_with(other):
+            raise ValueError(
+                "Dimensions %s and %s are not convertible" % (self, other)
+            )
+
+    def merge_with(self, other):
+        """Returns a Dimension that combines the information in `self` and
+        `other`.
+
+        Dimensions are combined as follows:
+
+        ```python
+        tf.Dimension(n)   .merge_with(tf.Dimension(n))    == tf.Dimension(n)
+        tf.Dimension(n)   .merge_with(tf.Dimension(None)) == tf.Dimension(n)
+        tf.Dimension(None).merge_with(tf.Dimension(n))    == tf.Dimension(n)
+        tf.Dimension(None).merge_with(tf.Dimension(None)) == tf.Dimension(None)
+        tf.Dimension(n)   .merge_with(tf.Dimension(m))  # raises ValueError for n != m
+        ```
+
+        Args:
+          other: Another Dimension.
+
+        Returns:
+          A Dimension containing the combined information of `self` and
+          `other`.
+
+        Raises:
+          ValueError: If `self` and `other` are not convertible (see
+            is_convertible_with).
+        """
+        other = as_dimension(other)
+        self.assert_is_convertible_with(other)
+        if self._value is None:
+            return Dimension(other.value)
+        else:
+            return Dimension(self._value)
+
+    def __add__(self, other):
+        """Returns the sum of `self` and `other`.
+
+        Dimensions are summed as follows:
+
+        ```python
+        tf.Dimension(m)    + tf.Dimension(n)    == tf.Dimension(m + n)
+        tf.Dimension(m)    + tf.Dimension(None) == tf.Dimension(None)
+        tf.Dimension(None) + tf.Dimension(n)    == tf.Dimension(None)
+        tf.Dimension(None) + tf.Dimension(None) == tf.Dimension(None)
+        ```
+
+        Args:
+          other: Another Dimension, or a value accepted by `as_dimension`.
+
+        Returns:
+          A Dimension whose value is the sum of `self` and `other`.
+        """
+        other = as_dimension(other)
+        if self._value is None or other.value is None:
+            return Dimension(None)
+        else:
+            return Dimension(self._value + other.value)
+
+    def __radd__(self, other):
+        """Returns the sum of `other` and `self`.
+
+        Args:
+          other: Another Dimension, or a value accepted by `as_dimension`.
+
+        Returns:
+          A Dimension whose value is the sum of `self` and `other`.
+        """
+        return self + other
+
+    def __sub__(self, other):
+        """Returns the subtraction of `other` from `self`.
+
+        Dimensions are subtracted as follows:
+
+        ```python
+        tf.Dimension(m)    - tf.Dimension(n)    == tf.Dimension(m - n)
+        tf.Dimension(m)    - tf.Dimension(None) == tf.Dimension(None)
+        tf.Dimension(None) - tf.Dimension(n)    == tf.Dimension(None)
+        tf.Dimension(None) - tf.Dimension(None) == tf.Dimension(None)
+        ```
+
+        Args:
+          other: Another Dimension, or a value accepted by `as_dimension`.
+
+        Returns:
+          A Dimension whose value is the subtraction of `other` from `self`.
+        """
+        other = as_dimension(other)
+        if self._value is None or other.value is None:
+            return Dimension(None)
+        else:
+            return Dimension(self._value - other.value)
+
+    def __rsub__(self, other):
+        """Returns the subtraction of `self` from `other`.
+
+        Args:
+          other: Another Dimension, or a value accepted by `as_dimension`.
+
+        Returns:
+          A Dimension whose value is the subtraction of `self` from `other`.
+        """
+        other = as_dimension(other)
+        if self._value is None or other.value is None:
+            return Dimension(None)
+        else:
+            return Dimension(other.value - self._value)
+
+    def __mul__(self, other):
+        """Returns the product of `self` and `other`.
+
+        Dimensions are summed as follows:
+
+        ```python
+        tf.Dimension(m)    * tf.Dimension(n)    == tf.Dimension(m * n)
+        tf.Dimension(m)    * tf.Dimension(None) == tf.Dimension(None)
+        tf.Dimension(None) * tf.Dimension(n)    == tf.Dimension(None)
+        tf.Dimension(None) * tf.Dimension(None) == tf.Dimension(None)
+        ```
+
+        Args:
+          other: Another Dimension, or a value accepted by `as_dimension`.
+
+        Returns:
+          A Dimension whose value is the product of `self` and `other`.
+        """
+        try:
+            other = as_dimension(other)
+        except (TypeError, ValueError):
+            return NotImplemented
+
+        if self._value is None or other.value is None:
+            return Dimension(None)
+        else:
+            return Dimension(self._value * other.value)
+
+    def __rmul__(self, other):
+        """Returns the product of `self` and `other`.
+
+        Args:
+          other: Another Dimension, or a value accepted by `as_dimension`.
+
+        Returns:
+          A Dimension whose value is the product of `self` and `other`.
+        """
+        return self * other
+
+    def __floordiv__(self, other):
+        """Returns the quotient of `self` and `other` rounded down.
+
+        Dimensions are divided as follows:
+
+        ```python
+        tf.Dimension(m)    // tf.Dimension(n)    == tf.Dimension(m // n)
+        tf.Dimension(m)    // tf.Dimension(None) == tf.Dimension(None)
+        tf.Dimension(None) // tf.Dimension(n)    == tf.Dimension(None)
+        tf.Dimension(None) // tf.Dimension(None) == tf.Dimension(None)
+        ```
+
+        Args:
+          other: Another Dimension, or a value accepted by `as_dimension`.
+
+        Returns:
+          A `Dimension` whose value is the integer quotient of `self` and `other`.
+        """
+        try:
+            other = as_dimension(other)
+        except (TypeError, ValueError):
+            return NotImplemented
+        if self._value is None or other.value is None:
+            return Dimension(None)
+        else:
+            return Dimension(self._value // other.value)
+
+    def __rfloordiv__(self, other):
+        """Returns the quotient of `other` and `self` rounded down.
+
+        Args:
+          other: Another Dimension, or a value accepted by `as_dimension`.
+
+        Returns:
+          A `Dimension` whose value is the integer quotient of `self` and `other`.
+        """
+        other = as_dimension(other)
+        if self._value is None or other.value is None:
+            return Dimension(None)
+        else:
+            return Dimension(other.value // self._value)
+
+    def __div__(self, other):
+        """DEPRECATED: Use `__floordiv__` via `x // y` instead.
+
+        This function exists only for backwards convertibility purposes; new code
+        should use `__floordiv__` via the syntax `x // y`.  Using `x // y`
+        communicates clearly that the result rounds down, and is forward convertible
+        to Python 3.
+
+        Args:
+          other: Another `Dimension`.
+
+        Returns:
+          A `Dimension` whose value is the integer quotient of `self` and `other`.
+        """
+        return self // other
+
+    def __mod__(self, other):
+        """Returns `self` modulo `other`.
+
+        Dimension moduli are computed as follows:
+
+        ```python
+        tf.Dimension(m)    % tf.Dimension(n)    == tf.Dimension(m % n)
+        tf.Dimension(m)    % tf.Dimension(None) == tf.Dimension(None)
+        tf.Dimension(None) % tf.Dimension(n)    == tf.Dimension(None)
+        tf.Dimension(None) % tf.Dimension(None) == tf.Dimension(None)
+        ```
+
+        Args:
+          other: Another Dimension, or a value accepted by `as_dimension`.
+
+        Returns:
+          A Dimension whose value is `self` modulo `other`.
+        """
+        try:
+            other = as_dimension(other)
+        except (TypeError, ValueError):
+            return NotImplemented
+        if self._value is None or other.value is None:
+            return Dimension(None)
+        else:
+            return Dimension(self._value % other.value)
+
+    def __rmod__(self, other):
+        """Returns `other` modulo `self`.
+
+        Args:
+          other: Another Dimension, or a value accepted by `as_dimension`.
+
+        Returns:
+          A Dimension whose value is `other` modulo `self`.
+        """
+        try:
+            other = as_dimension(other)
+        except (TypeError, ValueError):
+            return NotImplemented
+        return other % self
+
+    def __lt__(self, other):
+        """Returns True if `self` is known to be less than `other`.
+
+        Dimensions are compared as follows:
+
+        ```python
+        (tf.Dimension(m)    < tf.Dimension(n))    == (m < n)
+        (tf.Dimension(m)    < tf.Dimension(None)) == None
+        (tf.Dimension(None) < tf.Dimension(n))    == None
+        (tf.Dimension(None) < tf.Dimension(None)) == None
+        ```
+
+        Args:
+          other: Another Dimension.
+
+        Returns:
+          The value of `self.value < other.value` if both are known, otherwise
+          None.
+        """
+        other = as_dimension(other)
+        if self._value is None or other.value is None:
+            return None
+        else:
+            return self._value < other.value
+
+    def __le__(self, other):
+        """Returns True if `self` is known to be less than or equal to `other`.
+
+        Dimensions are compared as follows:
+
+        ```python
+        (tf.Dimension(m)    <= tf.Dimension(n))    == (m <= n)
+        (tf.Dimension(m)    <= tf.Dimension(None)) == None
+        (tf.Dimension(None) <= tf.Dimension(n))    == None
+        (tf.Dimension(None) <= tf.Dimension(None)) == None
+        ```
+
+        Args:
+          other: Another Dimension.
+
+        Returns:
+          The value of `self.value <= other.value` if both are known, otherwise
+          None.
+        """
+        other = as_dimension(other)
+        if self._value is None or other.value is None:
+            return None
+        else:
+            return self._value <= other.value
+
+    def __gt__(self, other):
+        """Returns True if `self` is known to be greater than `other`.
+
+        Dimensions are compared as follows:
+
+        ```python
+        (tf.Dimension(m)    > tf.Dimension(n))    == (m > n)
+        (tf.Dimension(m)    > tf.Dimension(None)) == None
+        (tf.Dimension(None) > tf.Dimension(n))    == None
+        (tf.Dimension(None) > tf.Dimension(None)) == None
+        ```
+
+        Args:
+          other: Another Dimension.
+
+        Returns:
+          The value of `self.value > other.value` if both are known, otherwise
+          None.
+        """
+        other = as_dimension(other)
+        if self._value is None or other.value is None:
+            return None
+        else:
+            return self._value > other.value
+
+    def __ge__(self, other):
+        """Returns True if `self` is known to be greater than or equal to
+        `other`.
+
+        Dimensions are compared as follows:
+
+        ```python
+        (tf.Dimension(m)    >= tf.Dimension(n))    == (m >= n)
+        (tf.Dimension(m)    >= tf.Dimension(None)) == None
+        (tf.Dimension(None) >= tf.Dimension(n))    == None
+        (tf.Dimension(None) >= tf.Dimension(None)) == None
+        ```
+
+        Args:
+          other: Another Dimension.
+
+        Returns:
+          The value of `self.value >= other.value` if both are known, otherwise
+          None.
+        """
+        other = as_dimension(other)
+        if self._value is None or other.value is None:
+            return None
+        else:
+            return self._value >= other.value
+
+    def __reduce__(self):
+        return Dimension, (self._value,)
+
+
+def as_dimension(value):
+    """Converts the given value to a Dimension.
+
+    A Dimension input will be returned unmodified.
+    An input of `None` will be converted to an unknown Dimension.
+    An integer input will be converted to a Dimension with that value.
+
+    Args:
+      value: The value to be converted.
+
+    Returns:
+      A Dimension corresponding to the given value.
+    """
+    if isinstance(value, Dimension):
+        return value
+    else:
+        return Dimension(value)
+
+
+# @tf_export("TensorShape")
+class TensorShape:
+    """Represents the shape of a `Tensor`.
+
+    A `TensorShape` represents a possibly-partial shape specification for a
+    `Tensor`. It may be one of the following:
+
+    * *Fully-known shape:* has a known number of dimensions and a known size
+      for each dimension. e.g. `TensorShape([16, 256])`
+    * *Partially-known shape:* has a known number of dimensions, and an unknown
+      size for one or more dimension. e.g. `TensorShape([None, 256])`
+    * *Unknown shape:* has an unknown number of dimensions, and an unknown
+      size in all dimensions. e.g. `TensorShape(None)`
+
+    If a tensor is produced by an operation of type `"Foo"`, its shape
+    may be inferred if there is a registered shape function for
+    `"Foo"`. See @{$adding_an_op#shape-functions-in-c$`Shape functions in C++`}
+    for details of shape functions and how to register them. Alternatively,
+    the shape may be set explicitly using @{tf.Tensor.set_shape}.
+    """
+
+    def __init__(self, dims):
+        """Creates a new TensorShape with the given dimensions.
+
+        Args:
+          dims: A list of Dimensions, or None if the shape is unspecified.
+            DEPRECATED: A single integer is treated as a singleton list.
+
+        Raises:
+          TypeError: If dims cannot be converted to a list of dimensions.
+        """
+        # TODO(irving): Eliminate the single integer special case.
+        if dims is None:
+            self._dims = None
+        elif isinstance(dims, compat.bytes_or_text_types):
+            raise TypeError(
+                "A string has ambiguous TensorShape, please wrap in a "
+                "list or convert to an int: %s" % dims
+            )
+        elif isinstance(dims, tensor_shape_pb2.TensorShapeProto):
+            if dims.unknown_rank:
+                self._dims = None
+            else:
+                self._dims = [
+                    # Protos store variable-size dimensions as -1
+                    as_dimension(dim.size if dim.size != -1 else None)
+                    for dim in dims.dim
+                ]
+        elif isinstance(dims, TensorShape):
+            self._dims = dims.dims
+        else:
+            try:
+                dims_iter = iter(dims)
+            except TypeError:
+                # Treat as a singleton dimension
+                self._dims = [as_dimension(dims)]
+            else:
+                # Got a list of dimensions
+                self._dims = [as_dimension(d) for d in dims_iter]
+        self._ndims = None
+
+    def __repr__(self):
+        return "TensorShape(%r)" % self._dims
+
+    def __str__(self):
+        if self.ndims is None:
+            return "<unknown>"
+        elif self.ndims == 1:
+            return "(%s,)" % self._dims[0]
+        else:
+            return "(%s)" % ", ".join(str(d) for d in self._dims)
+
+    @property
+    def dims(self):
+        """Returns a list of Dimensions, or None if the shape is
+        unspecified."""
+        return self._dims
+
+    @dims.setter
+    def dims(self, dims):
+        self._dims = dims
+        self._ndims = None
+
+    @property
+    def ndims(self):
+        """Returns the rank of this shape, or None if it is unspecified."""
+        if self._dims is None:
+            return None
+        else:
+            if self._ndims is None:
+                self._ndims = len(self._dims)
+            return self._ndims
+
+    def __len__(self):
+        """Returns the rank of this shape, or raises ValueError if
+        unspecified."""
+        if self._dims is None:
+            raise ValueError(
+                "Cannot take the length of Shape with unknown rank."
+            )
+        return self.ndims
+
+    def __bool__(self):
+        """Returns True if this shape contains non-zero information."""
+        return self._dims is not None
+
+    # Python 3 wants __bool__, Python 2.7 wants __nonzero__
+    __nonzero__ = __bool__
+
+    def __iter__(self):
+        """Returns `self.dims` if the rank is known, otherwise raises
+        ValueError."""
+        if self._dims is None:
+            raise ValueError("Cannot iterate over a shape with unknown rank.")
+        else:
+            return iter(self._dims)
+
+    def __getitem__(self, key):
+        """Returns the value of a dimension or a shape, depending on the key.
+
+        Args:
+          key: If `key` is an integer, returns the dimension at that index;
+            otherwise if `key` is a slice, returns a TensorShape whose
+            dimensions are those selected by the slice from `self`.
+
+        Returns:
+          A dimension if `key` is an integer, or a `TensorShape` if `key` is a
+          slice.
+
+        Raises:
+          ValueError: If `key` is a slice, and any of its elements are negative, or
+            if `self` is completely unknown and the step is set.
+        """
+        if self._dims is not None:
+            if isinstance(key, slice):
+                return TensorShape(self._dims[key])
+            else:
+                return self._dims[key]
+        else:
+            if isinstance(key, slice):
+                start = key.start if key.start is not None else 0
+                stop = key.stop
+
+                if key.step is not None:
+                    # TODO(mrry): Handle these maybe.
+                    raise ValueError("Steps are not yet handled")
+                if stop is None:
+                    # NOTE(mrry): This implies that TensorShape(None) is convertible with
+                    # TensorShape(None)[1:], which is obviously not true. It would be
+                    # possible to track the number of dimensions symbolically,
+                    # and perhaps we should do that.
+                    return unknown_shape()
+                elif start < 0 or stop < 0:
+                    # TODO(mrry): Handle this better, as it will be useful for handling
+                    # suffixes of otherwise unknown shapes.
+                    return unknown_shape()
+                else:
+                    return unknown_shape(ndims=stop - start)
+            else:
+                return Dimension(None)
+
+    def num_elements(self):
+        """Returns the total number of elements, or none for incomplete
+        shapes."""
+        if self.is_fully_defined():
+            size = 1
+            for dim in self._dims:
+                size *= dim.value
+            return size
+        else:
+            return None
+
+    def merge_with(self, other):
+        """Returns a `TensorShape` combining the information in `self` and
+        `other`.
+
+        The dimensions in `self` and `other` are merged elementwise,
+        according to the rules defined for `Dimension.merge_with()`.
+
+        Args:
+          other: Another `TensorShape`.
+
+        Returns:
+          A `TensorShape` containing the combined information of `self` and
+          `other`.
+
+        Raises:
+          ValueError: If `self` and `other` are not convertible.
+        """
+        other = as_shape(other)
+        if self._dims is None:
+            return other
+        else:
+            try:
+                self.assert_same_rank(other)
+                new_dims = []
+                for i, dim in enumerate(self._dims):
+                    new_dims.append(dim.merge_with(other[i]))
+                return TensorShape(new_dims)
+            except ValueError:
+                raise ValueError(
+                    "Shapes %s and %s are not convertible" % (self, other)
+                )
+
+    def concatenate(self, other):
+        """Returns the concatenation of the dimension in `self` and `other`.
+
+        *N.B.* If either `self` or `other` is completely unknown,
+        concatenation will discard information about the other shape. In
+        future, we might support concatenation that preserves this
+        information for use with slicing.
+
+        Args:
+          other: Another `TensorShape`.
+
+        Returns:
+          A `TensorShape` whose dimensions are the concatenation of the
+          dimensions in `self` and `other`.
+        """
+        # TODO(mrry): Handle the case where we concatenate a known shape with a
+        # completely unknown shape, so that we can use the partial information.
+        other = as_shape(other)
+        if self._dims is None or other.dims is None:
+            return unknown_shape()
+        else:
+            return TensorShape(self._dims + other.dims)
+
+    def assert_same_rank(self, other):
+        """Raises an exception if `self` and `other` do not have convertible
+        ranks.
+
+        Args:
+          other: Another `TensorShape`.
+
+        Raises:
+          ValueError: If `self` and `other` do not represent shapes with the
+            same rank.
+        """
+        other = as_shape(other)
+        if self.ndims is not None and other.ndims is not None:
+            if self.ndims != other.ndims:
+                raise ValueError(
+                    "Shapes %s and %s must have the same rank" % (self, other)
+                )
+
+    def assert_has_rank(self, rank):
+        """Raises an exception if `self` is not convertible with the given
+        `rank`.
+
+        Args:
+          rank: An integer.
+
+        Raises:
+          ValueError: If `self` does not represent a shape with the given `rank`.
+        """
+        if self.ndims not in (None, rank):
+            raise ValueError("Shape %s must have rank %d" % (self, rank))
+
+    def with_rank(self, rank):
+        """Returns a shape based on `self` with the given rank.
+
+        This method promotes a completely unknown shape to one with a
+        known rank.
+
+        Args:
+          rank: An integer.
+
+        Returns:
+          A shape that is at least as specific as `self` with the given rank.
+
+        Raises:
+          ValueError: If `self` does not represent a shape with the given `rank`.
+        """
+        try:
+            return self.merge_with(unknown_shape(ndims=rank))
+        except ValueError:
+            raise ValueError("Shape %s must have rank %d" % (self, rank))
+
+    def with_rank_at_least(self, rank):
+        """Returns a shape based on `self` with at least the given rank.
+
+        Args:
+          rank: An integer.
+
+        Returns:
+          A shape that is at least as specific as `self` with at least the given
+          rank.
+
+        Raises:
+          ValueError: If `self` does not represent a shape with at least the given
+            `rank`.
+        """
+        if self.ndims is not None and self.ndims < rank:
+            raise ValueError(
+                "Shape %s must have rank at least %d" % (self, rank)
+            )
+        else:
+            return self
+
+    def with_rank_at_most(self, rank):
+        """Returns a shape based on `self` with at most the given rank.
+
+        Args:
+          rank: An integer.
+
+        Returns:
+          A shape that is at least as specific as `self` with at most the given
+          rank.
+
+        Raises:
+          ValueError: If `self` does not represent a shape with at most the given
+            `rank`.
+        """
+        if self.ndims is not None and self.ndims > rank:
+            raise ValueError(
+                "Shape %s must have rank at most %d" % (self, rank)
+            )
+        else:
+            return self
+
+    def is_convertible_with(self, other):
+        """Returns True iff `self` is convertible with `other`.
+
+        Two possibly-partially-defined shapes are convertible if there
+        exists a fully-defined shape that both shapes can represent. Thus,
+        convertibility allows the shape inference code to reason about
+        partially-defined shapes. For example:
+
+        * TensorShape(None) is convertible with all shapes.
+
+        * TensorShape([None, None]) is convertible with all two-dimensional
+          shapes, such as TensorShape([32, 784]), and also TensorShape(None). It is
+          not convertible with, for example, TensorShape([None]) or
+          TensorShape([None, None, None]).
+
+        * TensorShape([32, None]) is convertible with all two-dimensional shapes
+          with size 32 in the 0th dimension, and also TensorShape([None, None])
+          and TensorShape(None). It is not convertible with, for example,
+          TensorShape([32]), TensorShape([32, None, 1]) or TensorShape([64, None]).
+
+        * TensorShape([32, 784]) is convertible with itself, and also
+          TensorShape([32, None]), TensorShape([None, 784]), TensorShape([None,
+          None]) and TensorShape(None). It is not convertible with, for example,
+          TensorShape([32, 1, 784]) or TensorShape([None]).
+
+        The convertibility relation is reflexive and symmetric, but not
+        transitive. For example, TensorShape([32, 784]) is convertible with
+        TensorShape(None), and TensorShape(None) is convertible with
+        TensorShape([4, 4]), but TensorShape([32, 784]) is not convertible with
+        TensorShape([4, 4]).
+
+        Args:
+          other: Another TensorShape.
+
+        Returns:
+          True iff `self` is convertible with `other`.
+        """
+        other = as_shape(other)
+        if self._dims is not None and other.dims is not None:
+            if self.ndims != other.ndims:
+                return False
+            for x_dim, y_dim in zip(self._dims, other.dims):
+                if not x_dim.is_convertible_with(y_dim):
+                    return False
+        return True
+
+    def assert_is_convertible_with(self, other):
+        """Raises exception if `self` and `other` do not represent the same
+        shape.
+
+        This method can be used to assert that there exists a shape that both
+        `self` and `other` represent.
+
+        Args:
+          other: Another TensorShape.
+
+        Raises:
+          ValueError: If `self` and `other` do not represent the same shape.
+        """
+        if not self.is_convertible_with(other):
+            raise ValueError(
+                "Shapes %s and %s are inconvertible" % (self, other)
+            )
+
+    def most_specific_convertible_shape(self, other):
+        """Returns the most specific TensorShape convertible with `self` and
+        `other`.
+
+        * TensorShape([None, 1]) is the most specific TensorShape convertible with
+          both TensorShape([2, 1]) and TensorShape([5, 1]). Note that
+          TensorShape(None) is also convertible with above mentioned TensorShapes.
+
+        * TensorShape([1, 2, 3]) is the most specific TensorShape convertible with
+          both TensorShape([1, 2, 3]) and TensorShape([1, 2, 3]). There are more
+          less specific TensorShapes convertible with above mentioned TensorShapes,
+          e.g. TensorShape([1, 2, None]), TensorShape(None).
+
+        Args:
+          other: Another `TensorShape`.
+
+        Returns:
+          A `TensorShape` which is the most specific convertible shape of `self`
+          and `other`.
+        """
+
+        other = as_shape(other)
+        if (
+            self._dims is None
+            or other.dims is None
+            or self.ndims != other.ndims
+        ):
+            return unknown_shape()
+
+        dims = [Dimension(None)] * self.ndims
+        for i, (d1, d2) in enumerate(zip(self._dims, other.dims)):
+            if d1 is not None and d2 is not None and d1 == d2:
+                dims[i] = d1
+        return TensorShape(dims)
+
+    def is_fully_defined(self):
+        """Returns True iff `self` is fully defined in every dimension."""
+        return self._dims is not None and all(
+            dim.value is not None for dim in self._dims
+        )
+
+    def assert_is_fully_defined(self):
+        """Raises an exception if `self` is not fully defined in every
+        dimension.
+
+        Raises:
+          ValueError: If `self` does not have a known value for every dimension.
+        """
+        if not self.is_fully_defined():
+            raise ValueError("Shape %s is not fully defined" % self)
+
+    def as_list(self):
+        """Returns a list of integers or `None` for each dimension.
+
+        Returns:
+          A list of integers or `None` for each dimension.
+
+        Raises:
+          ValueError: If `self` is an unknown shape with an unknown rank.
+        """
+        if self._dims is None:
+            raise ValueError(
+                "as_list() is not defined on an unknown TensorShape."
+            )
+        return [dim.value for dim in self._dims]
+
+    def as_proto(self):
+        """Returns this shape as a `TensorShapeProto`."""
+        if self._dims is None:
+            return tensor_shape_pb2.TensorShapeProto(unknown_rank=True)
+        else:
+            return tensor_shape_pb2.TensorShapeProto(
+                dim=[
+                    tensor_shape_pb2.TensorShapeProto.Dim(
+                        size=-1 if d.value is None else d.value
+                    )
+                    for d in self._dims
+                ]
+            )
+
+    def __eq__(self, other):
+        """Returns True if `self` is equivalent to `other`."""
+        try:
+            other = as_shape(other)
+        except TypeError:
+            return NotImplemented
+        return self._dims == other.dims
+
+    def __ne__(self, other):
+        """Returns True if `self` is known to be different from `other`."""
+        try:
+            other = as_shape(other)
+        except TypeError:
+            return NotImplemented
+        if self.ndims is None or other.ndims is None:
+            raise ValueError(
+                "The inequality of unknown TensorShapes is undefined."
+            )
+        if self.ndims != other.ndims:
+            return True
+        return self._dims != other.dims
+
+    def __reduce__(self):
+        return TensorShape, (self._dims,)
+
+
+def as_shape(shape):
+    """Converts the given object to a TensorShape."""
+    if isinstance(shape, TensorShape):
+        return shape
+    else:
+        return TensorShape(shape)
+
+
+def unknown_shape(ndims=None):
+    """Returns an unknown TensorShape, optionally with a known rank.
+
+    Args:
+      ndims: (Optional) If specified, the number of dimensions in the shape.
+
+    Returns:
+      An unknown TensorShape.
+    """
+    if ndims is None:
+        return TensorShape(None)
+    else:
+        return TensorShape([Dimension(None)] * ndims)
+
+
+_SCALAR_SHAPE = TensorShape([])
+
+
+def scalar():
+    """Returns a shape representing a scalar."""
+    return _SCALAR_SHAPE
+
+
+def vector(length):
+    """Returns a shape representing a vector.
+
+    Args:
+      length: The length of the vector, which may be None if unknown.
+
+    Returns:
+      A TensorShape representing a vector of the given length.
+    """
+    return TensorShape([length])
+
+
+def matrix(rows, cols):
+    """Returns a shape representing a matrix.
+
+    Args:
+      rows: The number of rows in the matrix, which may be None if unknown.
+      cols: The number of columns in the matrix, which may be None if unknown.
+
+    Returns:
+      A TensorShape representing a matrix of the given size.
+    """
+    return TensorShape([rows, cols])