Structure and API

fritzconnection is structured into subpackages:

fritzconnection --|-- cli
                  |-- core --|-- devices
                  |          |-- exceptions
                  |          |-- fritzconnection
                  |          |-- processor
                  |          |-- soaper
                  |          |-- utils
                  |
                  |-- lib
                  |-- tests

The package cli implements the entry-points for command line usage, the tests are in the tests package and the library modules are in lib. The implementation of fritzconnection itself is structured in the core package.

Public API

The public interface is provided by the FritzConnection class and the exceptions module.

As a shortcut FritzConnection can get imported by:

from fritzconnection import FritzConnection

fritzconnection

Module to communicate with the AVM Fritz!Box.

class fritzconnection.core.fritzconnection.FritzConnection(address=None, port=None, user=None, password=None, timeout=None, use_tls=False)

Main class to set up a connection to the Fritz!Box router. All parameters are optional. address should be the ip of a router, in case that are multiple Fritz!Box routers in a network, the ip must be given. Otherwise it is undefined which router will respond. If user and password are not provided, the environment gets checked for FRITZ_USERNAME and FRITZ_PASSWORD settings and taken from there, if found.

The optional parameter timeout is a floating number in seconds limiting the time waiting for a router response. This is a global setting for the internal communication with the router. In case of a timeout a requests.ConnectTimeout exception gets raised. (New in version 1.1)

use_tls accepts a boolean for using encrypted communication with the Fritz!Box. Default is False. (New in version 1.2)

call_action(service_name, action_name, *, arguments=None, **kwargs)

Executes the given action of the given service. Both parameters are required. Arguments are optional and can be provided as a dictionary given to ‘arguments’ or as separate keyword parameters. If ‘arguments’ is given additional keyword-parameters as further arguments are ignored. If the service_name does not end with a number (like 1), a 1 gets added by default. If the service_name ends with a colon and a number, the colon gets removed. So i.e. WLANConfiguration expands to WLANConfiguration1 and WLANConfiguration:2 converts to WLANConfiguration2. Invalid service names will raise a ServiceError and invalid action names will raise an ActionError.

modelname

Returns the modelname of the router.

static normalize_name(name)

Returns the normalized service name. E.g. WLANConfiguration and WLANConfiguration:1 will get converted to WLANConfiguration1.

reconnect()

Terminate the connection and reconnects with a new ip.

services

Dictionary of service instances. Keys are the service names.

static set_protocol(url, use_tls)

Sets the protocol of the url according to the use_tls-flag and returns the modified url. Does not check whether the url given as parameter is correct.

system_version

Returns system version if known, otherwise None.

exceptions

Exceptions can get imported by:

from fritzconnection.core.exceptions import FritzServiceError
# or:
from fritzconnection.core.exceptions import *

The latter style is often discouraged because of possible namespace-pollution, less clarity about the origin of imported objects and potential name clashings. By using a * import fritzconnection will just import exceptions starting with Fritz in their names.

Exception Hierarchy:

FritzConnectionException
                |
                |--> ActionError --> FritzActionError
                |--> ServiceError --> FritzServiceError
                |
                |--> FritzArgumentError
                |       |
                |       |--> FritzArgumentValueError
                |               |
                |               |--> FritzArgumentStringToShortError
                |               |--> FritzArgumentStringToLongError
                |               |--> FritzArgumentCharacterError
                |
                |--> FritzInternalError
                |       |
                |       |--> FritzActionFailedError
                |       |--> FritzOutOfMemoryError
                |
                |--> FritzSecurityError
                |
                |-->|--> FritzLookUpError
                |   |
KeyError -------+-->|
                |
                |
                |-->|--> FritzArrayIndexError
                    |
IndexError -------->|

Module defining fritzconnection specific exceptions.

exception fritzconnection.core.exceptions.FritzConnectionException

Base Exception for communication errors with the Fritz!Box

exception fritzconnection.core.exceptions.FritzActionError

Exception raised by calling nonexisting actions.

exception fritzconnection.core.exceptions.FritzActionFailedError

Exception raised by the box unable to execute the action properly. Inherits from the more generic FritzInternalError.

