python-zeroconf API reference

This module provides a framework for the use of DNS Service Discovery using IP multicast.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

exception zeroconf.AbstractMethodException[source]

Bases: Error

Exception when a required method is not implemented.

exception zeroconf.BadTypeInNameException[source]

Bases: Error

Exception when the type in a name is invalid.

class zeroconf.DNSQuestionType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

An MDNS question type.

“QU” - questions requesting unicast responses “QM” - questions requesting multicast responses https://datatracker.ietf.org/doc/html/rfc6762#section-5.4

QM = 2

QU = 1

exception zeroconf.Error[source]

Bases: Exception

Base class for all zeroconf exceptions.

exception zeroconf.EventLoopBlocked[source]

Bases: Error

Exception when the event loop is blocked.

This exception is never expected to be thrown during normal operation. It should only happen when the cpu is maxed out or there is something blocking the event loop.

exception zeroconf.IncomingDecodeError[source]

Bases: Error

Exception when there is invalid data in an incoming packet.

exception zeroconf.NamePartTooLongException[source]

Bases: Error

Exception when the name is too long.

exception zeroconf.NonUniqueNameException[source]

Bases: Error

Exception when the name is already registered.

exception zeroconf.NotRunningException[source]

Bases: Error

Exception when an action is called with a zeroconf instance that is not running.

The instance may not be running because it was already shutdown or startup has failed in some unexpected way.

class zeroconf.RecordUpdateListener[source]

Bases: object

Base call for all record listeners.

All listeners passed to async_add_listener should use RecordUpdateListener as a base class. In the future it will be required.

async_update_records(zc: Zeroconf, now: float_, records: list[RecordUpdate]) → None[source]

Update multiple records in one shot.

All records that are received in a single packet are passed to update_records.

This implementation is a compatibility shim to ensure older code that uses RecordUpdateListener as a base class will continue to get calls to update_record. This method will raise NotImplementedError in a future version.

At this point the cache will not have the new records

Records are passed as a list of RecordUpdate. This allows consumers of async_update_records to avoid cache lookups.

This method will be run in the event loop.

async_update_records_complete() → None[source]

Called when a record update has completed for all handlers.

At this point the cache will have the new records.

This method will be run in the event loop.

update_record(zc: Zeroconf, now: float, record: DNSRecord) → None[source]

Update a single record.

This method is deprecated and will be removed in a future version. update_records should be implemented instead.

class zeroconf.ServiceBrowser(zc: Zeroconf, type_: str | list, handlers: ServiceListener | list[Callable[..., None]] | None = None, listener: ServiceListener | None = None, addr: str | None = None, port: int = 5353, delay: int = 10000, question_type: DNSQuestionType | None = None)[source]

Bases: _ServiceBrowserBase, Thread

Used to browse for a service of a specific type.

The listener object will have its add_service() and remove_service() methods called when this browser discovers changes in the services availability.

async_update_records_complete() → None[source]

Called when a record update has completed for all handlers.

At this point the cache will have the new records.

This method will be run in the event loop.

cancel() → None[source]: Cancel the browser.

done

query_scheduler

run() → None[source]: Run the browser thread.

types: set[str]

zc

class zeroconf.ServiceInfo(type_: str, name: str, port: int | None = None, weight: int = 0, priority: int = 0, properties: bytes | dict = b'', server: str | None = None, host_ttl: int = 120, other_ttl: int = 4500, *, addresses: list[bytes] | None = None, parsed_addresses: list[str] | None = None, interface_index: int | None = None)[source]

Bases: RecordUpdateListener

Service information.

Constructor parameters are as follows:

type_: fully qualified service type name
name: fully qualified service name
port: port that the service runs on
weight: weight of the service
priority: priority of the service
properties: dictionary of properties (or a bytes object holding the contents of the text field). converted to str and then encoded to bytes using UTF-8. Keys with None values are converted to value-less attributes.
server: fully qualified name for service host (defaults to name)
host_ttl: ttl used for A/SRV records
other_ttl: ttl used for PTR/TXT records
addresses and parsed_addresses: List of IP addresses (either as bytes, network byte order, or in parsed form as text; at most one of those parameters can be provided)
interface_index: scope_id or zone_id for IPv6 link-local addresses i.e. an identifier of the interface where the peer is connected to

