# `ldapurl` LDAP URL handling

This module parses and generates LDAP URLs. It is implemented in pure Python and does not rely on any non-standard modules. Therefore it can be used stand- alone without the rest of the python-ldap package.

See also

RFC 4516 - The LDAP URL Format

## Constants

The `ldapurl` module exports the following constants:

ldapurl.SEARCH_SCOPE

  This dictionary maps a search scope string identifier to the corresponding integer value used with search operations in `ldap`.

ldapurl.SEARCH_SCOPE_STR

  This dictionary is the inverse to `SEARCH_SCOPE`. It maps a search scope integer value to the corresponding string identifier used in a LDAP URL string representation.

ldapurl.LDAP_SCOPE_BASE

ldapurl.LDAP_SCOPE_ONELEVEL

ldapurl.LDAP_SCOPE_SUBTREE

## Functions

ldapurl.isLDAPUrl(s)

  Returns True if s is a LDAP URL, else False

ldapurl.ldapUrlEscape(s)

  Returns URL encoding of string s

## Classes

### LDAP URLs

A `LDAPUrl` object represents a complete LDAP URL.

class ldapurl.LDAPUrl(ldapUrl=None, urlscheme='ldap', hostport='', dn='', attrs=None, scope=None, filterstr=None, extensions=None, who=None, cred=None)

  Class for parsing and unparsing LDAP URLs as described in RFC 4516.

  Usable class attributes:
    urlscheme

      URL scheme (either ldap, ldaps or ldapi)

    hostport

      LDAP host (default ‘’)

    dn

      String holding distinguished name (default ‘’)

    attrs

      list of attribute types (default None)

    scope

      integer search scope for ldap-module

    filterstr

      String representation of LDAP Search Filters (see RFC 4515)

    extensions

      Dictionary used as extensions store

    who

      Maps automagically to bindname LDAP URL extension

    cred

      Maps automagically to X-BINDPW LDAP URL extension

  Changed in version 3.4.0: The urlscheme is now case insensitive and always converted to lower case. `LDAP://localhost` is equivalent to `ldap://localhost`.

  applyDefaults(defaults)

    Apply defaults to all class attributes which are None.

    defaults

      Dictionary containing a mapping from class attributes to default values

  htmlHREF(urlPrefix='', hrefText=None, hrefTarget=None)

    Returns a string with HTML link for this LDAP URL.

    urlPrefix

      Prefix before LDAP URL (e.g. for addressing another web-based client)

    hrefText

      link text/description

    hrefTarget

      string added as link target attribute

  initializeUrl()

    Returns LDAP URL suitable to be passed to ldap.initialize()

  unparse()

    Returns LDAP URL depending on class attributes set.

### LDAP URL extensions

A `LDAPUrlExtension` object represents a single LDAP URL extension whereas `LDAPUrlExtensions` represents a list of LDAP URL extensions.

class ldapurl.LDAPUrlExtension(extensionStr=None, critical=0, extype=None, exvalue=None)

  Class for parsing and unparsing LDAP URL extensions as described in RFC 4516.

  Usable class attributes:
    critical

      Boolean integer marking the extension as critical

    extype

      Type of extension

    exvalue

      Value of extension

class ldapurl.LDAPUrlExtensions(default=None)

  Models a collection of LDAP URL extensions as a mapping type

### Example

Important security advice: For security reasons you should not specify passwords in LDAP URLs unless you really know what you are doing.

The following example demonstrates how to parse a LDAP URL with `ldapurl` module.

    >>> import ldapurl
    >>> ldap_url = ldapurl.LDAPUrl('ldap://localhost:1389/dc=stroeder,dc=com?cn,mail???bindname=cn=Michael%2cdc=stroeder%2cdc=com,X-BINDPW=secret')
    >>> # Using the parsed LDAP URL by reading the class attributes
    >>> ldap_url.dn
    'dc=stroeder,dc=com'
    >>> ldap_url.hostport
    'localhost:1389'
    >>> ldap_url.attrs
    ['cn','mail']
    >>> ldap_url.filterstr
    '(objectclass=*)'
    >>> ldap_url.who
    'cn=Michael,dc=stroeder,dc=com'
    >>> ldap_url.cred
    'secret'
    >>> ldap_url.scope
    0

The following example demonstrates how to generate a LDAP URL with module{ldapurl} module.

    >>> import ldapurl
    >>> ldap_url = ldapurl.LDAPUrl(hostport='localhost:1389',dn='dc=stroeder,dc=com',attrs=['cn','mail'],who='cn=Michael,dc=stroeder,dc=com',cred='secret')
    >>> ldap_url.unparse()
    'ldap://localhost:1389/dc=stroeder,dc=com?cn,mail?base?(objectclass=*)?bindname=cn=Michael%2Cdc=stroeder%2Cdc=com,X-BINDPW=secret'