From 6811272729d72d08859b86902f7b51ec8769a9a7 2012-04-14 18:15:42
From: Thomas Kluyver <takowl@gmail.com>
Date: 2012-04-14 18:15:42
Subject: [PATCH] Add docstrings for read_py_file and read_py_url.

---

diff --git a/IPython/utils/openpy.py b/IPython/utils/openpy.py
index 000eff0..1c1f8af 100644
--- a/IPython/utils/openpy.py
+++ b/IPython/utils/openpy.py
@@ -139,7 +139,22 @@ def strip_encoding_cookie(filelike):
     for line in it:
         yield line
 
-def read_py_file(filename, errors='replace', skip_encoding_cookie=True):
+def read_py_file(filename, skip_encoding_cookie=True):
+    """Read a Python file, using the encoding declared inside the file.
+    
+    Parameters
+    ----------
+    filename : str
+      The path to the file to read.
+    skip_encoding_cookie : bool
+      If True (the default), and the encoding declaration is found in the first
+      two lines, that line will be excluded from the output - compiling a
+      unicode string with an encoding declaration is a SyntaxError in Python 2.
+    
+    Returns
+    -------
+    A unicode string containing the contents of the file.
+    """
     with open(filename) as f:   # the open function defined in this module.
         if skip_encoding_cookie:
             return "".join(strip_encoding_cookie(f))
@@ -147,8 +162,23 @@ def read_py_file(filename, errors='replace', skip_encoding_cookie=True):
             return f.read()
 
 def read_py_url(url, errors='replace', skip_encoding_cookie=True):
-    """Open a URL to a raw Python file, using the encoding detected by
-    detect_encoding().
+    """Read a Python file from a URL, using the encoding declared inside the file.
+    
+    Parameters
+    ----------
+    url : str
+      The URL from which to fetch the file.
+    errors : str
+      How to handle decoding errors in the file. Options are the same as for
+      bytes.decode(), but here 'replace' is the default.
+    skip_encoding_cookie : bool
+      If True (the default), and the encoding declaration is found in the first
+      two lines, that line will be excluded from the output - compiling a
+      unicode string with an encoding declaration is a SyntaxError in Python 2.
+    
+    Returns
+    -------
+    A unicode string containing the contents of the file.
     """
     response = urllib.urlopen(url)
     buffer = io.BytesIO(response.read())