Implementation:Bentoml BentoML Public API Module

Knowledge Sources	Bentoml_BentoML
Domains	Public API, Module System, Lazy Loading
Last Updated	2026-02-13 15:00 GMT

Overview

The top-level bentoml package __init__.py that defines the public API surface, implements lazy module loading for performance, and re-exports symbols from internal and SDK packages.

Description

This module serves as the primary entry point for the BentoML library. It uses a sophisticated lazy loading mechanism to avoid importing heavy dependencies until they are actually needed, which significantly reduces import time. The module is organized into several sections:

1. Version export: Imports and exposes __version__ from _internal.configuration.BENTOML_VERSION.

1. MODULE_ATTRS dictionary: A mapping of public attribute names to their fully qualified import paths (using "module:attr" notation). This dictionary powers the lazy __getattr__ mechanism and includes:
   • Core types: Bento, Model, Tag, Context, Cookie
   • Configuration: load_config, save_config, set_serialization_strategy
   • Cloud: BentoCloudClient, ApiToken, ApiTokenAPI
   • Bento management: get, build, delete, list, push, pull, serve, export_bento, import_bento
   • New SDK: service, Service, api, task, depends, Dependency, on_shutdown, on_startup, on_deployment, asgi_app, mount_asgi_app, IODescriptor
   • Clients: SyncHTTPClient, AsyncHTTPClient

1. TYPE_CHECKING block: When type checking (e.g., with Pyright), provides explicit imports for all public symbols. This enables full IDE autocompletion and type inference without actually running the lazy loading code.

1. Runtime lazy loading (the else branch):
   • Uses FrameworkImporter.install() to set up framework-specific lazy imports.
   • Creates LazyLoader instances for all submodules: bentos, legacy, io, batch, models, metrics, container, client, server, exceptions, monitoring, cloud, deployment, api_token, validators.
   • Creates LazyLoader instances for ML framework modules (catboost, sklearn, xgboost, lightgbm, mlflow, pytorch, tensorflow, transformers, etc.), many with deprecation warnings since v1.4.
   • Creates LazyLoader instances for integration modules (triton, ray, gradio).

1. __getattr__ function: Handles attribute lookups at runtime by:
   • First checking MODULE_ATTRS and dynamically importing the specified module and attribute.
   • Then checking the legacy module's __all__ for backwards compatibility, issuing deprecation warnings for moved symbols.
   • Raising AttributeError for unknown attributes.

1. __all__ list: Exports approximately 90 public symbols covering the complete BentoML API surface.

Usage

This is the primary import target for all BentoML users. Every import bentoml statement loads this module. The lazy loading design ensures that importing bentoml is fast even though the library supports many optional ML frameworks and integrations.

Code Reference

Source Location

• Repository: Bentoml_BentoML
• File: src/bentoml/__init__.py
• Lines: 1-410

Signature

# Key exported symbols
__version__: str

# Decorators and service construction
def service(...) -> ...: ...
class Service: ...
def api(...) -> ...: ...
def task(...) -> ...: ...
def depends(...) -> ...: ...
def on_shutdown(...) -> ...: ...
def on_startup(...) -> ...: ...
def on_deployment(...) -> ...: ...

# Bento management
def build(...) -> Bento: ...
def get(...) -> Bento: ...
def list(...) -> ...: ...
def push(...) -> ...: ...
def pull(...) -> ...: ...
def serve(...) -> ...: ...
def delete(...) -> ...: ...
def load(...) -> ...: ...

# Clients
class SyncHTTPClient: ...
class AsyncHTTPClient: ...

# Types
class Bento: ...
class Model: ...
class Tag: ...
class IODescriptor: ...

Import

import bentoml

# Direct symbol access
from bentoml import service, api, Service, Bento, Tag
from bentoml import SyncHTTPClient, AsyncHTTPClient

I/O Contract

Inputs

Name	Type	Required	Description
(module import)	Python import	Yes	import bentoml or from bentoml import ...

Outputs

Name	Type	Description
bentoml namespace	module	Fully populated module namespace with lazy-loaded submodules and attributes
__version__	str	Current BentoML version string
Public API symbols	Various	All symbols listed in __all__, loaded on demand

Usage Examples

import bentoml

# Check version
print(bentoml.__version__)

# Define a service
@bentoml.service
class MyService:
    @bentoml.api
    def predict(self, data: dict) -> dict:
        return {"result": "ok"}

# Build and manage bentos
bento = bentoml.build("service:MyService")
bentoml.push(bento.tag)

# Use clients
client = bentoml.SyncHTTPClient("http://localhost:3000")

# Access framework modules (lazy loaded)
bentoml.sklearn.save_model("my_model", model)

Related Pages

• Implementation:Bentoml_BentoML_IO_Models
• Implementation:Bentoml_BentoML_SDK_Validators
• Implementation:Bentoml_BentoML_Client_Base
• Implementation:Bentoml_BentoML_Project_Configuration