property addresses: list[bytes]

IPv4 addresses of this service.

Only IPv4 addresses are returned for backward compatibility. Use addresses_by_version() or parsed_addresses() to include IPv6 addresses as well.

addresses_by_version(version: IPVersion) → list[bytes][source]

List addresses matching IP version.

Addresses are guaranteed to be returned in LIFO (last in, first out) order with IPv4 addresses first and IPv6 addresses second.

This means the first address will always be the most recently added address of the given IP version.

async_clear_cache() → None[source]: Clear the cache for this service info.

async async_request(zc: Zeroconf, timeout: float, question_type: DNSQuestionType | None = None, addr: str | None = None, port: int = 5353) → bool[source]

Returns true if the service could be discovered on the network, and updates this object with details discovered.

This method will be run in the event loop.

Passing addr and port is optional, and will default to the mDNS multicast address and port. This is useful for directing requests to a specific host that may be able to respond across subnets.

Parameters:

zc – Zeroconf instance
timeout – time in milliseconds to wait for a response
question_type – question type to ask
addr – address to send the request to
port – port to send the request to

async_update_records(zc: Zeroconf, now: float_, records: list[RecordUpdate]) → None[source]

Updates service information from a DNS record.

This method will be run in the event loop.

async async_wait(timeout: float, loop: AbstractEventLoop | None = None) → None[source]: Calling task waits for a given number of milliseconds or until notified.

property decoded_properties: dict[str, str | None]: Return properties as strings.

dns_addresses(override_ttl: int | None = None, version: IPVersion = IPVersion.All) → list[DNSAddress][source]: Return matching DNSAddress from ServiceInfo.

dns_nsec(missing_types: list[int], override_ttl: int | None = None) → DNSNsec[source]: Return DNSNsec from ServiceInfo.

dns_pointer(override_ttl: int | None = None) → DNSPointer[source]: Return DNSPointer from ServiceInfo.

dns_service(override_ttl: int | None = None) → DNSService[source]: Return DNSService from ServiceInfo.

dns_text(override_ttl: int | None = None) → DNSText[source]: Return DNSText from ServiceInfo.

get_address_and_nsec_records(override_ttl: int | None = None) → set[DNSRecord][source]: Build a set of address records and NSEC records for non-present record types.

get_name() → str[source]: Name accessor

host_ttl

interface_index

ip_addresses_by_version(version: IPVersion) → list[ZeroconfIPv4Address] | list[ZeroconfIPv6Address][source]

List ip_address objects matching IP version.

Addresses are guaranteed to be returned in LIFO (last in, first out) order with IPv4 addresses first and IPv6 addresses second.

This means the first address will always be the most recently added address of the given IP version.

key

load_from_cache(zc: Zeroconf, now: float_ | None = None) → bool[source]

Populate the service info from the cache.

This method is designed to be threadsafe.

property name: str: The name of the service.

other_ttl

parsed_addresses(version: IPVersion = IPVersion.All) → list[str][source]

List addresses in their parsed string form.

Addresses are guaranteed to be returned in LIFO (last in, first out) order with IPv4 addresses first and IPv6 addresses second.

This means the first address will always be the most recently added address of the given IP version.

parsed_scoped_addresses(version: IPVersion = IPVersion.All) → list[str][source]

Equivalent to parsed_addresses, with the exception that IPv6 Link-Local addresses are qualified with %<interface_index> when available

Addresses are guaranteed to be returned in LIFO (last in, first out) order with IPv4 addresses first and IPv6 addresses second.

This means the first address will always be the most recently added address of the given IP version.

port

priority

property properties: dict[bytes, bytes | None]: Return properties as bytes.

request(zc: Zeroconf, timeout: float, question_type: DNSQuestionType | None = None, addr: str | None = None, port: int = 5353) → bool[source]

Returns true if the service could be discovered on the network, and updates this object with details discovered.

