parse_type extends the parse module (opposite of string.format()) with the following features:
- build type converters for common use cases (enum/mapping, choice)
- build a type converter with a cardinality constraint (0..1, 0..*, 1..*)
- from the type converter with cardinality=1.
- compose a type converter from other type converters
- an extended parser that supports the CardinalityField naming schema
- and creates missing type variants (0..1, 0..*, 1..*) from the primary type converter
- type converter
- A type converter function that converts a textual representation of a value type into instance of this value type. In addition, a type converter function is often annotated with attributes that allows the parse module to use it in a generic way. A type converter is also called a parse_type (a definition used here).
- cardinality field
A naming convention for related types that differ in cardinality. A cardinality field is a type name suffix in the format of a field. It allows parse format expression, ala:
"{person:Person}" #< Cardinality: 1 (one; the normal case) "{person:Person?}" #< Cardinality: 0..1 (zero or one = optional) "{persons:Person*}" #< Cardinality: 0..* (zero or more = many0) "{persons:Person+}" #< Cardinality: 1..* (one or more = many)This naming convention mimics the relationship descriptions in UML diagrams.
Define an own type converter for numbers (integers):
# -- USE CASE:
def parse_number(text):
return int(text)
parse_number.pattern = r"\d+" # -- REGULAR EXPRESSION pattern for type.This is equivalent to:
import parse
@parse.with_pattern(r"\d+")
def parse_number(text):
return int(text)
assert hasattr(parse_number, "pattern")
assert parse_number.pattern == r"\d+"# -- USE CASE: Use the type converter with the parse module.
schema = "Hello {number:Number}"
parser = parse.Parser(schema, dict(Number=parse_number))
result = parser.parse("Hello 42")
assert result is not None, "REQUIRE: text matches the schema."
assert result["number"] == 42
result = parser.parse("Hello XXX")
assert result is None, "MISMATCH: text does not match the schema."Hint
The described functionality above is standard functionality of the parse module. It serves as introduction for the remaining cases.
Create an type converter for "ManyNumbers" (List, separated with commas) with cardinality "1..* = 1+" (many) from the type converter for a "Number".
# -- USE CASE: Create new type converter with a cardinality constraint.
# CARDINALITY: many := one or more (1..*)
from parse import Parser
from parse_type import TypeBuilder
parse_numbers = TypeBuilder.with_many(parse_number, listsep=",")
schema = "List: {numbers:ManyNumbers}"
parser = Parser(schema, dict(ManyNumbers=parse_numbers))
result = parser.parse("List: 1, 2, 3")
assert result["numbers"] == [1, 2, 3]Create an type converter for an "OptionalNumbers" with cardinality "0..1 = ?" (optional) from the type converter for a "Number".
# -- USE CASE: Create new type converter with cardinality constraint.
# CARDINALITY: optional := zero or one (0..1)
from parse import Parser
from parse_type import TypeBuilder
parse_optional_number = TypeBuilder.with_optional(parse_number)
schema = "Optional: {number:OptionalNumber}"
parser = Parser(schema, dict(OptionalNumber=parse_optional_number))
result = parser.parse("Optional: 42")
assert result["number"] == 42
result = parser.parse("Optional: ")
assert result["number"] == NoneCreate an type converter for an "Enumeration" from the description of the mapping as dictionary.
# -- USE CASE: Create a type converter for an enumeration.
from parse import Parser
from parse_type import TypeBuilder
parse_enum_yesno = TypeBuilder.make_enum({"yes": True, "no": False})
parser = Parser("Answer: {answer:YesNo}", dict(YesNo=parse_enum_yesno))
result = parser.parse("Answer: yes")
assert result["answer"] == TrueCreate an type converter for an "Enumeration" from the description of the mapping as an enumeration class (Python 3.4 enum or the enum34 backport; see also: PEP-0435).
# -- USE CASE: Create a type converter for enum34 enumeration class.
# NOTE: Use Python 3.4 or enum34 backport.
from parse import Parser
from parse_type import TypeBuilder
from enum import Enum
class Color(Enum):
red = 1
green = 2
blue = 3
parse_enum_color = TypeBuilder.make_enum(Color)
parser = Parser("Select: {color:Color}", dict(Color=parse_enum_color))
result = parser.parse("Select: red")
assert result["color"] is Color.redA Choice data type allows to select one of several strings.
Create an type converter for an "Choice" list, a list of unique names (as string).
from parse import Parser
from parse_type import TypeBuilder
parse_choice_yesno = TypeBuilder.make_choice(["yes", "no"])
schema = "Answer: {answer:ChoiceYesNo}"
parser = Parser(schema, dict(ChoiceYesNo=parse_choice_yesno))
result = parser.parse("Answer: yes")
assert result["answer"] == "yes"Sometimes you need a type converter that can accept text for multiple type converter alternatives. This is normally called a "variant" (or: union).
Create an type converter for an "Variant" type that accepts:
- Numbers (positive numbers, as integer)
- Color enum values (by name)
from parse import Parser, with_pattern
from parse_type import TypeBuilder
from enum import Enum
class Color(Enum):
red = 1
green = 2
blue = 3
@with_pattern(r"\d+")
def parse_number(text):
return int(text)
# -- MAKE VARIANT: Alternatives of different type converters.
parse_color = TypeBuilder.make_enum(Color)
parse_variant = TypeBuilder.make_variant([parse_number, parse_color])
schema = "Variant: {variant:Number_or_Color}"
parser = Parser(schema, dict(Number_or_Color=parse_variant))
# -- TEST VARIANT: With number, color and mismatch.
result = parser.parse("Variant: 42")
assert result["variant"] == 42
result = parser.parse("Variant: blue")
assert result["variant"] is Color.blue
result = parser.parse("Variant: __MISMATCH__")
assert not resultThe parser extends the parse.Parser and adds the following functionality:
- supports the CardinalityField naming scheme
- automatically creates missing type variants for types with a CardinalityField by using the primary type converter for cardinality=1
- extends the provide type converter dictionary with new type variants.
Example:
# -- USE CASE: Parser with CardinalityField support.
# NOTE: Automatically adds missing type variants with CardinalityField part.
# USE: parse_number() type converter from above.
from parse_type.cfparse import Parser
# -- PREPARE: parser, adds missing type variant for cardinality 1..* (many)
type_dict = dict(Number=parse_number)
schema = "List: {numbers:Number+}"
parser = Parser(schema, type_dict)
assert "Number+" in type_dict, "Created missing type variant based on: Number"
# -- USE: parser.
result = parser.parse("List: 1, 2, 3")
assert result["numbers"] == [1, 2, 3]