add more doc pointers for compat mode, and enable PendingDeprecationWarning

2 files changed, 19 insertions, 17 deletions

diff --git a/README.md b/README.md
index 6f1c8dc..cc66367 100644
--- a/README.md
+++ b/README.md
@@ -15,7 +15,7 @@ functionality is exposed to the command line by the Unix command
 >>> magic.from_file("testdata/test.pdf")
 'PDF document, version 1.2'
 # recommend using at least the first 2048 bytes, as less can produce incorrect identification
->>> magic.from_buffer(open("testdata/test.pdf", "rb").read(2048)) 
+>>> magic.from_buffer(open("testdata/test.pdf", "rb").read(2048))
 'PDF document, version 1.2'
 >>> magic.from_file("testdata/test.pdf", mime=True)
 'application/pdf'
@@ -83,10 +83,10 @@ pip install python-magic-bin
 
 - 'WindowsError: [Error 193] %1 is not a valid Win32 application':
   Attempting to run the 32-bit libmagic DLL in a 64-bit build of
-  python will fail with this error.  Here are 64-bit builds of libmagic for windows: https://github.com/pidydx/libmagicwin64. 
+  python will fail with this error.  Here are 64-bit builds of libmagic for windows: https://github.com/pidydx/libmagicwin64.
   Newer version can be found here: https://github.com/nscaife/file-windows.
 
-- 'WindowsError: exception: access violation writing 0x00000000 ' This may indicate you are mixing 
+- 'WindowsError: exception: access violation writing 0x00000000 ' This may indicate you are mixing
   Windows Python and Cygwin Python. Make sure your libmagic and python builds are consistent.
 
 
@@ -101,7 +101,7 @@ triage it.
 
 ## Running the tests
 
-To run the tests across 3 recent Ubuntu LTS releases (depends on Docker):
+To run the tests across a variety of linux distributions (depends on Docker):
 
 ```
 ./test_docker.sh
@@ -119,6 +119,10 @@ To run against a specific python version:
 LC_ALL=en_US.UTF-8 python3 test/test.py
 ```
 
+## libmagic and python-magic
+
+See [COMPAT.md](COMPAT.md) for a guide to libmagic / python-magic compatability.
+
 ## Versioning
 
 Minor version bumps should be backwards compatible.  Major bumps are not.
diff --git a/magic/__init__.py b/magic/__init__.py
index 554f3f5..f2fd34d 100644
--- a/magic/__init__.py
+++ b/magic/__init__.py
@@ -450,25 +450,23 @@ def _add_compat(to_module):
     import warnings, re
     from magic import compat
 
-    def deprecation_wrapper(compat, fn, alternate):
+    def deprecation_wrapper(fn):
         def _(*args, **kwargs):
             warnings.warn(
-                "Using compatability mode with libmagic's python binding",
-                DeprecationWarning)
+                "Using compatability mode with libmagic's python binding. "
+                "See https://github.com/ahupp/python-magic/blob/master/COMPAT.md for details.",
+                PendingDeprecationWarning)
 
-            return compat[fn](*args, **kwargs)
+            return fn(*args, **kwargs)
 
         return _
 
-    fn = [('detect_from_filename', 'magic.from_file'),
-          ('detect_from_content', 'magic.from_buffer'),
-          ('detect_from_fobj', 'magic.Magic.from_open_file'),
-          ('open', 'magic.Magic')]
-    for (fname, alternate) in fn:
-        # for now, disable the deprecation warning until theres clarity on
-        # what the merged module should look like
-        to_module[fname] = compat.__dict__.get(fname)
-        # to_module[fname] = deprecation_wrapper(compat.__dict__, fname, alternate)
+    fn = ['detect_from_filename',
+          'detect_from_content',
+          'detect_from_fobj',
+          'open']
+    for fname in fn:
+        to_module[fname] = deprecation_wrapper(compat.__dict__[fname])
 
     # copy constants over, ensuring there's no conflicts
     is_const_re = re.compile("^[A-Z_]+$")