cpython/Doc/library/bastion.rst

65 lines
2.6 KiB
ReStructuredText
Raw Normal View History

2007-08-15 11:28:01 -03:00
:mod:`Bastion` --- Restricting access to objects
================================================
.. module:: Bastion
:synopsis: Providing restricted access to objects.
2008-05-09 23:27:04 -03:00
:deprecated:
2009-01-03 16:55:06 -04:00
2008-05-09 23:27:04 -03:00
.. deprecated:: 2.6
The :mod:`Bastion` module has been removed in Python 3.0.
2009-01-03 16:55:06 -04:00
2007-08-15 11:28:01 -03:00
.. moduleauthor:: Barry Warsaw <bwarsaw@python.org>
.. versionchanged:: 2.3
Disabled module.
.. note::
2007-08-15 11:28:01 -03:00
The documentation has been left in place to help in reading old code that uses
the module.
According to the dictionary, a bastion is "a fortified area or position", or
"something that is considered a stronghold." It's a suitable name for this
module, which provides a way to forbid access to certain attributes of an
object. It must always be used with the :mod:`rexec` module, in order to allow
restricted-mode programs access to certain safe attributes of an object, while
denying access to other, unsafe attributes.
2007-12-29 06:57:00 -04:00
.. I'm concerned that the word 'bastion' won't be understood by people
.. for whom English is a second language, making the module name
.. somewhat mysterious. Thus, the brief definition... --amk
2007-08-15 11:28:01 -03:00
2007-12-29 06:57:00 -04:00
.. I've punted on the issue of documenting keyword arguments for now.
2007-08-15 11:28:01 -03:00
.. function:: Bastion(object[, filter[, name[, class]]])
Protect the object *object*, returning a bastion for the object. Any attempt to
access one of the object's attributes will have to be approved by the *filter*
function; if the access is denied an :exc:`AttributeError` exception will be
raised.
If present, *filter* must be a function that accepts a string containing an
attribute name, and returns true if access to that attribute will be permitted;
if *filter* returns false, the access is denied. The default filter denies
access to any function beginning with an underscore (``'_'``). The bastion's
string representation will be ``<Bastion for name>`` if a value for *name* is
provided; otherwise, ``repr(object)`` will be used.
*class*, if present, should be a subclass of :class:`BastionClass`; see the
code in :file:`bastion.py` for the details. Overriding the default
:class:`BastionClass` will rarely be required.
.. class:: BastionClass(getfunc, name)
Class which actually implements bastion objects. This is the default class used
by :func:`Bastion`. The *getfunc* parameter is a function which returns the
value of an attribute which should be exposed to the restricted execution
environment when called with the name of the attribute as the only parameter.
*name* is used to construct the :func:`repr` of the :class:`BastionClass`
instance.