Programming interface

Building URLs

klempner.url.build_url(service, *path, **query)

Build a URL that targets service.

  • service (str) – service to target

  • path – request path elements

  • query – request query parameters


a fully-formed, absolute URL

Return type



class klempner.config.DiscoveryMethod

Available discovery methods.

CONSUL = 'consul'

Build consul-based service URLs.

CONSUL_AGENT = 'consul+agent'

Build consul-based service URLs using a consul agent.

ENV_VARS = 'environment'

Build URLs based on _HOST, _PORT, and _SCHEME environment variables.

K8S = 'kubernetes'

Build Kubernetes cluster-based service URLs.

SIMPLE = 'simple'

Build URLs using service name as host name.

klempner.config.URL_SCHEME_MAP = {21: 'ftp', 22: 'ssh', 23: 'telnet', 25: 'smtp', 69: 'tftp', 70: 'gopher', 80: 'http', 110: 'pop', 119: 'nntp', 161: 'snmp', 322: 'rtsps', 389: 'ldap', 443: 'https', 554: 'rtsp', 602: 'xmlrpc.beep', 631: 'ipp', 636: 'ldaps', 873: 'rsync', 1344: 'icap', 3306: 'mysql', 3372: 'tip', 5432: 'postgresql', 5672: 'amqp', 5900: 'vnc', 6379: 'redis', 27017: 'mongodb'}

Mapping of port number to URL scheme.

This dictionary is used to identify the URL scheme based on the port number when a port number is available. Users of the library MAY modify the content of this dictionary at any time.

klempner.config.configure(discovery_method, **parameters)

Configure the discovery method directly.

  • discovery_method – method to use

  • parameters – parameters required for the selected method


klempner.errors.ConfigurationError if a required parameter is not provided


Set the discovery method from $KLEMPNER_DISCOVERY.

This method configures the library based on the KLEMPNER_DISCOVERY environment variable. If the environment variable is not set, then the “simple” configuration is used.


Configure from the environment if currently unconfigured.


Retrieve the configured method and parameters.

Return type

tuple(str, dict)


Reset URL construction parameters.


exception klempner.errors.ConfigurationError(config_option, config_value, *args)

Configuration is invalid.

exception klempner.errors.KlempnerError

Library root exception class.

exception klempner.errors.ServiceNotFoundError(service_name, *args, **kwargs)

Requested service was not found.