Python API

The dominant frontend. import tensorflow as tf exposes the entire public API surface, much of which is generated.

Purpose

• Construct ops on tensors (eager or graph).
• Define and train models (tf.keras, manual loops).
• Save/load (tf.saved_model, tf.train.Checkpoint).
• Build input pipelines (tf.data).
• Distribute training (tf.distribute).
• Convert and ship to mobile (tf.lite).

Directory layout

tensorflow/python/
├── __init__.py                # tiny — real entrypoint is generated
├── api_template.__init__.py   # template the build fills in
├── modules_with_exports.py    # registers which modules expose tf_export'd APIs
├── ops/                       # tf.* op wrappers (mostly auto-generated `gen_*.py`)
├── framework/                 # core types: Tensor, Operation, Graph, dtypes, errors
├── eager/                     # eager runtime bindings, polymorphic_function (tf.function)
├── data/                      # tf.data input pipelines
├── distribute/                # tf.distribute strategies
├── keras/                     # bundled v2 Keras (legacy snapshot, see apps/keras.md)
├── kernel_tests/              # tests for ops (~hundreds)
├── lite/                      # Python entry to TFLite converter
├── module/                    # tf.Module
├── ops/                       # math_ops, array_ops, control_flow_ops, gradients_*, ...
├── platform/                  # logging, sysconfig, gfile
├── profiler/                  # tf.profiler
├── saved_model/               # tf.saved_model.save/load
├── summary/                   # tf.summary writers
├── trackable/                 # base classes for checkpointable objects
├── training/                  # tf.train.Checkpoint, optimizers, queues, server
├── tpu/                       # TPU integration
├── types/                     # tf.types public protocols
└── util/                      # tf_export, decorators, lazy_loader

Key abstractions

Type / class	File	Role
tf.Tensor	tensorflow/python/framework/ops.py	The user-visible tensor.
tf.Operation	tensorflow/python/framework/ops.py	A graph node.
tf.Graph	tensorflow/python/framework/ops.py	Container of operations.
EagerTensor	tensorflow/python/framework/ops.py + C++ pybind code	Tensor that owns its value (no graph).
tf.Variable	tensorflow/python/ops/variables.py, resource_variable_ops.py	Mutable tensor-state, normally a ResourceVariable.
tf.function	tensorflow/python/eager/polymorphic_function/	Trace a Python fn into a graph.
tf.Module	tensorflow/python/module/module.py	Base class for trackable Python objects.
tf.errors.*	tensorflow/python/framework/errors_impl.py	Wrappers around C++ Status.
@tf_export	tensorflow/python/util/tf_export.py	Decorator that registers the public name.

How it works

graph LR
    User[user.py]
    PyOps[tf.add, tf.matmul, ...]
    GenOps[gen_math_ops.py auto-generated]
    Pybind[_pywrap_tensorflow*.cc / tfe_wrapper.cc]
    Eager[C++ EagerContext]
    Kernel[OpKernel runs on device]

    User --> PyOps
    PyOps --> GenOps
    GenOps -- _eager_fallback --> Pybind
    Pybind --> Eager
    Eager --> Kernel

In eager mode, calling tf.add(a, b) calls gen_math_ops.add(a, b), which calls into the C++ eager runtime through the pywrap_tfe pybind module. The eager runtime resolves the kernel for (Add, DEVICE_CPU/GPU, dtypes), runs it, and returns an EagerTensor.

In graph mode (inside a @tf.function or a tf.compat.v1.Session), calling tf.add(a, b) adds an Add node to the current Graph (or FuncGraph). The graph is later executed by the runtime.

tf.function is the bridge: it traces a Python function once per signature, captures the graph, and registers it with the function library so it can be called like an op in the future.

Generated wrappers

The bulk of tensorflow/python/ops/ is generated:

gen_math_ops.py
gen_array_ops.py
gen_nn_ops.py
gen_control_flow_ops.py
gen_resource_variable_ops.py
... (dozens more)

Each file is produced from the OpDef registrations in tensorflow/core/ops/. The generator is tensorflow/python/framework/python_op_gen_main.cc. Hand-written wrappers (e.g. math_ops.py, array_ops.py) layer convenient Python on top of the generated ones.

Public API export

A symbol becomes part of tf.* only if it has an @tf_export("foo.bar") decorator. The tensorflow/api_template.__init__.py and tensorflow/api_template_v1.__init__.py files are filled in at build time with a tree of _api/v2/ modules that re-export the canonical names. Golden files live under tensorflow/tools/api/golden/ and are checked by api_compatibility_test. Adding a new public API requires regenerating these goldens.

Integration points

• Pybind11 wrappers under tensorflow/python/: _pywrap_tensorflow*.cc, tfe_wrapper.cc, tf_session_helper.cc, pywrap_dtensor_device.cc, etc.
• Eager runtime in tensorflow/core/common_runtime/eager/ — the C++ side of every Python op call. See systems/eager-execution.
• Function library in tensorflow/core/framework/function.h — where @tf.function-traced graphs live.
• TFLite converter entrypoint at tensorflow/python/lite/python/lite.py. See apps/tensorflow-lite.

Entry points for modification

• Adding a new op: register OpDef in tensorflow/core/ops/, kernel in tensorflow/core/kernels/, and (optional) a hand-written wrapper in tensorflow/python/ops/<family>_ops.py. The auto-generator picks up the OpDef and emits gen_<family>_ops.py.
• Adding a new public Python class: place it under tensorflow/python/, decorate exports with @tf_export("foo.bar"), regenerate golden files via the test suite under tensorflow/tools/api/tests/.
• Touching tf.function semantics: most logic is in tensorflow/python/eager/polymorphic_function/. Tread carefully — virtually every other API depends on it.

Related

• c-api — what Python uses for cross-language interop with C++.
• keras — the bundled Keras frontend.
• systems/eager-execution — the C++ runtime that backs tf.add & friends.
• features/tf-function-and-autograph — Python control flow → graphs.