Core APIs

Core classes and functions in Home Assistant

The homeassistant.core module contains the fundamental classes that power Home Assistant.

HomeAssistant Class

The HomeAssistant class is the root object of the Home Assistant home automation system.

Initialization

config_dir · str · required

Path to the configuration directory

from homeassistant.core import HomeAssistant

hass = HomeAssistant("/config")

Key Attributes

data · HassDict

Dictionary that any component can store data on. This is the primary way to share data between components.

bus · EventBus

The event bus for firing and listening to events.

services · ServiceRegistry

The service registry for registering and calling services.

states · StateMachine

The state machine for tracking entity states.

config · Config

Configuration object containing Home Assistant settings.

state · CoreState

Current state of Home Assistant (NOT_RUNNING, STARTING, RUNNING, STOPPING, STOPPED).

loop · asyncio.AbstractEventLoop

The asyncio event loop.

Methods

async_start()

Finalize startup from inside the event loop.

await hass.async_start()

async_stop(exit_code: int = 0, *, force: bool = False)

Stop Home Assistant and shut down all threads.

exit_code · int · default: "0"

Exit code to return

force · bool · default: "False"

Force stop regardless of current state

await hass.async_stop()

async_create_task(target, name=None, eager_start=True)

Create a task from within the event loop.

target · Coroutine · required

Coroutine to execute

name · str

Name for the task (useful for debugging)

eager_start · bool · default: "True"

Whether to start the task eagerly

return · asyncio.Task

The created task

task = hass.async_create_task(
    my_coroutine(),
    name="my_task"
)

async_create_background_task(target, name, eager_start=True)

Create a background task that won’t block startup or shutdown.

target · Coroutine · required

Coroutine to execute

name · str · required

Name for the task

eager_start · bool · default: "True"

Whether to start the task eagerly

task = hass.async_create_background_task(
    long_running_task(),
    name="background_worker"
)

async_add_executor_job(target, *args)

Add an executor job from within the event loop.

target · Callable · required

Function to execute in the executor

*args · Any

Arguments to pass to the function

result = await hass.async_add_executor_job(
    blocking_function,
    arg1,
    arg2
)

State Class

Represents the state of an entity.

Initialization

entity_id · str · required

The entity ID (format: domain.object_id)

state · str · required

The state value

attributes · Mapping[str, Any]

Additional attributes for the state

last_changed · datetime

When the state was last changed

last_updated · datetime

When the state or attributes were last updated

context · Context

Context in which the state was created

from homeassistant.core import State

state = State(
    "light.living_room",
    "on",
    {"brightness": 255, "color_temp": 400}
)

Attributes

entity_id · str

The entity ID

state · str

The state value

attributes · ReadOnlyDict[str, Any]

Read-only dictionary of attributes

domain · str

Domain portion of the entity ID

object_id · str

Object ID portion of the entity ID

last_changed · datetime

When the state was last changed

last_updated · datetime

When the state or attributes were last updated

last_reported · datetime

Last time the state was reported

context · Context

Context object containing user_id, parent_id, and id

Methods

as_dict()

Return a read-only dictionary representation of the state.

state_dict = state.as_dict()
# Returns: {"entity_id": "...", "state": "...", "attributes": {...}, ...}

Event Class

Represents an event within the event bus.

Initialization

event_type · str · required

Type of the event

data · Mapping[str, Any]

Event data

origin · EventOrigin · default: "EventOrigin.local"

Origin of the event (local or remote)

context · Context

Context in which the event was fired

from homeassistant.core import Event, EventOrigin

event = Event(
    "my_event",
    {"some_key": "some_value"},
    EventOrigin.local
)

Attributes

event_type · str

Type of the event

data · Mapping[str, Any]

Event data dictionary

origin · EventOrigin

Origin of the event (local or remote)

time_fired · datetime

When the event was fired

context · Context

Context object

ServiceCall Class

Represents a call to a service.

Initialization

hass · HomeAssistant · required

Home Assistant instance

domain · str · required

Domain of the service

service · str · required

Name of the service

data · dict[str, Any]

Service call data

context · Context

Context for the service call

return_response · bool · default: "False"

Whether to return a response

from homeassistant.core import ServiceCall

call = ServiceCall(
    hass,
    "light",
    "turn_on",
    {"entity_id": "light.living_room", "brightness": 255}
)

Attributes

domain · str

Service domain

service · str

Service name

data · ReadOnlyDict[str, Any]

Service call data

context · Context

Context object

return_response · bool

Whether a response is expected

Context Class

Represents the context that triggered something.

Initialization

user_id · str

ID of the user who triggered the action

parent_id · str

ID of the parent context

id · str

Unique ID for this context (auto-generated if not provided)

from homeassistant.core import Context

context = Context(user_id="abc123")

Attributes

id · str

Unique context ID (ULID format)

user_id · str | None

User ID if triggered by a user

parent_id · str | None

Parent context ID if this is a child context

Helper Functions

callback(func)

Decorator to mark a method as safe to call from within the event loop.

from homeassistant.core import callback

@callback
def my_callback_function():
    # This function is safe to call from the event loop
    pass

async_get_hass()

Return the HomeAssistant instance from within the event loop.

from homeassistant.core import async_get_hass, callback

@callback
def my_function():
    hass = async_get_hass()
    # Use hass...

This function raises HomeAssistantError if called from the wrong thread. Use sparingly and prefer passing the hass instance as a parameter.

split_entity_id(entity_id: str)

Split a state entity ID into domain and object ID.

entity_id · str · required

Entity ID to split

return · tuple[str, str]

Tuple of (domain, object_id)

from homeassistant.core import split_entity_id

domain, object_id = split_entity_id("light.living_room")
# domain = "light", object_id = "living_room"

valid_entity_id(entity_id: str)

Test if an entity ID is in a valid format.

from homeassistant.core import valid_entity_id

if valid_entity_id("light.living_room"):
    print("Valid!")

CoreState Enum

Represents the current state of Home Assistant.

not_running · str

Home Assistant is not running

starting · str

Home Assistant is starting up

running · str

Home Assistant is running

stopping · str

Home Assistant is stopping

final_write · str

Final write stage during shutdown

stopped · str

Home Assistant has stopped

EventOrigin Enum

Represents the origin of an event.

local · str

Event originated locally

remote · str

Event originated from a remote source