ldap-dn.rst 3.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111
  1. .. % $Id: ldap-dn.rst,v 1.4 2010/05/16 11:22:08 stroeder Exp $
  2. :mod:`ldap.dn` LDAP Distinguished Name handling
  3. ====================================================
  4. .. module:: ldap.dn
  5. :synopsis: LDAP Distinguished Name handling.
  6. .. moduleauthor:: python-ldap project (see http://www.python-ldap.org/)
  7. .. % Author of the module code;
  8. .. seealso::
  9. For LDAPv3 DN syntax see:
  10. :rfc:`4514` - Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names
  11. For LDAPv2 DN syntax (obsoleted by LDAPv3) see:
  12. :rfc:`1779` - A String Representation of Distinguished Names
  13. The :mod:`ldap.dn` module defines the following functions:
  14. .. function:: escape_dn_chars(s)
  15. This function escapes characters in string *s* which are special in LDAP
  16. distinguished names. You should use this function when building LDAP DN strings
  17. from arbitrary input.
  18. .. % -> string
  19. .. function:: str2dn(s [, flags=0])
  20. This function takes *s* and breaks it up into its component parts down to AVA
  21. level. The optional parameter *flags* describes the DN format of s (see
  22. :ref:`ldap-dn-flags`). Note that hex-encoded non-ASCII chars are decoded
  23. to the raw bytes.
  24. .. % -> list
  25. .. function:: dn2str(dn)
  26. This function takes a decomposed DN in *dn* and returns a single string. It's
  27. the inverse to :func:`str2dn`. Special characters are escaped with the help of
  28. function :func:`escape_dn_chars`.
  29. .. % -> string
  30. .. function:: explode_dn(dn [, notypes=0[, flags=0]])
  31. This function takes *dn* and breaks it up into its component parts. Each part
  32. is known as an RDN (Relative Distinguished Name). The optional *notypes*
  33. parameter is used to specify that only the RDN values be returned and not
  34. their types. The optional parameter *flags* describes the DN format of s (see
  35. :ref:`ldap-dn-flags`). This function is emulated by function
  36. :func:`str2dn` since the function ldap_explode_dn() in the C library is
  37. deprecated.
  38. .. % -> list
  39. .. function:: explode_rdn(rdn [, notypes=0[, flags=0]])
  40. This function takes a (multi-valued) *rdn* and breaks it up into a list of
  41. characteristic attributes. The optional *notypes* parameter is used to specify
  42. that only the RDN values be returned and not their types. The optional *flags*
  43. parameter describes the DN format of s (see :ref:`ldap-dn-flags`). This
  44. function is emulated by function :func:`str2dn` since the function
  45. ldap_explode_rdn() in the C library is deprecated.
  46. .. % -> list
  47. .. _ldap-dn-example:
  48. Examples
  49. ^^^^^^^^^
  50. Splitting a LDAPv3 DN to AVA level. Note that both examples have the same result
  51. but in the first example the non-ASCII chars are passed as is (byte buffer string)
  52. whereas in the second example the hex-encoded DN representation are passed to the function.
  53. >>> ldap.dn.str2dn('cn=Michael Str\xc3\xb6der,dc=stroeder,dc=com',flags=ldap.DN_FORMAT_LDAPV3)
  54. [[('cn', 'Michael Str\xc3\xb6der', 4)], [('dc', 'stroeder', 1)], [('dc', 'com', 1)]]
  55. >>> ldap.dn.str2dn('cn=Michael Str\C3\B6der,dc=stroeder,dc=com',flags=ldap.DN_FORMAT_LDAPV3)
  56. [[('cn', 'Michael Str\xc3\xb6der', 4)], [('dc', 'stroeder', 1)], [('dc', 'com', 1)]]
  57. Splitting a LDAPv2 DN into RDN parts:
  58. >>> ldap.dn.explode_dn('cn=Michael Stroeder;dc=stroeder;dc=com',flags=ldap.DN_FORMAT_LDAPV2)
  59. ['cn=Michael Stroeder', 'dc=stroeder', 'dc=com']
  60. Splitting a multi-valued RDN:
  61. >>> ldap.dn.explode_rdn('cn=Michael Stroeder+mail=michael@stroeder.com',flags=ldap.DN_FORMAT_LDAPV2)
  62. ['cn=Michael Stroeder', 'mail=michael@stroeder.com']
  63. Splitting a LDAPv3 DN with a multi-valued RDN into its AVA parts:
  64. >>> ldap.dn.str2dn('cn=Michael Stroeder+mail=michael@stroeder.com,dc=stroeder,dc=com')
  65. [[('cn', 'Michael Stroeder', 1), ('mail', 'michael@stroeder.com', 1)], [('dc', 'stroeder', 1)], [('dc', 'com', 1)]]