Simple "Symbol" Type
====================

Installing SymbolType (using ``"easy_install SymbolType"`` or
``"setup.py install"``) gives you access to the ``peak.util.symbols``
module, previously available only by installing the full PEAK toolkit.
``peak.util.symbols`` provides a ``Symbol`` type and two built-in symbols
that are used by PEAK: ``NOT_FOUND`` and ``NOT_GIVEN``.  You can create your
own symbol objects using the ``Symbol`` type, by giving it the symbol name
and the name of the module where the symbol is being created::

    >>> from peak.util.symbols import Symbol
    >>> AN_EXAMPLE = Symbol('AN_EXAMPLE', __name__)

The resulting object's ``repr()`` and ``str()`` forms are the same as the name
you passed in::

    >>> AN_EXAMPLE
    AN_EXAMPLE

    >>> str(AN_EXAMPLE)
    'AN_EXAMPLE'

But symbols compare equal only to themselves; they are not equal to strings::

    >>> AN_EXAMPLE == 'AN_EXAMPLE'
    False

    >>> AN_EXAMPLE == AN_EXAMPLE
    True

A symbol's ``__name__`` and ``__module__`` attributes are the original name and
module used to create the symbol::

    >>> from peak.util.symbols import NOT_FOUND

    >>> NOT_FOUND.__name__
    'NOT_FOUND'

    >>> NOT_FOUND.__module__
    'peak.util.symbols'

The reason that symbols want to know their defining module is that this allows
them to be pickled and unpickled correctly::

    >>> import pickle
    >>> pickle.loads(pickle.dumps(NOT_FOUND))
    NOT_FOUND

Specifically, it's so that the result of unpickling a symbol is exactly the
same object as the original symbol::

    >>> pickle.loads(pickle.dumps(NOT_FOUND)) is NOT_FOUND
    True

Note that this means the symbol must be defined at module level within its
module, with the same name that's passed in to it, or else ``pickle`` will
not be able to find it when unpickling.

Last, but not least, symbol objects are immutable and cannot be changed in
any way::

    >>> AN_EXAMPLE.foo = "bar"
    Traceback (most recent call last):
    ...
    TypeError: Symbols are immutable


Mailing List
------------

Please direct questions regarding this package to the PEAK mailing list; see
http://www.eby-sarna.com/mailman/listinfo/PEAK/ for details.