Mercurial > repos > shellac > guppy_basecaller

comparison env/lib/python3.7/site-packages/aenum/README @ 5:9b1c78e6ba9c draft default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
"planemo upload commit 6c0a8142489327ece472c84e558c47da711a9142"
author shellac
date Mon, 01 Jun 2020 08:59:25 -0400
parents 79f47841a781
children
comparison
equal deleted inserted replaced
4:79f47841a781 5:9b1c78e6ba9c
1 aenum --- support for advanced enumerations, namedtuples, and constants
2 ===========================================================================
3
4 Advanced Enumerations (compatible with Python's stdlib Enum), NamedTuples,
5 and NamedConstants
6
7 aenum includes a Python stdlib Enum-compatible data type, as well as a
8 metaclass-based NamedTuple implementation and a NamedConstant class.
9
10 An Enum is a set of symbolic names (members) bound to unique, constant
11 values. Within an enumeration, the members can be compared by identity, and
12 the enumeration itself can be iterated over. If using Python 3 there is
13 built-in support for unique values, multiple values, auto-numbering, and
14 suspension of aliasing (members with the same value are not identical), plus
15 the ability to have values automatically bound to attributes.
16
17 A NamedTuple is a class-based, fixed-length tuple with a name for each
18 possible position accessible using attribute-access notation as well as the
19 standard index notation.
20
21 A NamedConstant is a class whose members cannot be rebound; it lacks all other
22 Enum capabilities, however; consequently, it can have duplicate values.
23
24
25 Module Contents
26 ---------------
27
28 ``NamedTuple``
29 ^^^^^^^^^^^^^^
30 Base class for ``creating NamedTuples``, either by subclassing or via it's
31 functional API.
32
33 ``Constant``
34 ^^^^^^^^^^^^
35 Constant class for creating groups of constants. These names cannot be rebound
36 to other values.
37
38 ``Enum``
39 ^^^^^^^^
40 Base class for creating enumerated constants. See section ``Enum Functional API``
41 for an alternate construction syntax.
42
43 ``IntEnum``
44 ^^^^^^^^^^^
45 Base class for creating enumerated constants that are also subclasses of ``int``.
46
47 ``AutoNumberEnum``
48 ^^^^^^^^^^^^^^^^^^
49 Derived class that automatically assigns an ``int`` value to each member.
50
51 ``OrderedEnum``
52 ^^^^^^^^^^^^^^^
53 Derived class that adds ``<``, ``<=``, ``>=``, and ``>`` methods to an ``Enum``.
54
55 ``UniqueEnum``
56 ^^^^^^^^^^^^^^
57 Derived class that ensures only one name is bound to any one value.
58
59 ``IntFlag``
60 ^^^^^^^^^^^
61 Base class for creating enumerated constants that can be combined using
62 the bitwise operators without losing their ``IntFlag`` membership.
63 ``IntFlag`` members are also subclasses of ``int``.
64
65 ``Flag``
66 ^^^^^^^^
67 Base class for creating enumerated constants that can be combined using
68 the bitwise operations without losing their ``Flag`` membership.
69
70 ``unique``
71 ^^^^^^^^^^
72 Enum class decorator that ensures only one name is bound to any one value.
73
74 ``constant``
75 ^^^^^^^^^^^^
76 Descriptor to add constant values to an ``Enum``
77
78 ``convert``
79 ^^^^^^^^^^^
80 Helper to transform target global variables into an ``Enum``.
81
82 ``enum``
83 ^^^^^^^^
84 Helper for specifying keyword arguments when creating ``Enum`` members.
85
86 ``export``
87 ^^^^^^^^^^
88 Helper for inserting ``Enum`` members into a namespace (usually ``globals()``.
89
90 ``extend_enum``
91 ^^^^^^^^^^^^^^^
92 Helper for adding new ``Enum`` members after creation.
93
94 ``module``
95 ^^^^^^^^^^
96 Function to take a ``Constant`` or ``Enum`` class and insert it into
97 ``sys.modules`` with the affect of a module whose top-level constant and
98 member names cannot be rebound.
99
100 ``skip``
101 ^^^^^^^^
102 Descriptor to add a normal (non-``Enum`` member) attribute to an ``Enum``
103 or ``Constant``.
104
105
106 Creating an Enum
107 ----------------
108
109 Enumerations can be created using the ``class`` syntax, which makes them
110 easy to read and write. To define an enumeration, subclass ``Enum`` as
111 follows::
112
113 >>> from aenum import Enum
114 >>> class Color(Enum):
115 ... RED = 1
116 ... GREEN = 2
117 ... BLUE = 3
118
119 The ``Enum`` class is also callable, providing the following functional API::
120
121 >>> Animal = Enum('Animal', 'ANT BEE CAT DOG')
122 >>> Animal
123 <enum 'Animal'>
124 >>> Animal.ANT
125 <Animal.ANT: 1>
126 >>> Animal.ANT.value
127 1
128 >>> list(Animal)
129 [<Animal.ANT: 1>, <Animal.BEE: 2>, <Animal.CAT: 3>, <Animal.DOG: 4>]
130
131 Note that ``Enum`` members are boolean ``True`` unless the ``__nonzero__``
132 (Python 2) or ``__bool__`` (Python 3) method is overridden to provide
133 different semantics.
134
135
136 Creating a Flag
137 ---------------
138
139 ``Flag`` (and ``IntFlag``) has members that can be combined with each other
140 using the bitwise operators (&, \|, ^, ~). ``IntFlag`` members can be combined
141 with ``int`` and other ``IntFlag`` members. While it is possible to specify
142 the values directly it is recommended to use ``auto`` as the value and let
143 ``(Int)Flag`` select an appropriate value::
144
145 >>> from enum import Flag
146 >>> class Color(Flag):
147 ... RED = auto()
148 ... BLUE = auto()
149 ... GREEN = auto()
150 ...
151 >>> Color.RED & Color.GREEN
152 <Color.0: 0>
153 >>> bool(Color.RED & Color.GREEN)
154 False
155 >>> Color.RED | Color.BLUE
156 <Color.RED|BLUE: 3>
157
158 If you want to name the empty flag, or various combinations of flags, you may::
159
160 >>> class Color(Flag):
161 ... BLACK = 0
162 ... RED = auto()
163 ... BLUE = auto()
164 ... GREEN = auto()
165 ... WHITE = RED | BLUE | GREEN
166 ...
167 >>> Color.BLACK
168 <Color.BLACK: 0>
169 >>> Color.WHITE
170 <Color.WHITE: 7>
171
172 Note that ``(Int)Flag`` zero-value members have the usual boolean value of
173 ``False``.
174
175
176 Creating NamedTuples
177 --------------------
178
179 Simple
180 ^^^^^^
181
182 The most common way to create a new NamedTuple will be via the functional API::
183
184 >>> from aenum import NamedTuple
185 >>> Book = NamedTuple('Book', 'title author genre', module=__name__)
186
187 Advanced
188 ^^^^^^^^
189
190 The simple method of creating ``NamedTuples`` requires always specifying all
191 possible arguments when creating instances; failure to do so will raise
192 exceptions.
193
194 However, it is possible to specify both docstrings and default values when
195 creating a ``NamedTuple`` using the class method::
196
197 >>> class Point(NamedTuple):
198 ... x = 0, 'horizontal coordinate', 0
199 ... y = 1, 'vertical coordinate', 0
200 ...
201 >>> Point()
202 Point(x=0, y=0)
203
204
205 Creating Constants
206 ------------------
207
208 ``Constant`` is similar to ``Enum``, but do not support the ``Enum``
209 protocols, and have no restrictions on duplications::
210
211 >>> class K(Constant):
212 ... PI = 3.141596
213 ... TAU = 2 * PI
214 ...
215 >>> K.TAU
216 6.283192
217
218 More Information
219 ----------------
220
221 Detailed documentation can be found at `<aenum/doc/aenum.rst>`_