TensorFlow Type Stubs

Warnings

• gotcha The `types-tensorflow` package is marked as 'partial'. Type checkers, such as Pyright, often assume that if type stubs are present, they are authoritative for that module. This can lead to a lack of autocompletion or type information for parts of the TensorFlow API that are not yet covered by the stubs, rather than falling back to runtime introspection.
  Fix: Consult TensorFlow's official documentation for un-stubbed parts. Contribute to `typeshed` to help complete the stubs.
• breaking The `types-tensorflow` package aims to provide accurate annotations for specific TensorFlow minor versions (e.g., `tensorflow~=2.18.0`). Mismatches between the installed `types-tensorflow` version and your actual `tensorflow` runtime version can lead to incorrect or misleading type checking results, including false positives or missed errors.
  Fix: Always install `types-tensorflow` matching the minor version of your `tensorflow` installation, e.g., if you have `tensorflow==2.18.x`, install `types-tensorflow==2.18.x.YYYYMMDD`.
• gotcha TensorFlow's API relies heavily on dynamic method definitions, decorator magic, and internal re-exports (e.g., classes defined internally but exposed publicly via different paths). This complexity can make generating perfect type stubs challenging, potentially leading to situations where type checkers might produce false positives or fail to catch actual errors due to the discrepancies between the stub's static view and TensorFlow's runtime behavior.
  Fix: Be aware that some advanced or dynamically generated TensorFlow patterns might still require `type: ignore` comments or might not be perfectly covered by stubs. Consult TensorFlow documentation if types are unclear.
• breaking While `types-tensorflow` explicitly requires Python `>=3.10`, the underlying `tensorflow` library also has its own Python version compatibility requirements. For instance, TensorFlow 2.21 removed support for Python 3.9. Ensure that your Python environment satisfies the requirements of *both* `types-tensorflow` and the specific version of `tensorflow` you intend to use.
  Fix: Always verify Python compatibility with both the `types-tensorflow` package and your `tensorflow` installation. Upgrade your Python version if necessary.

Install

• pip install types-tensorflow Install types-tensorflow
• pip install tensorflow Install TensorFlow (required runtime dependency)

Imports

• tf

  import tensorflow as tf

  types-tensorflow provides stubs for the `tensorflow` library; users directly import `tensorflow`, and type checkers then utilize the installed `types-tensorflow` package for static analysis. There is no direct import for `types-tensorflow` itself.

Quickstart

This quickstart demonstrates how to write type-hinted TensorFlow code that `types-tensorflow` can then be used to check with a static type checker like `mypy` or `pyright`. It shows basic tensor creation and manipulation with Python type annotations.

import tensorflow as tf

def create_and_add_constants(val1: int, val2: int) -> tf.Tensor:
    """Creates two constant tensors from ints and adds them."""
    tensor1 = tf.constant(val1, dtype=tf.int32)
    tensor2 = tf.constant(val2, dtype=tf.int32)
    return tf.add(tensor1, tensor2)

def concatenate_tensors(tensors: list[tf.Tensor]) -> tf.Tensor:
    """Concatenates a list of tensors along axis 0."""
    return tf.concat(tensors, axis=0)

if __name__ == "__main__":
    # Example 1: Basic addition with type hints
    sum_result = create_and_add_constants(10, 20)
    print(f"Sum result (numpy value): {sum_result.numpy()}")

    # Example 2: Concatenation with explicit type hints
    tensor_a = tf.constant([1.0, 2.0], dtype=tf.float32)
    tensor_b = tf.constant([3.0, 4.0], dtype=tf.float32)
    combined_tensors = concatenate_tensors([tensor_a, tensor_b])
    print(f"Concatenated tensors (numpy value): {combined_tensors.numpy()}")

    # To run type checking:
    # 1. Save this code as `tf_example.py`.
    # 2. Install a type checker (e.g., `pip install mypy`).
    # 3. Run `mypy tf_example.py` in your terminal.
    #    Expected output: Success (no errors) if code is correctly typed.