ldapurl.rst 2.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126
  1. .. % $Id: ldapurl.rst,v 1.9 2011/07/22 13:27:01 stroeder Exp $
  2. ###################################
  3. :py:mod:`ldapurl` LDAP URL handling
  4. ###################################
  5. .. py:module:: ldapurl
  6. :synopsis: Parses and generates LDAP URLs
  7. .. moduleauthor:: python-ldap project (see http://www.python-ldap.org/)
  8. This module parses and generates LDAP URLs. It is implemented in pure Python
  9. and does not rely on any non-standard modules. Therefore it can be used stand-
  10. alone without the rest of the python-ldap package. Compability note: This
  11. module has been solely tested on Python 2.x and above.
  12. .. seealso::
  13. :rfc:`4516` - The LDAP URL Format
  14. Constants
  15. =========
  16. The :mod:`ldapurl` module exports the following constants:
  17. .. py:data:: SEARCH_SCOPE
  18. This dictionary maps a search scope string identifier to the corresponding
  19. integer value used with search operations in :mod:`ldap`.
  20. .. py:data:: SEARCH_SCOPE_STR
  21. This dictionary is the inverse to :const:`SEARCH_SCOPE`. It maps a search scope
  22. integer value to the corresponding string identifier used in a LDAP URL string
  23. representation.
  24. .. py:data:: LDAP_SCOPE_BASE
  25. .. py:data:: LDAP_SCOPE_ONELEVEL
  26. .. py:data:: LDAP_SCOPE_SUBTREE
  27. Functions
  28. =========
  29. .. autofunction:: ldapurl.isLDAPUrl
  30. .. autofunction:: ldapurl.ldapUrlEscape
  31. Classes
  32. =======
  33. .. _ldapurl-ldapurl:
  34. LDAP URLs
  35. ^^^^^^^^^
  36. A :py:class:`LDAPUrl` object represents a complete LDAP URL.
  37. .. autoclass:: ldapurl.LDAPUrl
  38. LDAP URL extensions
  39. ^^^^^^^^^^^^^^^^^^^
  40. A :py:class:`LDAPUrlExtension` object represents a single LDAP URL extension
  41. whereas :py:class:`LDAPUrlExtensions` represents a list of LDAP URL extensions.
  42. .. _ldapurl-ldapurlextension:
  43. .. autoclass:: ldapurl.LDAPUrlExtension
  44. .. _ldapurl-ldapurlextensions:
  45. .. autoclass:: ldapurl.LDAPUrlExtensions
  46. .. _ldapurl-example:
  47. Example
  48. ^^^^^^^
  49. Important security advice:
  50. For security reasons you shouldn't specify passwords in LDAP URLs
  51. unless you really know what you are doing.
  52. The following example demonstrates how to parse a LDAP URL
  53. with :mod:`ldapurl` module.
  54. >>> import ldapurl
  55. >>> ldap_url = ldapurl.LDAPUrl('ldap://localhost:1389/dc=stroeder,dc=com?cn,mail???bindname=cn=Michael%2cdc=stroeder%2cdc=com,X-BINDPW=secret')
  56. >>> # Using the parsed LDAP URL by reading the class attributes
  57. >>> ldap_url.dn
  58. 'dc=stroeder,dc=com'
  59. >>> ldap_url.hostport
  60. 'localhost:1389'
  61. >>> ldap_url.attrs
  62. ['cn','mail']
  63. >>> ldap_url.filterstr
  64. '(objectclass=*)'
  65. >>> ldap_url.who
  66. 'cn=Michael,dc=stroeder,dc=com'
  67. >>> ldap_url.cred
  68. 'secret'
  69. >>> ldap_url.scope
  70. 0
  71. The following example demonstrates how to generate a LDAP URL
  72. with \module{ldapurl} module.
  73. >>> import ldapurl
  74. >>> ldap_url = ldapurl.LDAPUrl(hostport='localhost:1389',dn='dc=stroeder,dc=com',attrs=['cn','mail'],who='cn=Michael,dc=stroeder,dc=com',cred='secret')
  75. >>> ldap_url.unparse()
  76. 'ldap://localhost:1389/dc=stroeder,dc=com?cn,mail?base?(objectclass=*)?bindname=cn=Michael%2Cdc=stroeder%2Cdc=com,X-BINDPW=secret'