1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
|
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.
|
