Skip to main content

Simplifies to build parse types based on the parse module

Project description

Travis CI Build Status Latest Version Downloads License

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

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]

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

radish-parse_type-0.3.5.tar.gz (263.0 kB view details)

Uploaded Source

Built Distribution

radish_parse_type-0.3.5-py2-none-any.whl (240.0 kB view details)

Uploaded Python 2

File details

Details for the file radish-parse_type-0.3.5.tar.gz.

File metadata

File hashes

Hashes for radish-parse_type-0.3.5.tar.gz
Algorithm Hash digest
SHA256 1029556ce9a0c76612183775b71a058403c9acc322ac1099ee5497f29ccc6fa5
MD5 68cbae950748f4f08c1824ca670a7591
BLAKE2b-256 c3a3177e8715c995e011b7e6ff966b1408e8b5392d0ebb35ec16494c5a291f32

See more details on using hashes here.

Provenance

File details

Details for the file radish_parse_type-0.3.5-py2-none-any.whl.

File metadata

File hashes

Hashes for radish_parse_type-0.3.5-py2-none-any.whl
Algorithm Hash digest
SHA256 85c2bf02868670d8dc4ac28f97c4f9a26c0939f30c2aff7d194423fc3fdb66c3
MD5 eaccbd2becc67313e80c9761e66b0045
BLAKE2b-256 8021830503fc51e204b12af7f062bc8510ab1c32dd5ed237d1a2ade99e068c19

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page