1 

     2 :mod:`Bastion` --- Restricting access to objects

     3 ================================================

     4 

     5 .. module:: Bastion

     6    :synopsis: Providing restricted access to objects.

     7    :deprecated:

     8    

     9 .. deprecated:: 2.6

    10    The :mod:`Bastion` module has been removed in Python 3.0.

    11    

    12 .. moduleauthor:: Barry Warsaw <bwarsaw@python.org>

    13 

    14 

    15 .. versionchanged:: 2.3

    16    Disabled module.

    17 

    18 .. warning::

    19 

    20    The documentation has been left in place to help in reading old code that uses

    21    the module.

    22 

    23 According to the dictionary, a bastion is "a fortified area or position", or

    24 "something that is considered a stronghold."  It's a suitable name for this

    25 module, which provides a way to forbid access to certain attributes of an

    26 object.  It must always be used with the :mod:`rexec` module, in order to allow

    27 restricted-mode programs access to certain safe attributes of an object, while

    28 denying access to other, unsafe attributes.

    29 

    30 .. I'm concerned that the word 'bastion' won't be understood by people

    31 .. for whom English is a second language, making the module name

    32 .. somewhat mysterious.  Thus, the brief definition... --amk

    33 

    34 .. I've punted on the issue of documenting keyword arguments for now.

    35 

    36 

    37 .. function:: Bastion(object[, filter[, name[, class]]])

    38 

    39    Protect the object *object*, returning a bastion for the object.  Any attempt to

    40    access one of the object's attributes will have to be approved by the *filter*

    41    function; if the access is denied an :exc:`AttributeError` exception will be

    42    raised.

    43 

    44    If present, *filter* must be a function that accepts a string containing an

    45    attribute name, and returns true if access to that attribute will be permitted;

    46    if *filter* returns false, the access is denied.  The default filter denies

    47    access to any function beginning with an underscore (``'_'``).  The bastion's

    48    string representation will be ``<Bastion for name>`` if a value for *name* is

    49    provided; otherwise, ``repr(object)`` will be used.

    50 

    51    *class*, if present, should be a subclass of :class:`BastionClass`;  see the

    52    code in :file:`bastion.py` for the details.  Overriding the default

    53    :class:`BastionClass` will rarely be required.

    54 

    55 

    56 .. class:: BastionClass(getfunc, name)

    57 

    58    Class which actually implements bastion objects.  This is the default class used

    59    by :func:`Bastion`.  The *getfunc* parameter is a function which returns the

    60    value of an attribute which should be exposed to the restricted execution

    61    environment when called with the name of the attribute as the only parameter.

    62    *name* is used to construct the :func:`repr` of the :class:`BastionClass`

    63    instance.

    64