parse-type 0.6.6

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

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]