# Module: `utils.openpy`

Tools to open .py files as Unicode, using the encoding specified within the file, as per PEP 263.

Much of the code is taken from the tokenize module in Python 3.2.

## 8 Functions

`IPython.utils.openpy.``detect_encoding`(readline)

  The detect_encoding() function is used to detect the encoding that should be used to decode a Python source file. It requires one argument, readline, in the same way as the tokenize() generator.

  It will call readline a maximum of twice, and return the encoding used (as a string) and a list of any lines (left as bytes) it has read in.

  It detects the encoding from the presence of a utf-8 bom or an encoding cookie as specified in pep-0263. If both a bom and a cookie are present, but disagree, a SyntaxError will be raised. If the encoding cookie is an invalid charset, raise a SyntaxError. Note that if a utf-8 bom is found, ‘utf-8-sig’ is returned.

  If no encoding is specified, then the default of ‘utf-8’ will be returned.

`IPython.utils.openpy.``open`(filename)

  Open a file in read only mode using the encoding detected by detect_encoding().

`IPython.utils.openpy.``source_to_unicode`(txt, errors='replace', skip_encoding_cookie=True)

  Converts a bytes string with python source code to unicode.

  Unicode strings are passed through unchanged. Byte strings are checked for the python source file encoding cookie to determine encoding. txt can be either a bytes buffer or a string containing the source code.

`IPython.utils.openpy.``strip_encoding_cookie`(filelike)

  Generator to pull lines from a text-mode file, skipping the encoding cookie if it is found in the first two lines.

`IPython.utils.openpy.``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: |
  Return type: | A unicode string containing the contents of the file.

`IPython.utils.openpy.``read_py_url`(url, errors='replace', skip_encoding_cookie=True)

  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: |
  Return type: | A unicode string containing the contents of the file.

`IPython.utils.openpy.``source_from_cache`(path)

  Given the path to a .pyc. file, return the path to its .py file.

  The .pyc file does not need to exist; this simply returns the path to the .py file calculated to correspond to the .pyc file. If path does not conform to PEP 3147/488 format, ValueError will be raised. If sys.implementation.cache_tag is None then NotImplementedError is raised.

`IPython.utils.openpy.``cache_from_source`(path, debug_override=None, *, optimization=None)

  Given the path to a .py file, return the path to its .pyc file.

  The .py file does not need to exist; this simply returns the path to the .pyc file calculated as if the .py file were imported.

  The ‘optimization’ parameter controls the presumed optimization level of the bytecode file. If ‘optimization’ is not None, the string representation of the argument is taken and verified to be alphanumeric (else ValueError is raised).

  The debug_override parameter is deprecated. If debug_override is not None, a True value is the same as setting ‘optimization’ to the empty string while a False value is equivalent to setting ‘optimization’ to ‘1’.

  If sys.implementation.cache_tag is None then NotImplementedError is raised.