README.rst

parse_type

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

Definitions

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.

Basic Example

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.

Cardinality

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"] == None

Enumeration (Name-to-Value Mapping)

Create 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"] == True

Create 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.red

Choice (Name Enumeration)

A 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"

Variant (Type Alternatives)

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 result

Extended Parser with CardinalityField support

The 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]