review chgs to README & authfmwork

Author: d-w-moore

README.md

@@ -137,23 +137,23 @@ The following free functions may be used to create the authentication secrets fi
    - `irods.client_init.write_native_irodsA_file`
    - `irods.client_init.write_pam_irodsA_file`
 
-These functions can roughly be described as duplicating the function of `iinit`,
+These functions can roughly be described as duplicating the "authentication" functionality of `iinit`,
 provided that a valid `irods_environment.json` has already been created.
 
 Each of the above functions can take a cleartext password and write an appropriately encoded
-version of it into an authentication in the appropriate location.  That location is
+version of it into an authentication file in the appropriate location.  That location is
 `~/.irods/.irodsA` unless the environment variable IRODS_AUTHENTICATION_FILE has been set
 in the command shell to dictate an alternative file path.
 
 As an example, here we write a native `.irodsA` file using the first of the two functions.  We
-provide the one required argument, a password string entered - in this case - interactively at the
+provide the one required argument, a password string which entered interactively at the
 terminal.
 
 ```bash
-bash$ echo '{ "irods_user_name":"rods",
-              ... # other parameters as needed
-            }'> ~/.irods/irods_environment.json
-bash$ python -c "import irods.client_init, getpass
+$ echo '{ "irods_user_name":"rods",
+          ... # other parameters as needed
+        }'> ~/.irods/irods_environment.json
+$ python -c "import irods.client_init, getpass
 irods.client_init.write_native_irodsA_file(getpass.getpass('Enter iRODS password -> '))"
 ```
 
@@ -164,22 +164,22 @@ is raised to warn of any older `.irodsA` file that might otherwise have been ove
 Equivalently to the above, we can issue the following command.
 
 ```bash
-bash$ prc_write_irodsA.py native <<<"${MY_CURRENT_IRODS_PASSWORD}"
+$ prc_write_irodsA.py native <<<"${MY_CURRENT_IRODS_PASSWORD}"
 ```
 
 The redirect may of course be left off, in which case the user is prompted for the iRODS password
-and echo of the keyboard input will be suppressed, in the style of `iinit`.  Regardless
+and echo of the keyboard input will be suppressed, in the style of `iinit`.  Regardless of
 which technique is used, no password will be visible on the terminal during or after input.
 
 For the `pam_password` scheme, typically SSL/TLS must first be enabled to avoid sending data related
 to the password - or even sending the raw password itself - over a network connection in the clear.
 
-Thus for `pam_password` authentication to work well, we should first ensure, when setting up the
+Thus, for `pam_password` authentication to work well, we should first ensure, when setting up the
 client environment, to include within `irods_environment.json` the appropriate SSL/TLS connection
 parameters.  In a pinch, `iinit` can be used to verify this prerequisite is fulfilled,
-as its invocation would then create a valid .irodsA from merely prompting the user for their PAM password.
+as its invocation would then create a valid `.irodsA` from merely prompting the user for their PAM password.
 
-Once again, this can also be done either using the free function directly:
+Once again, this can also be done using the free function directly:
 
 ```python
 irods.client_init.write_pam_irodsA_file(getpass.getpass('Enter current PAM password -> '))
@@ -188,10 +188,10 @@ irods.client_init.write_pam_irodsA_file(getpass.getpass('Enter current PAM passw
 or from the Bash command shell:
 
 ```bash
-bash$ prc_write_irodsA.py pam_password <<<"${MY_CURRENT_PAM_PASSWORD}"
+$ prc_write_irodsA.py pam_password <<<"${MY_CURRENT_PAM_PASSWORD}"
 ```
 
-As a final note, in the "pam_password" scheme the default SSL requirement can be disabled.
+As a final note, in the `pam_password` scheme, the default SSL requirement can be disabled.
 **Warning:** Disabling the SSL requirement may cause user passwords to be sent over the network
 in the clear. This should only be done for purposes of testing. Here's how to do it:
 

irods/auth/__init__.py

@@ -20,7 +20,7 @@
 class AuthStorage:
     """A class that facilitates flexible means password storage.
 
-    Using an instance of this class, passwords may either be
+    Using an instance of this class, passwords may either be one of the following:
 
         - directly placed in a member attribute (pw), or
 
@@ -32,7 +32,6 @@ class AuthStorage:
     password is stored in RAM or in the filesystem depends on whether it was read
     originally as a function parameter or from an authentication file, respectively,
     when the session was created.
-
     """
 
     @staticmethod

irods/auth/native.py

@@ -16,7 +16,7 @@
 
 
 def login(conn, **extra_opt):
-    """When the Python iRODS client loads this(or any plugin) for authenticating a connection object,
+    """When the Python iRODS client loads this (or any) plugin for authenticating a connection object,
     login is the hook function that gets called.
     """
     opt = {"user_name": conn.account.proxy_user, "zone_name": conn.account.proxy_zone}

irods/test/scripts/README.md

@@ -6,7 +6,7 @@ now implemented in a development branch but slated for release in a later versio
 of python-irodsclient.  (See issue #502.)
 
 Each BATS script is designed such that a "main" function is executed to assert
-the relevant test outcomes.  In effect this is realized because BATS fails the
+the relevant test outcomes.  In effect, this is realized because BATS fails the
 test if any individual command in the function fails.
 
 The BATS tests are designed to be run by the recipe below: