Doc deprecated functions for removal in 3.1

jdufresne · jdufresne · commit 9dff16169ffa · 2017-12-13T06:31:44.000-08:00
- ldap.open()
- ldap.init()
- ldif.CreateLDIF()
- ldif.ParseLDIF()
diff --git a/Doc/reference/ldap.rst b/Doc/reference/ldap.rst
@@ -73,8 +73,21 @@ This module defines the following functions:
    string containing solely the host name. *port* is an integer specifying the
    port where the LDAP server is  listening (default is 389).
 
-   Note: Using this function is deprecated.
+   .. deprecated:: 3.0
 
+      ``ldap.open()`` is deprecated. It will be removed in version 3.1. Use
+      :func:`ldap.initialize()` with a URI like ``'ldap://<hostname>:<port>'``
+      instead.
+
+.. py:function:: init(host [, port=PORT]) -> LDAPObject object
+
+   Alias of :func:`ldap.open()`.
+
+   .. deprecated:: 3.0
+
+      ``ldap.init()`` is deprecated. It will be removed in version 3.1. Use
+      :func:`ldap.initialize()` with a URI like ``'ldap://<hostname>:<port>'``
+      instead.
 
 .. py:function:: get_option(option) -> int|string
 
diff --git a/Doc/reference/ldif.rst b/Doc/reference/ldif.rst
@@ -22,8 +22,20 @@ Functions
 
 .. autofunction:: ldif.CreateLDIF
 
+   .. deprecated:: 3.0
+
+      ``ldif.CreateLDIF()`` is deprecated. It will be removed in version 3.1.
+      Use :meth:`ldif.LDIFWriter.unparse` with a file or ``io.StringIO``
+      instead.
+
 .. autofunction:: ldif.ParseLDIF
 
+   .. deprecated:: 3.0
+
+      ``ldif.ParseLDIF()`` is deprecated. It will be removed in version 3.1.
+      Use the ``all_records`` attribute of the returned value of
+      ``ldif.LDIFRecordList.parse()`` instead.
+
 
 Classes
 ^^^^^^^
diff --git a/Lib/ldap/functions.py b/Lib/ldap/functions.py
@@ -101,7 +101,12 @@ def open(host,port=389,trace_level=0,trace_file=sys.stdout,trace_stack_limit=Non
         Whether to enable "bytes_mode" for backwards compatibility under Py2.
   """
   import warnings
-  warnings.warn('ldap.open() is deprecated! Use ldap.initialize() instead.', DeprecationWarning,2)
+  warnings.warn(
+    'ldap.open() is deprecated. Use ldap.initialize() instead. It will be '
+    'removed in python-ldap 3.1.',
+    category=DeprecationWarning,
+    stacklevel=2,
+  )
   return initialize('ldap://%s:%d' % (host,port),trace_level,trace_file,trace_stack_limit,bytes_mode)
 
 init = open
diff --git a/Lib/ldif.py b/Lib/ldif.py
@@ -23,6 +23,7 @@
 import re
 from base64 import b64encode, b64decode
 from io import StringIO
+import warnings
 
 from ldap.compat import urlparse, urlopen
 
@@ -209,7 +210,7 @@ def unparse(self,dn,record):
 def CreateLDIF(dn,record,base64_attrs=None,cols=76):
   """
   Create LDIF single formatted record including trailing empty line.
-  This is a compatibility function. Use is deprecated!
+  This is a compatibility function.
 
   dn
         string-representation of distinguished name
@@ -222,6 +223,12 @@ def CreateLDIF(dn,record,base64_attrs=None,cols=76):
         Specifies how many columns a line may have before it's
         folded into many lines.
   """
+  warnings.warn(
+    'ldif.CreateLDIF() is deprecated. Use LDIFWriter.unparse() instead. It '
+    'will be removed in python-ldap 3.1',
+    category=DeprecationWarning,
+    stacklevel=2,
+  )
   f = StringIO()
   ldif_writer = LDIFWriter(f,base64_attrs,cols,'\n')
   ldif_writer.unparse(dn,record)
@@ -633,8 +640,14 @@ def handle(self,dn,entry):
 def ParseLDIF(f,ignore_attrs=None,maxentries=0):
   """
   Parse LDIF records read from file.
-  This is a compatibility function. Use is deprecated!
+  This is a compatibility function.
   """
+  warnings.warn(
+    'ldif.ParseLDIF() is deprecated. Use LDIFRecordList.parse() instead. It '
+    'will be removed in python-ldap 3.1',
+    category=DeprecationWarning,
+    stacklevel=2,
+  )
   ldif_parser = LDIFRecordList(
     f,ignored_attr_types=ignore_attrs,max_entries=maxentries,process_url_schemes=0
   )
