FePy options
============

FePy has some optional parts you can choose to use or not. These options
are provided by ``fepy`` package.

For example, you may want to use ``cipher`` option, which re-implements
parts of `Python Cryptoraphy Toolkit`_ written in C using subclasses of
`SymmetricAlgorithm`_ in .NET Framework. On the other hand, it will only
lengthen the already long startup time if you don't need it.

.. _Python Cryptoraphy Toolkit: http://www.amk.ca/python/code/crypto
.. _SymmetricAlgorithm: http://msdn2.microsoft.com/en-us/library/system.security.cryptography.symmetricalgorithm.aspx

There are two ways to use FePy options. One enables them at the startup
time using ``site.py``. The other enables them in the middle of execution,
as in the interactive console.

.. contents::

Startup time usage
------------------

IPCE already includes following two lines in ``site.py``, and that's all you
need::

  import fepy
  fepy.install()

This reads the environment variable ``FEPY_OPTIONS``. It is a comma separated
list of option names. And then named options are enabled.

If the environment variable is not set, nothing happens and ``fepy.install()``
returns immediately.

Interactive usage
-----------------

Let's have a look at the example::

  $ ipy
  IronPython 1.1a1 (1.1) on .NET 2.0.50727.42
  Copyright (c) Microsoft Corporation. All rights reserved.
  >>> import socket
  >>> socket._fileobject
  Traceback (most recent call last):
  AttributeError: 'module' object has no attribute '_fileobject'

IronPython 1.1a1 does not have an undocumented ``_fileobject`` class in
`socket`_ module. Sadly, `urllib2`_ module is using it anyway. FePy provides
``fileobject`` option for this, but how does one enable it in the middle
of execution?

.. _socket: http://docs.python.org/lib/module-socket.html
.. _urllib2: http://docs.python.org/lib/module-urllib2.html

Of course, you can quit, set the environment variable, and start again,
but you may not want to trash the interactive session if possible. So here's
how::

  >>> import fepy
  >>> fepy.install_option('fileobject')
  >>> socket._fileobject
  <class '_fileobject._fileobject'>

Here's how to do this at the startup time::

  $ export FEPY_OPTIONS=fileobject
  $ ipy
  IronPython 1.1a1 (1.1) on .NET 2.0.50727.42
  Copyright (c) Microsoft Corporation. All rights reserved.
  >>> import socket
  >>> socket._fileobject
  <class '_fileobject._fileobject'>

Available options
-----------------

ast
  Support for `compiler.parse`_ using the internal parser of IronPython.

.. _compiler.parse: http://docs.python.org/lib/module-compiler.html

cipher
  Support for `Python Cryptoraphy Toolkit`_.

codecs_errors
  Support for built-in codec error handling callbacks, ``ignore``,
  ``xmlcharrefreplace``, and ``backslashreplace``. The stock IronPython
  provides ``strict`` and ``replace``.

encoding
  Support for `standard encodings`_ like ``base64`` and ``hex``.

.. _standard encodings: http://docs.python.org/lib/standard-encodings.html

fileobject
  Support for ``socket._fileobject`` class.

network
  Use FePy's version of ``socket``, ``select``, and ``ssl`` module.

pth_support
  Support for ``.pth`` files and ``site-packages`` directory.

regex
  Support for using pure Python regex engine `\_sre.py`_. You may want to
  try this if you are hit by bugs in IronPython's ``re`` module.

.. _\_sre.py: http://ubique.ch/code/_sre/