Package

formaldict

class formaldict.Errors

Collects errors found when validating a Schema

class formaldict.FormalDict(*, schema, parsed, data, errors)

A formal dictionary of data associated with a Schema.

Formal dictionaries can be created two ways:

1. Schema(...).parse(data)
2. Schema(...).prompt()

After creation, attributes from the Schema can be accessed as attributes on the dictionary.

property data

The raw data used when constructing the formal dictionary

property errors

Returns an Errors class if any errors happened during parsing

property is_valid

True if the dictionary is valid and all attributes are present from the schema

property parsed

The parsed “formal” data.

Accessing the dictionary (i.e. data[key]) returns parsed data

class formaldict.Schema(schema)

The Schema object provides a definition of structured data and associated methods to parse and validate structured data.

Below is an example of a schema that represents a “name” and a “description”:

schema = Schema([{
    'label': 'description'
}, {
    'label': 'name'
}])

Each schema entry requires the “label”, a unique ID for the attribute being parsed, and a “type” that specifies the type of data being parsed.

After declaring the schema, one can parse dictionaries with Schema.parse(). For example:

data = schema.parse({'description': 'My Description', 'name': 'John'})

In the above, data is a FormalDict object, which can be accessed as a dictionary. If data.is_valid is True, it means that the data passed schema validation and was successfully parsed. data.errors will contain all of the schema errors that were found.

The Schema object directly integrates with python-prompt-toolkit, allowing one to prompt for information based on the schema.

For example:

data = schema.prompt()

The above will result in the user being prompted for all attributes in the schema in the order in which they were defined. Any data that passes the prompt will also pass the schema validation, ensuring that valid data is always returned from prompting.

The Schema object provides the ability to configure prompt help text, multi-line input, and parsing other types of data. See more examples below, which provide more information on schema attributes.

Examples

The schema below obtains a formal dictionary with information about a person - a name, address, marital status, and date of birth:

schema = Schema([{
    # The label is required and is the resulting key in the formal
    # dictionary
    'label': 'name',

    # The name is a human-readable description of the label. It is used
    # when prompting the user for the information. It defaults to
    # a title-ized version of the label.
    'name': 'Full Name',

    # The help is displayed when prompting the user.
    'help': 'Your full name (first, middle, and last).'

    # The type defaults to string. Currently formaldict supports
    # string and datetime types.
    'type': 'string'
}, {
    'label': 'address',
    'help': 'Enter your street, city, state, and zipcode',

    # The multiline attribute turns on multi-line mode when
    # prompting the user.
    'multiline': True
}, {
    'label': 'marital_status',
    'help': 'Your current marital status.',

    # The user is only allowed to enter the provided choices.
    'choices': [
        'single', 'separated', 'widowed', 'divorced', 'married'
    ],
}, {
    'label': 'dob',
    'name': 'Date of Birth',
    'help': 'Your birthday (YYYY/MM/DD)',

    # datetime types are parsed either as integers (unix timestamps)
    # or by any format accepted by dateutil
    # (https://dateutil.readthedocs.io/en/stable/)
    'type': 'datetime',

    # Everything is required by default.
    'required': False,
}])

Note

When declaring a schema, the order of entries will be the order in which the user is prompted for information.

Schemas allow conditional collection of information. For example, say that you want to create a schema where the user enters Jira ticket numbers and extended descriptions for all non-trivial types of changes to a project:

schema = Schema([
    'label': 'type',
    'help': 'The type of change being committed',
    'choices': ['bug', 'feature', 'trivial'],
}, {
    'label': 'description',
    'multiline': True,
    'help': 'An extended description of the change.',

    # Conditions are kmatch patterns
    # (https://github.com/ambitioninc/kmatch)
    # that must validate against the labels in previous steps.
    # This kmatch pattern asserts that we only collect
    # the description if the "type" entered by the user
    # is not the "trivial" choice.
    'condition': ['!=', 'type', 'trivial']
}, {
    'label': 'jira',
    'help': 'The Jira ticket number',
    'condition': ['!=', 'type', 'trivial'],

    # Use a regex for validating input.
    'matches': 'PROJ-\d+'
}])

In the above, the user would not be prompted for the “description” and “jira” steps if they entered “trivial” as the type of change. Similarly, one must enter a proper Jira ticket in order to pass the parsing of information. Here are some examples of parsing payloads that fail the schema:

# The jira ticket is not required for trivial changes. Remember,
# the "strict" flag verifies that all keys in the payload
# match keys that are required (or conditionally required) by
# the schema.
schema.parse({
    'type': 'trivial',
    'jira': 'PROJ-111'
}, strict=True)

# The jira ticket is required, but it does not match the pattern.
schema.parse({
    'type': 'bug',
    'description': 'Description of bug'
    'jira': 'invalid-ticket'
})

parse(data, strict=False)

Parse data based on the schema.

Parameters

strict (boolean, default=False) – If True, add a ValidationError to self.errors if any keys in the entry are not present in the schema.

Returns

The parsed data

Return type

dict

Todo

Allow passing in default values to override any defaults in the schema.

prompt(defaults=None)

Prompt for input of all entries in the schema

Parameters

defaults (dict, default=None) – Default values for the schema that should be used in place of any other declared defaults

Returns

The parsed information, which also validates against the Schema.

Return type

dict

formaldict.exceptions

exception formaldict.exceptions.Error

The base error for all formaldict errors

exception formaldict.exceptions.SchemaError

When an issue is found in the user-supplied schema

exception formaldict.exceptions.ValidationError

When a schema validation error happens