exception fritzconnection.core.exceptions.FritzArgumentCharacterError

Exception raised by arguments with invalid characters. Inherits from the more generic FritzArgumentValueError.

exception fritzconnection.core.exceptions.FritzArgumentError

Exception raised by invalid arguments.

exception fritzconnection.core.exceptions.FritzArgumentStringToLongError

Exception raised by arguments with invalid string length for the string being to long. Inherits from the more generic FritzArgumentValueError.

exception fritzconnection.core.exceptions.FritzArgumentStringToShortError

Exception raised by arguments with invalid string length for the string being to short. Inherits from the more generic FritzArgumentValueError.

exception fritzconnection.core.exceptions.FritzArgumentValueError

Exception raised by arguments with invalid values. Inherits from the more generic FritzArgumentError.

exception fritzconnection.core.exceptions.FritzArrayIndexError

Addressing an entry in an internal array by index failed. Inherits from IndexError. So IndexError can also be used for exception handling.

exception fritzconnection.core.exceptions.FritzInternalError

Exception raised by panic in the box.

exception fritzconnection.core.exceptions.FritzLookUpError

Lookup for id or entry in existing internal array failed. Inherits from KeyError. So KeyError can also be used for exception handling.

exception fritzconnection.core.exceptions.FritzOutOfMemoryError

Exception raised by memory shortage of the box. Inherits from the more generic FritzInternalError.

exception fritzconnection.core.exceptions.FritzSecurityError

Authorization error or wrong security context.

exception fritzconnection.core.exceptions.FritzServiceError

Exception raised by calling nonexisting services.

Legathy Exceptions:

exception fritzconnection.core.exceptions.ActionError

Exception raised by calling nonexisting actions. Legathy Exception. Use FritzActionError instead.

exception fritzconnection.core.exceptions.ServiceError

Exception raised by calling nonexisting services. Legathy Exception. Use FritzServiceError instead.

Internal API

The devices-, processor- and soaper-module don’t provide a public interface and are used internally.

devices

Implements the DeviceManager for physical and virtual devices. Every physical device (a router) has a set of virtual subdevices.

class fritzconnection.core.devices.DeviceManager(timeout=None, session=None)

Knows all data about the device and the subdevices, including the available services. Takes an optional timeout parameter to limit the time waiting for a router response. The optional parameter session is a reusable connection and can speed up the communication with the device. In case session is given, timeout will not get used.

add_description(source)

Adds description data about the devices and the according services. ‘source’ is a string with the xml-data, like the content of an igddesc- or tr64desc-file.

load_service_descriptions(address, port)

Triggers the load of the scpd files of the services, so they known their actions.

modelname

Take the root-device of the first description and return the according modelname. This is the name of the Fritz!Box itself. Will raise an IndexError if the method is called before descriptions are added.

scan()

Scans all available services defined by the description files. Must get called after all xml-descriptions are added.

system_version

Returns a tuple with version, display and buildnumber from the first description providing this informations. Returns None if no system informations are available.

processor

Module to parse and store the device description and the service data provided by xml and the scpd protocol based on xml. Names partly violate PEP8 representing node-names from xml description files.

class fritzconnection.core.processor.Action

Every Action has a name and a list of arguments.

arguments

Returns the action-arguments as a dict. argument-names are the keys and the argument objects are the values. The dictionary gets cached.

class fritzconnection.core.processor.ActionList(storage)

Collection of actions of a service. The Action instances are stored in the Scpd.actions attribute.

class fritzconnection.core.processor.Argument

An argument with name, direction and relatedStateVariable attributes.

class fritzconnection.core.processor.ArgumentList(storage)

Collects the arguments for an action.

class fritzconnection.core.processor.Description(root)

Root class for a given description information as the content from the files igddesc.xml or tr64desc.xml.

services

Returns dictionary with the known services as values and the according service-names as keys.

system_buildnumber

Returns the buildnumber or None. This information is only available by the ‘tr64desc.xml’ file.

system_display

Returns the system display-string or None. This information is only available by the ‘tr64desc.xml’ file.

system_version

Returns the system version of the Fritz!Box as a string like ‘7.10’ or None. This information is only available by the ‘tr64desc.xml’ file.

