valasp package

Submodules

valasp.core module

This module defines the Context class, a convenient place where classes and @-terms are registered.

An instance of Context can wrap one or more classes and functions to be used as @-terms by an ASP system. Classes can be registered by using a convenient decorator, and are used to inject data validation into an external ASP program.

class valasp.core.Context(wrap: Optional[List[Any]] = None, max_arity: int = 16)[source]

Bases: object

The place where classes and @-terms can be registered to make them available for the ASP system.

Typical usage just amount to create an instance and apply the valasp decorator to one or more classes, and at the end call the method run() to execute the ASP system.

valasp(validate_predicate: bool = True, with_fun: valasp.domain.primitive_types.Fun = <Fun.FORWARD_IMPLICIT: 0>, auto_blacklist: bool = True)[source]

Decorator to process classes for ASP validation.

Annotations on a decorated class are used to define attributes and to inject an __init__() method. If the class defines a __post_init__() method, it is called at the end of the __init__() method. Other common magic methods are also injected, unless already defined in the class.

Parameters

  • validate_predicate – True if the class is associated with a predicate in the ASP program

  • with_fun – modality of initialization for instances of the class

  • auto_blacklist – if True, predicates with the same name but different arities are blacklisted

Returns

a decorator

valasp_add_validator(predicate: valasp.domain.names.PredicateName, arity: int, fun: Optional[str] = None) → None[source]

Add a constraint validator for the given predicate name.

The constraint validator is paired with an @-term, which in turn calls the constructor of the associated class name.

Parameters

  • predicate – a predicate name to be validated

  • arity – the arity of the predicate

  • fun – the function name expected by the constructor of the associated class name, or None if the constructor expects a single value

valasp_all_arities_but(excluded: int) → List[int][source]

Return a list of all arities but excluded.

Parameters

excluded – an arity to exclude

Returns

a list of arities

valasp_blacklist(predicate: valasp.domain.names.PredicateName, arities: Optional[List[int]] = None) → None[source]

Add the given predicate name to the blacklist, for all provided arities.

Parameters

  • predicate – the predicate name to blacklist

  • arities – a list of arities, or None for blacklisting all arities

valasp_error(msg, args)[source]
static valasp_extract_error_message(error: Exception) → str[source]
valasp_is_reserved(key: str, auth: Optional[Any] = None) → bool[source]

Return True if the given key is reserved.

Parameters

  • key – a string

  • auth – if it is the internal secret, the valasp prefix is authorized

Returns

True if reserved

valasp_make_fun(filename: str, name: str, args: List[str], body_lines: List[str], with_self: bool = False) → Callable[source]

Return a function obtained by compiling the given code.

The provided code can refer classes and @-terms registered in the context.

Parameters

  • filename – the name of the file associated with the given code (for reference in errors)

  • name – the name of the function to create (for reference in errors)

  • args – the argument names of the function

  • body_lines – the actual code

  • with_self – True if self must be included in the arguments

Returns

a function

valasp_register_class(other: ClassVar) → None[source]

Add the given class to the context.

Parameters

other – a class

Raise

KeyError if the name of the class is reserved

valasp_register_term(filename: str, name: valasp.domain.names.PredicateName, args: List[str], body_lines: List[str], auth: Optional[Any] = None) → None[source]

Add the given @-term to the context.

Parameters

  • filename – the name of the file associated with the given code (for reference in errors)

  • name – the name of the @-term

  • args – the argument names

  • auth – if it is the internal secret, the valasp prefix is authorized

  • body_lines – the code to be associated with the @-term

valasp_run(control: clingo.Control, on_validation_done: Optional[Callable] = None, on_model: Optional[Callable] = None, aux_program: Optional[List[str]] = None, with_validators: bool = True, with_solve: bool = True) → None[source]

Run grounder on the given controller, possibly performing validation and searching for a model.

Parameters

  • control – a controller

  • on_validation_done – a function invoked after grounding, if no validation error is reported

  • on_model – a callback function to process a model

  • aux_program – more ASP code to add to the program

  • with_validators – if True, validator constraints are added, and before_grounding* and after_grounding* class methods are called

  • with_solve – if True, a model is searched

valasp_run_class_methods(prefix: str = 'check') → None[source]

Crawl all class methods with a given prefix, and a call them.

Parameters

prefix – a string

valasp_run_grounder(base_program: List[str]) → clingo.Control[source]

Run grounder for the given ASP code, including all validators.

Parameters

base_program – ASP code

Returns

the resulting controller

valasp_run_solver(base_program: List[str]) → Optional[List[clingo.SymbolicAtom]][source]

Run solver on the given ASP program, including all validators.

Parameters

base_program – ASP code

Returns

a model, or None if the program is inconsistent

valasp_validators() → str[source]

Return a string with all constraint validators.

Returns

constraints in a string

valasp.main module

The main method when the module is executed as a script is defined here.

Here is an example of usage for a valid file:

(valasp) $ cat examples/bday.yaml
valasp:
    python: |+
        import datetime
    asp: |+

date:
    year: Integer
    month: Integer
    day: Integer

    valasp:
        validate_predicate: False
        with_fun: TUPLE
        after_init: |+
            datetime.datetime(self.year, self.month, self.day)

bday:
    name:
        type: Alpha
        min: 3
    date: date

(valasp) $ cat examples/bday.valid.asp
bday(sofia, (2019,6,25)).
bday(leonardo, (2018,2,1)).

(valasp) $ python -m valasp examples/bday.yaml examples/bday.valid.asp
Answer: bday(sofia,(2019,6,25)) bday(leonardo,(2018,2,1))

And here is an example of invalid file:

(valasp) $ cat examples/bday.invalid.asp
bday(sofia, (2019,6,25)).
bday(leonardo, (2018,2,1)).
bday(bigel, (1982,123)).

(valasp) $ python -m valasp examples/bday.yaml examples/bday.invalid.asp
<block>:31:17-51: error: error in context:
  Traceback (most recent call last):
    File "<def valasp_validate_bday(value)>", line 2, in valasp_validate_bday
    File "<def Bday.__init__(self, value)>", line 16, in Bday____init__
    File "<def Date.__init__(self, value)>", line 7, in Date____init__
  ValueError: expecting arity 3 for TUPLE, but found 2

Functions in this module are not intended to be used directly or imported in some other module of this project.

valasp.main.main(args: List[str], stdout=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>, stderr=<_io.TextIOWrapper name='<stderr>' mode='w' encoding='UTF-8'>)[source]
valasp.main.parse_args(args, stdout, stderr) → Callable[source]
valasp.main.print_python_code(asp_files, validation_code, stdout, stderr)[source]
valasp.main.process_yaml(yaml_file: str) → List[str][source]
valasp.main.run_clingo(asp_files, validation_code, with_solve, stdout, stderr)[source]
valasp.main.run_clingo_with_solve(asp_files, validation_code, stdout, stderr)[source]
valasp.main.run_clingo_without_solve(asp_files, validation_code, stdout, stderr)[source]

Module contents