[_521] clearer documentation and errors regarding pam/pam_password

Also incorporated is the pass-through module pam.py which incorporates
a version check and reminds users in a friendly way (ie. by throwing a
fatal exception with a non-confusing message :) ) to update their
PAM scheme strings for 4.3+ ...

README.md

@@ -161,6 +161,15 @@ the `encryption_*` and `ssl_*` options
 directly to the constructor as keyword arguments, even though it is
 required when they are placed in the environment file.
 
+PAM logins
+----------
+
+Starting with v2.0.0, the python iRODS client is able to authenticate under PAM using the same file-based client environment as the
+iCommands.
+
+Caveat for iRODS 4.3+: when upgrading from 4.2, the "irods_authentication_scheme" setting must be changed from "pam" to "pam_password" in
+`~/.irods/irods_environment.json` for all file-based client environments.
+
 Maintaining a connection
 ------------------------
 

irods/auth/pam.py

@@ -0,0 +1,9 @@
+class PamLoginException(Exception): pass
+
+def login(conn):
+    if conn.server_version >= (4,3):
+        raise PamLoginException('PAM logins in iRODS 4.3+ require a scheme of "pam_password"')
+    conn._login_pam()
+
+# Pattern for when you need to import from sibling plugins:
+from .native import login as native_login