class fritzconnection.core.processor.Device

Storage for devices attributes and device subnodes. Subnodes are the serviceList and the deviceList. The services provided by a device are collected in services. Subdevices are collected in devices. All instance attributes are public for read only use.

class fritzconnection.core.processor.DeviceList(storage)

Collection of sub-devices of a device. The Device instances are stored in the device.devices attribute of the parent device.

class fritzconnection.core.processor.InstanceAttributeFactory(cls)

Non data descriptor returning instances of ‘cls’ and registering these instances in the ‘_storage’ attribute of the calling instance.

class fritzconnection.core.processor.Scpd(root)

Provides informations about the Service Control Point Definitions for every Service. Every Service has one instance of this class for accessing the description of it’s own actions and the according parameters. Root class for processing the content of an scpd-file.

actions

Returns a dictionary with the actions from the actions-list. The action-names are the keys and the actions themself are the values.

state_variables

Returns a dictionary with the state_variable name as keys and the StateVariable itself as value.

class fritzconnection.core.processor.Service

Class describing a service.

actions

Returns all known actions of this service as a dictionary. Action names are keys, the action objects are the values. Caches the dictionary once retrieved from _scpd.

load_scpd(address, port, timeout=None, session=None)

Loads the scpd data

state_variables

Returns all known stateVariables of this service as a dictionary. Names are keys, the stateVariables objects are the values. Caches the dictionary once retrieved from _scpd.

class fritzconnection.core.processor.ServiceList(storage)

Collection of Service instances for a device. The service instances are stored in the device.services attribute.

class fritzconnection.core.processor.ServiceStateTable(storage)

Collection of stateVariables.

class fritzconnection.core.processor.SpecVersion

Specification version from the schema device or service informations.

class fritzconnection.core.processor.StateVariable

Represents a stateVariable with the attributes name, dataType, defaultValue, allowedValueList and allowedValueRange.

class fritzconnection.core.processor.Storage(storage)

Baseclass for classes working with InstanceAttributeFactory.

class fritzconnection.core.processor.SystemVersion

Information about the Fritz!OS version of the Fritz!Box. Information is just provided by the ‘tr64desc.xml’ file.

version

Returns system version as string like ‘7.10’ or None if system version is unknown.

class fritzconnection.core.processor.ValueSequencer(sequence_name)

Data descriptor storing a value (assigned as attribute value) in a given sequence.

fritzconnection.core.processor.process_node(obj, root)

Take an object and a root of nodes. The node.text of nodes with the same name as an instance-attribute of ‘obj’ are set as values for the corresponding instance-attribute. If the attribute is a callable, processing the node gets delegated to the callable (which in turn calls process_node).

fritzconnection.core.processor.processor(cls)

Class decorator to add the functionality of calling ‘process_node’ on invoking an instance as a callable.

soaper

Module handling the SOAP based communication with the router.

class fritzconnection.core.soaper.Soaper(address, port, user, password, timeout=None, session=None)

Class making the soap on its own to communicate with the FritzBox. Instead of ham, spam and eggs, it’s hopelessly addicted to soap.

For accessing the Fritz!Box the parameters address for the router ip, port, user, password and session are required. (These parameters will get set by FritzConnection,)

execute(service, action_name, arguments)

Builds the soap request and returns the response as dictionary. Numeric and boolean values are converted from strings to Python datatypes.

get_body(service, action_name, arguments)

Returns the body by template substitution.

parse_response(response, service, action_name)

Extracts all known parameters of the given action from the response and returns this as a dictionary with the out-parameter names as keys and the corresponding response as values. Will raise an ActionError on unknown action_name.

fritzconnection.core.soaper.boolean_convert(value)

Converts a string like ‘1’ or ‘0’ to a boolean value

fritzconnection.core.soaper.datetime_convert(value)

Converts a string in ISO 8601 format to a datetime-object.

fritzconnection.core.soaper.raise_fritzconnection_error(response)

Handles all responses with status codes other than 200. Will raise the relevant FritzConnectionException with the error code and description if available

fritzconnection.core.soaper.uuid_convert(value)

Strips the leading ‘uuid:’ part from the string.