While it is not expected during normal operation, this function may raise EventLoopBlocked if the underlying call to async_request cannot be completed.

Parameters:

zc – Zeroconf instance
timeout – time in milliseconds to wait for a response
question_type – question type to ask
addr – address to send the request to
port – port to send the request to

server

server_key

set_server_if_missing() → None[source]

Set the server if it is missing.

This function is for backwards compatibility.

text

type

weight

exception zeroconf.ServiceNameAlreadyRegistered[source]

Bases: Error

Exception when a service name is already registered.

class zeroconf.Zeroconf(interfaces: Sequence[str | int | tuple[tuple[str, int, int], int]] | InterfaceChoice = InterfaceChoice.All, unicast: bool = False, ip_version: IPVersion | None = None, apple_p2p: bool = False, use_asyncio: bool | None = None)[source]

Bases: QuietLogger

Implementation of Zeroconf Multicast DNS Service Discovery

Supports registration, unregistration, queries and browsing.

add_listener(listener: RecordUpdateListener, question: DNSQuestion | list[DNSQuestion] | None) → None[source]

Adds a listener for a given question. The listener will have its update_record method called when information is available to answer the question(s).

This function is threadsafe

add_service_listener(type_: str, listener: ServiceListener) → None[source]: Adds a listener for a particular service type. This object will then have its add_service and remove_service methods called when services of that type become available and unavailable.

async_add_listener(listener: RecordUpdateListener, question: DNSQuestion | list[DNSQuestion] | None) → None[source]

Adds a listener for a given question. The listener will have its update_record method called when information is available to answer the question(s).

This function is not threadsafe and must be called in the eventloop.

async async_check_service(info: ServiceInfo, allow_name_change: bool, cooperating_responders: bool = False, strict: bool = True) → None[source]: Checks the network for a unique service name, modifying the ServiceInfo passed in if it is not unique.

async async_get_service_info(type_: str, name: str, timeout: int = 3000, question_type: DNSQuestionType | None = None) → AsyncServiceInfo | None[source]

Returns network’s service information for a particular name and type, or None if no service matches by the timeout, which defaults to 3 seconds.

Parameters:

type – fully qualified service type name
name – the name of the service
timeout – milliseconds to wait for a response
question_type – The type of questions to ask (DNSQuestionType.QM or DNSQuestionType.QU)

async_notify_all() → None[source]: Schedule an async_notify_all.

async async_register_service(info: ServiceInfo, ttl: int | None = None, allow_name_change: bool = False, cooperating_responders: bool = False, strict: bool = True) → Awaitable[source]: Registers service information to the network with a default TTL. Zeroconf will then respond to requests for information for that service. The name of the service may be changed if needed to make it unique on the network. Additionally multiple cooperating responders can register the same service on the network for resilience (if you want this behavior set cooperating_responders to True).

async_remove_listener(listener: RecordUpdateListener) → None[source]

Removes a listener.

This function is not threadsafe and must be called in the eventloop.

async_send(out: DNSOutgoing, addr: str | None = None, port: int = 5353, v6_flow_scope: tuple[()] | tuple[int, int] = (), transport: _WrappedTransport | None = None) → None[source]: Sends an outgoing packet.

async async_unregister_all_services() → None[source]

Unregister all registered services.

Unlike async_register_service and async_unregister_service, this method does not return a future and is always expected to be awaited since its only called at shutdown.

async async_unregister_service(info: ServiceInfo) → Awaitable[source]: Unregister a service.

async async_update_service(info: ServiceInfo) → Awaitable[source]: Registers service information to the network with a default TTL. Zeroconf will then respond to requests for information for that service.

async async_wait(timeout: float) → None[source]: Calling task waits for a given number of milliseconds or until notified.

async async_wait_for_start(timeout: float = 9) → None[source]

Wait for start up for actions that require a running Zeroconf instance.

Throws NotRunningException if the instance is not running or could not be started.

close() → None[source]

Ends the background threads, and prevent this instance from servicing further queries.

This method is idempotent and irreversible.

generate_service_broadcast(info: ServiceInfo, ttl: int | None, broadcast_addresses: bool = True) → DNSOutgoing[source]: Generate a broadcast to announce a service.

generate_service_query(info: ServiceInfo) → DNSOutgoing[source]: Generate a query to lookup a service.

generate_unregister_all_services() → DNSOutgoing | None[source]: Generate a DNSOutgoing goodbye for all services and remove them from the registry.

get_service_info(type_: str, name: str, timeout: int = 3000, question_type: DNSQuestionType | None = None) → ServiceInfo | None[source]

Returns network’s service information for a particular name and type, or None if no service matches by the timeout, which defaults to 3 seconds.

Parameters:

type – fully qualified service type name
name – the name of the service
timeout – milliseconds to wait for a response
question_type – The type of questions to ask (DNSQuestionType.QM or DNSQuestionType.QU)

notify_all() → None[source]: Notifies all waiting threads and notify listeners.

register_service(info: ServiceInfo, ttl: int | None = None, allow_name_change: bool = False, cooperating_responders: bool = False, strict: bool = True) → None[source]

Registers service information to the network with a default TTL. Zeroconf will then respond to requests for information for that service. The name of the service may be changed if needed to make it unique on the network. Additionally multiple cooperating responders can register the same service on the network for resilience (if you want this behavior set cooperating_responders to True).

While it is not expected during normal operation, this function may raise EventLoopBlocked if the underlying call to register_service cannot be completed.

remove_all_service_listeners() → None[source]: Removes a listener from the set that is currently listening.

remove_listener(listener: RecordUpdateListener) → None[source]

Removes a listener.

This function is threadsafe

remove_service_listener(listener: ServiceListener) → None[source]: Removes a listener from the set that is currently listening.

send(out: DNSOutgoing, addr: str | None = None, port: int = 5353, v6_flow_scope: tuple[()] | tuple[int, int] = (), transport: _WrappedTransport | None = None) → None[source]: Sends an outgoing packet threadsafe.

start() → None[source]: Start Zeroconf.

property started: bool: Check if the instance has started.

unregister_all_services() → None[source]

Unregister all registered services.

While it is not expected during normal operation, this function may raise EventLoopBlocked if the underlying call to async_unregister_all_services cannot be completed.

unregister_service(info: ServiceInfo) → None[source]

Unregister a service.

While it is not expected during normal operation, this function may raise EventLoopBlocked if the underlying call to async_unregister_service cannot be completed.

update_service(info: ServiceInfo) → None[source]

Registers service information to the network with a default TTL. Zeroconf will then respond to requests for information for that service.

While it is not expected during normal operation, this function may raise EventLoopBlocked if the underlying call to async_update_service cannot be completed.

class zeroconf.ZeroconfServiceTypes[source]

Bases: ServiceListener

Return all of the advertised services on any local networks

add_service(zc: Zeroconf, type_: str, name: str) → None[source]: Service added.

Return all of the advertised services on any local networks.

Parameters:

zc – Zeroconf() instance. Pass in if already have an instance running or if non-default interfaces are needed
timeout – seconds to wait for any responses
interfaces – interfaces to listen on.
ip_version – IP protocol version to use.

Returns:

tuple of service type strings

remove_service(zc: Zeroconf, type_: str, name: str) → None[source]: Service removed.

update_service(zc: Zeroconf, type_: str, name: str) → None[source]: Service updated.

zeroconf.current_time_millis() → float[source]

Current time in milliseconds.

The current implementation uses time.monotonic but may change in the future.

The design requires the time to match asyncio.loop.time()

This module provides a framework for the use of DNS Service Discovery using IP multicast.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

class zeroconf.asyncio.AsyncServiceBrowser(zeroconf: Zeroconf, type_: str | list, handlers: ServiceListener | list[Callable[[...], None]] | None = None, listener: ServiceListener | None = None, addr: str | None = None, port: int = 5353, delay: int = 10000, question_type: DNSQuestionType | None = None)[source]

Bases: _ServiceBrowserBase

Used to browse for a service for specific type(s).

Constructor parameters are as follows:

