python: update documentation

This touches up a handful of places in the python documentation to try to make
the current best-practices more obvious. In particular, I often find the
function signatures (what to pass, what not to pass) confusing and have added
them to the docs.

Also updated the metas to be more consistent with the most frequently used
modern style.

pkgs/development/python-modules/toolz/default.nix

@@ -21,10 +21,10 @@ buildPythonPackage rec{
     nosetests toolz/tests
   '';
 
-  meta = {
-    homepage = https://github.com/pytoolz/toolz/;
+  meta = with lib; {
+    homepage = https://github.com/pytoolz/toolz;
     description = "List processing tools and functional utilities";
-    license = lib.licenses.bsd3;
-    maintainers = with lib.maintainers; [ fridh ];
+    license = licenses.bsd3;
+    maintainers = with maintainers; [ fridh ];
   };
 }