README.rst
1===============================================================================
2parse_type
3===============================================================================
4
5.. image:: https://img.shields.io/travis/jenisys/parse_type/master.svg
6 :target: https://travis-ci.org/jenisys/parse_type
7 :alt: Travis CI Build Status
8
9.. image:: https://img.shields.io/pypi/v/parse_type.svg
10 :target: https://pypi.python.org/pypi/parse_type
11 :alt: Latest Version
12
13.. image:: https://img.shields.io/pypi/dm/parse_type.svg
14 :target: https://pypi.python.org/pypi/parse_type
15 :alt: Downloads
16
17.. image:: https://img.shields.io/pypi/l/parse_type.svg
18 :target: https://pypi.python.org/pypi/parse_type/
19 :alt: License
20
21
22`parse_type`_ extends the `parse`_ module (opposite of `string.format()`_)
23with the following features:
24
25* build type converters for common use cases (enum/mapping, choice)
26* build a type converter with a cardinality constraint (0..1, 0..*, 1..*)
27 from the type converter with cardinality=1.
28* compose a type converter from other type converters
29* an extended parser that supports the CardinalityField naming schema
30 and creates missing type variants (0..1, 0..*, 1..*) from the
31 primary type converter
32
33.. _parse_type: http://pypi.python.org/pypi/parse_type
34.. _parse: http://pypi.python.org/pypi/parse
35.. _`string.format()`: http://docs.python.org/library/string.html#format-string-syntax
36
37
38Definitions
39-------------------------------------------------------------------------------
40
41*type converter*
42 A type converter function that converts a textual representation
43 of a value type into instance of this value type.
44 In addition, a type converter function is often annotated with attributes
45 that allows the `parse`_ module to use it in a generic way.
46 A type converter is also called a *parse_type* (a definition used here).
47
48*cardinality field*
49 A naming convention for related types that differ in cardinality.
50 A cardinality field is a type name suffix in the format of a field.
51 It allows parse format expression, ala::
52
53 "{person:Person}" #< Cardinality: 1 (one; the normal case)
54 "{person:Person?}" #< Cardinality: 0..1 (zero or one = optional)
55 "{persons:Person*}" #< Cardinality: 0..* (zero or more = many0)
56 "{persons:Person+}" #< Cardinality: 1..* (one or more = many)
57
58 This naming convention mimics the relationship descriptions in UML diagrams.
59
60
61Basic Example
62-------------------------------------------------------------------------------
63
64Define an own type converter for numbers (integers):
65
66.. code-block:: python
67
68 # -- USE CASE:
69 def parse_number(text):
70 return int(text)
71 parse_number.pattern = r"\d+" # -- REGULAR EXPRESSION pattern for type.
72
73This is equivalent to:
74
75.. code-block:: python
76
77 import parse
78
79 @parse.with_pattern(r"\d+")
80 def parse_number(text):
81 return int(text)
82 assert hasattr(parse_number, "pattern")
83 assert parse_number.pattern == r"\d+"
84
85
86.. code-block:: python
87
88 # -- USE CASE: Use the type converter with the parse module.
89 schema = "Hello {number:Number}"
90 parser = parse.Parser(schema, dict(Number=parse_number))
91 result = parser.parse("Hello 42")
92 assert result is not None, "REQUIRE: text matches the schema."
93 assert result["number"] == 42
94
95 result = parser.parse("Hello XXX")
96 assert result is None, "MISMATCH: text does not match the schema."
97
98.. hint::
99
100 The described functionality above is standard functionality
101 of the `parse`_ module. It serves as introduction for the remaining cases.
102
103
104Cardinality
105-------------------------------------------------------------------------------
106
107Create an type converter for "ManyNumbers" (List, separated with commas)
108with cardinality "1..* = 1+" (many) from the type converter for a "Number".
109
110.. code-block:: python
111
112 # -- USE CASE: Create new type converter with a cardinality constraint.
113 # CARDINALITY: many := one or more (1..*)
114 from parse import Parser
115 from parse_type import TypeBuilder
116 parse_numbers = TypeBuilder.with_many(parse_number, listsep=",")
117
118 schema = "List: {numbers:ManyNumbers}"
119 parser = Parser(schema, dict(ManyNumbers=parse_numbers))
120 result = parser.parse("List: 1, 2, 3")
121 assert result["numbers"] == [1, 2, 3]
122
123
124Create an type converter for an "OptionalNumbers" with cardinality "0..1 = ?"
125(optional) from the type converter for a "Number".
126
127.. code-block:: python
128
129 # -- USE CASE: Create new type converter with cardinality constraint.
130 # CARDINALITY: optional := zero or one (0..1)
131 from parse import Parser
132 from parse_type import TypeBuilder
133
134 parse_optional_number = TypeBuilder.with_optional(parse_number)
135 schema = "Optional: {number:OptionalNumber}"
136 parser = Parser(schema, dict(OptionalNumber=parse_optional_number))
137 result = parser.parse("Optional: 42")
138 assert result["number"] == 42
139 result = parser.parse("Optional: ")
140 assert result["number"] == None
141
142
143Enumeration (Name-to-Value Mapping)
144-------------------------------------------------------------------------------
145
146Create an type converter for an "Enumeration" from the description of
147the mapping as dictionary.
148
149.. code-block:: python
150
151 # -- USE CASE: Create a type converter for an enumeration.
152 from parse import Parser
153 from parse_type import TypeBuilder
154
155 parse_enum_yesno = TypeBuilder.make_enum({"yes": True, "no": False})
156 parser = Parser("Answer: {answer:YesNo}", dict(YesNo=parse_enum_yesno))
157 result = parser.parse("Answer: yes")
158 assert result["answer"] == True
159
160
161Create an type converter for an "Enumeration" from the description of
162the mapping as an enumeration class (`Python 3.4 enum`_ or the `enum34`_
163backport; see also: `PEP-0435`_).
164
165.. code-block:: python
166
167 # -- USE CASE: Create a type converter for enum34 enumeration class.
168 # NOTE: Use Python 3.4 or enum34 backport.
169 from parse import Parser
170 from parse_type import TypeBuilder
171 from enum import Enum
172
173 class Color(Enum):
174 red = 1
175 green = 2
176 blue = 3
177
178 parse_enum_color = TypeBuilder.make_enum(Color)
179 parser = Parser("Select: {color:Color}", dict(Color=parse_enum_color))
180 result = parser.parse("Select: red")
181 assert result["color"] is Color.red
182
183.. _`Python 3.4 enum`: http://docs.python.org/3.4/library/enum.html#module-enum
184.. _enum34: http://pypi.python.org/pypi/enum34
185.. _PEP-0435: http://www.python.org/dev/peps/pep-0435
186
187
188Choice (Name Enumeration)
189-------------------------------------------------------------------------------
190
191A Choice data type allows to select one of several strings.
192
193Create an type converter for an "Choice" list, a list of unique names
194(as string).
195
196.. code-block:: python
197
198 from parse import Parser
199 from parse_type import TypeBuilder
200
201 parse_choice_yesno = TypeBuilder.make_choice(["yes", "no"])
202 schema = "Answer: {answer:ChoiceYesNo}"
203 parser = Parser(schema, dict(ChoiceYesNo=parse_choice_yesno))
204 result = parser.parse("Answer: yes")
205 assert result["answer"] == "yes"
206
207
208Variant (Type Alternatives)
209-------------------------------------------------------------------------------
210
211Sometimes you need a type converter that can accept text for multiple
212type converter alternatives. This is normally called a "variant" (or: union).
213
214Create an type converter for an "Variant" type that accepts:
215
216* Numbers (positive numbers, as integer)
217* Color enum values (by name)
218
219.. code-block:: python
220
221 from parse import Parser, with_pattern
222 from parse_type import TypeBuilder
223 from enum import Enum
224
225 class Color(Enum):
226 red = 1
227 green = 2
228 blue = 3
229
230 @with_pattern(r"\d+")
231 def parse_number(text):
232 return int(text)
233
234 # -- MAKE VARIANT: Alternatives of different type converters.
235 parse_color = TypeBuilder.make_enum(Color)
236 parse_variant = TypeBuilder.make_variant([parse_number, parse_color])
237 schema = "Variant: {variant:Number_or_Color}"
238 parser = Parser(schema, dict(Number_or_Color=parse_variant))
239
240 # -- TEST VARIANT: With number, color and mismatch.
241 result = parser.parse("Variant: 42")
242 assert result["variant"] == 42
243 result = parser.parse("Variant: blue")
244 assert result["variant"] is Color.blue
245 result = parser.parse("Variant: __MISMATCH__")
246 assert not result
247
248
249
250Extended Parser with CardinalityField support
251-------------------------------------------------------------------------------
252
253The parser extends the ``parse.Parser`` and adds the following functionality:
254
255* supports the CardinalityField naming scheme
256* automatically creates missing type variants for types with
257 a CardinalityField by using the primary type converter for cardinality=1
258* extends the provide type converter dictionary with new type variants.
259
260Example:
261
262.. code-block:: python
263
264 # -- USE CASE: Parser with CardinalityField support.
265 # NOTE: Automatically adds missing type variants with CardinalityField part.
266 # USE: parse_number() type converter from above.
267 from parse_type.cfparse import Parser
268
269 # -- PREPARE: parser, adds missing type variant for cardinality 1..* (many)
270 type_dict = dict(Number=parse_number)
271 schema = "List: {numbers:Number+}"
272 parser = Parser(schema, type_dict)
273 assert "Number+" in type_dict, "Created missing type variant based on: Number"
274
275 # -- USE: parser.
276 result = parser.parse("List: 1, 2, 3")
277 assert result["numbers"] == [1, 2, 3]
278