zc: A Zeroconf instance
type_: fully qualified service type name
handler: ServiceListener or Callable that knows how to process ServiceStateChange events
listener: ServiceListener
addr: address to send queries (will default to multicast)
port: port to send queries (will default to mdns 5353)
delay: The initial delay between answering questions
question_type: The type of questions to ask (DNSQuestionType.QM or DNSQuestionType.QU)

The listener object will have its add_service() and remove_service() methods called when this browser discovers changes in the services availability.

async async_cancel() → None[source]: Cancel the browser.

done

query_scheduler

types: set[str]

zc

class zeroconf.asyncio.AsyncServiceInfo(type_: str, name: str, port: int | None = None, weight: int = 0, priority: int = 0, properties: bytes | dict = b'', server: str | None = None, host_ttl: int = 120, other_ttl: int = 4500, *, addresses: list[bytes] | None = None, parsed_addresses: list[str] | None = None, interface_index: int | None = None)[source]

Bases: ServiceInfo

An async version of ServiceInfo.

host_ttl

interface_index

key

other_ttl

port

priority

server

server_key

text

type

weight

class zeroconf.asyncio.AsyncZeroconf(interfaces: Sequence[str | int | tuple[tuple[str, int, int], int]] | InterfaceChoice = InterfaceChoice.All, unicast: bool = False, ip_version: IPVersion | None = None, apple_p2p: bool = False, zc: Zeroconf | None = None)[source]

Bases: object

Implementation of Zeroconf Multicast DNS Service Discovery

Supports registration, unregistration, queries and browsing.

The async version is currently a wrapper around Zeroconf which is now also async. It is expected that an asyncio event loop is already running before creating the AsyncZeroconf object.

async async_add_service_listener(type_: str, listener: ServiceListener) → None[source]: Adds a listener for a particular service type. This object will then have its add_service and remove_service methods called when services of that type become available and unavailable.

async async_close() → None[source]: Ends the background threads, and prevent this instance from servicing further queries.

async async_get_service_info(type_: str, name: str, timeout: int = 3000, question_type: DNSQuestionType | None = None) → AsyncServiceInfo | None[source]

Returns network’s service information for a particular name and type, or None if no service matches by the timeout, which defaults to 3 seconds.

Parameters:

type – fully qualified service type name
name – the name of the service
timeout – milliseconds to wait for a response
question_type – The type of questions to ask (DNSQuestionType.QM or DNSQuestionType.QU)

async async_register_service(info: ServiceInfo, ttl: int | None = None, allow_name_change: bool = False, cooperating_responders: bool = False, strict: bool = True) → Awaitable[source]

Registers service information to the network with a default TTL. Zeroconf will then respond to requests for information for that service. The name of the service may be changed if needed to make it unique on the network. Additionally multiple cooperating responders can register the same service on the network for resilience (if you want this behavior set cooperating_responders to True).

The service will be broadcast in a task. This task is returned and therefore can be awaited if necessary.

async async_remove_all_service_listeners() → None[source]: Removes a listener from the set that is currently listening.

async async_remove_service_listener(listener: ServiceListener) → None[source]: Removes a listener from the set that is currently listening.

async async_unregister_all_services() → None[source]

Unregister all registered services.

Unlike async_register_service and async_unregister_service, this method does not return a future and is always expected to be awaited since its only called at shutdown.

async async_unregister_service(info: ServiceInfo) → Awaitable[source]

Unregister a service.

The service will be broadcast in a task. This task is returned and therefore can be awaited if necessary.

async async_update_service(info: ServiceInfo) → Awaitable[source]

Registers service information to the network with a default TTL. Zeroconf will then respond to requests for information for that service.

The service will be broadcast in a task. This task is returned and therefore can be awaited if necessary.

class zeroconf.asyncio.AsyncZeroconfServiceTypes[source]

Bases: ZeroconfServiceTypes

An async version of ZeroconfServiceTypes.

Return all of the advertised services on any local networks.

Parameters:

aiozc – AsyncZeroconf() instance. Pass in if already have an instance running or if non-default interfaces are needed
timeout – seconds to wait for any responses
interfaces – interfaces to listen on.
ip_version – IP protocol version to use.

Returns:

tuple of service type strings