SymbolType Simple "symbol" type, useful for enumerations or sentinels 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. Phillip J. Eby 74e889834c9780ae22d7c8e13126b991295f6b66 1.0