upnpclient

The following example scripts demonstrate different ways to interact with UPnP devices:

• discover.py: Discovers UPnP devices on the network and prints device information.
• server.py: Demonstrates how to connect directly to a specific UPnP device without performing a discovery step.
• action_call.py: Demonstrates how to find and invoke a specific action on a UPnP device.
• upnp_dump.py: Discovers all UPnP devices on the network and performs a full dump of their available actions, including parameter details.

A Device object exposes its services via the .services attribute.

Services are typically accessed as attributes on the Device object using the last part of their service_id. For example, a service with ID urn:upnp-org:serviceId:WANIPConn1 is accessed via d.WANIPConn1.

If the service name is not a valid Python attribute, use dictionary-style access: d["service_name"].

# List all services
print(d.services)

# Access actions via attribute (using the last part of the service_id)
print(d.WANIPConn1.actions)

# Access service via dictionary-style if attribute access fails
service = d["WANIPConn1"]

If you are contributing to or extending the upnpclient codebase, follow these technical constraints:

• Python Version: Minimum requirement is Python 3.9. Use datetime.timezone.utc for UTC timestamps (do not use datetime.UTC).
• XML Parsing: The project relies on lxml. The global XML_PARSER in upnp.py is configured with recover=True to handle malformed device descriptions.
• Networking:
  • Use urllib.parse directly; do not use requests.compat.
  • SOAP calls are performed using raw requests.post() calls rather than a requests.Session.
• Package Contents: The gui/, doc/, and examples/ directories are excluded from the published sdist and wheel packages.

Use upnpclient.discover() to find available uPnP devices on your network. This returns a list of Device objects.

Alternatively, if you already have the URL for a device's description XML, you can instantiate a Device object directly.

import upnpclient

# Discover devices on the network
devices = upnpclient.discover()

# Create a device directly from its XML description URL
d = upnpclient.Device("http://192.168.1.1:5000/rootDesc.xml")

Install the upnpclient library using pip. Ensure you are using Python 3.9 or higher.

pip install upnpclient

Before pushing changes, ensure you run the test suite using tox to catch potential cross-version issues. It is recommended to use uv for execution:

uv run --with tox-uv tox

The repository includes a run.sh script to execute the provided examples. Note that these examples depend on physical UPnP devices being present on your network and may not work in all environments.

To run a specific example, pass the script name as an argument to ./run.sh.

$ ./run.sh discover.py

You can inspect the expected input arguments and the output structure of an action using argsdef_in and argsdef_out.

• action.argsdef_in: A list of tuples containing (argument_name, metadata_dict). Metadata includes datatype, name, and allowed_values.
• action.argsdef_out: A list of tuples containing (result_name, metadata_dict) describing the returned data.

# Inspect expected input arguments
print(d.WANIPConn1.AddPortMapping.argsdef_in)

# Inspect expected output structure
print(d.WANIPConn1.GetStatusInfo.argsdef_out)

# Call the action with arguments
d.WANIPConn1.AddPortMapping(
    NewRemoteHost='0.0.0.0',
    NewExternalPort=12345,
    NewProtocol='TCP',
    NewInternalPort=12345,
    NewInternalClient='192.168.1.10',
    NewEnabled='1',
    NewPortMappingDescription='Testing',
    NewLeaseDuration=10000
)

Once you have accessed a service, you can call its actions as methods. Actions return a dictionary containing the results.

# Call an action and get the result dictionary
status = d.WANIPConn1.GetStatusInfo()
print(status)
# Output example: {'NewConnectionStatus': 'Connected', ...}