Python API Reference

Fandango provides a simple API for Python programs to

• load a .fan specification with Fandango();

• produce outputs from the spec with fuzz(); and

• parse inputs using the spec with parse().

Note

This API will be extended over time.

Installing the API

When you install Fandango, the Python Fandango API is installed as well.

The Fandango class

The Fandango API comes as a class, named Fandango. To use it, write

from fandango import Fandango

The Fandango constructor allows reading in a .fan specification, either from an (open) file, a string, or a list of strings or files.

class Fandango(fan_files: str | IO | List[str | IO],
    constraints: List[str] = None, *,
    start_symbol: Optional[str] = None,
    use_cache: bool = True,
    use_stdlib: bool = True,
    logging_level: Optional[int] = None)

Create a Fandango object.

• fan_files is the Fandango specification to load. This is either

  • a string holding a .fan specification; or

  • an (open) .fan file; or

  • a list of strings or files.

• constraints, if given, is a list of additional constraints (as strings).

• start_symbol is the start symbol to use (default: <start>).

• use_cache can be set to False to avoid loading the input from cache.

• use_stdlib can be set to False to avoid loading the standard library.

• includes: A list of directories to search for include files before the Fandango spec locations.

• logging_level controls the logging output. It can be set to any of the values in the Python logging module, such as logging.DEBUG or logging.INFO. Default is logging.WARNING.

Danger

Be aware that .fan files can contain Python code that is executed when loaded. This code can execute arbitrary commands.

Warning

Code in the .fan spec cannot access identifiers from the API-calling code or vice versa. However, as both are executed in the same Python interpreter, there is a risk that loaded .fan code may bypass these restrictions and gain access to the API-calling code.

Caution

Only load .fan files you trust.

Fandango() can raise a number of exceptions, including

• FandangoSyntaxError if the .fan input has syntax errors. The exception attributes line, column, and msg hold the line, column, and error message.

• FandangoValueError if the .fan input has consistency errors.

The exception class FandangoError is the superclass of these exceptions.

The fuzz() method

On a Fandango object, use the fuzz() method to produce outputs from the loaded specification.

fuzz(extra_constraints: Optional[List[str]] = None, **settings)
    -> List[DerivationTree])

Create outputs from the specification, as a list of derivation trees.

In the future, the set of available settings may change dependent on the chosen algorithm.

• extra_constraints: if given, use this list of strings as additional constraints

• settings: pass extra values to control the fuzzer algorithm. These include

  • population_size: int: set the population size (default: 100).

  • desired_solutions: int: set the number of desired solutions.

  • initial_population: List[Union[DerivationTree, str]]: set the initial population.

  • max_generations: int: set the maximum number of generations (default: 500).

  • warnings_are_errors: bool can be set to True to raise an exception on warnings.

  • best_effort: bool can be set to True to return the population even if it does not satisfy the constraints.

The fuzz() method returns a list of DerivationTree objects. These are typically converted into Python data types (typically using str() or bytes()) to be used in standard Python functions.

fuzz() can raise a number of exceptions, including

• FandangoFailedError if the algorithm failed and warnings_are_errors is set.

• FandangoValueError if algorithm settings are invalid.

• FandangoParseError if a generator value could not be parsed.

The exception class FandangoError is the superclass of these exceptions.

The parse() method

On a Fandango object, use the parse() method to parse an input using the loaded specification.

parse(word: str | bytes | DerivationTree, *, prefix: bool = False, **settings)
    -> Generator[DerivationTree, None, None]

Parse a word; return a generator for derivation trees.

• word: the word to be parsed. This can be a string, a byte string, or a derivation tree.

• prefix: if True, allow incomplete inputs that form a prefix of the inputs accepted by the grammar.

• settings: additional settings for the parser.

  • There are no additional user-facing settings for the parser at this point.

The return value is a generator of derivation trees - if the .fan grammar is ambiguous, a single word may be parsed into different trees. To iterate over all trees parsed, use a construct such as

for tree in fan.parse(word):
    ...  # do something with the tree

parse() can raise exceptions, notably

• FandangoParseError if parsing fails. The attribute position of the exception indicates the position in word at which the syntax error was detected.[1]

Note

At this point, the parse() method does not check whether constraints are satisfied.

API Usage Examples

Fuzzing from a .fan Spec

Let us read and produce inputs from persons-faker.fan discussed in the section on generators and fakers:

from fandango import Fandango

# Read in a .fan spec from a file
with open('persons-faker.fan') as persons:
    fan = Fandango(persons)

for tree in fan.fuzz(desired_solutions=10):
    print(str(tree))

Danielle Maddox,1
Jennifer White,74
Jeffrey Martinez,37
Rodney Colon,59
Tammy Diaz,7
Michael Potter,23
Jared Alvarez,7
Sean Perry,98
Marcus Shea,703
Kelly Chandler,07

Fuzzing from a .fan String

We can also read a .fan spec from a string. This also demonstrates the usage of the logging_level parameter.

from fandango import Fandango
import logging

# Read in a .fan spec from a string
spec = """
    <start> ::= ('a' | 'b' | 'c')+
    where str(<start>) != 'd'
"""

fan = Fandango(spec, logging_level=logging.INFO)
for tree in fan.fuzz(population_size=3):
    print(str(tree))

fandango:INFO: <string>: saving spec to cache /home/runner/.cache/fandango/f94354f5584103bf2764367c84b3f839873d5d5a89704eb0baf8613220911a90.pickle

fandango:INFO: Redefining <start>

fandango:INFO: ---------- Initializing FANDANGO algorithm ---------- 

fandango:INFO: Generating initial population (size: 3)...

fandango:INFO: Initial population generated in 0.00 seconds

fandango:INFO: ---------- Starting evolution ----------

fandango:INFO: ---------- Evolution finished ----------

fandango:INFO: Perfect solutions found: (3)

fandango:INFO: Fitness of final population: 1.00

fandango:INFO: Time taken: 0.00 seconds

baabb
aa
cc

Parsing an Input

This example illustrates usage of the parse() method.

from fandango import Fandango

spec = """
    <start> ::= ('a' | 'b' | 'c')+
    where str(<start>) != 'd'
"""

fan = Fandango(spec)
word = 'abc'

for tree in fan.parse(word):
    print(f"tree = {repr(str(tree))}")
    print(tree.to_grammar())

tree = 'abc'
<start> ::= 'a' 'b' 'c'  # Position 0x0000 (0); 'abc'

Use the DerivationTree functions to convert and traverse the resulting trees.

Parsing an Incomplete Input

This example illustrates how to parse a prefix ('ab') for a grammar that expects a final d letter.

from fandango import Fandango

spec = """
    <start> ::= ('a' | 'b' | 'c')+ 'd'
    where str(<start>) != 'd'
"""

fan = Fandango(spec)
word = 'ab'

for tree in fan.parse(word, prefix=True):
    print(f"tree = {repr(str(tree))}")
    print(tree.to_grammar())

tree = 'ab'
<start> ::= 'a' 'b'  # Position 0x0000 (0); 'ab'

Without prefix=True, parsing would fail:

from fandango import Fandango

spec = """
    <start> ::= ('a' | 'b' | 'c')+ 'd'
    where str(<start>) != 'd'
"""

fan = Fandango(spec)
word = 'ab'

fan.parse(word)

Traceback (most recent call last):

  File /opt/hostedtoolcache/Python/3.13.2/x64/lib/python3.13/site-packages/IPython/core/interactiveshell.py:3549 in run_code
    exec(code_obj, self.user_global_ns, self.user_ns)

  Cell In[8], line 11
    fan.parse(word)

  File ~/work/fandango/fandango/src/fandango/__init__.py:230 in parse
    raise FandangoParseError(position=position)

  File <string>
FandangoParseError: Parse error at position 3

Handling Parsing Errors

This example illustrates handling of parse() errors.

from fandango import Fandango, FandangoParseError

spec = """
    <start> ::= ('a' | 'b' | 'c')+
    where str(<start>) != 'd'
"""

fan = Fandango(spec)
invalid_word = 'abcdef'

try:
    fan.parse(invalid_word)
except FandangoParseError as exc:
    error_position = exc.position
    print("Syntax error at", repr(invalid_word[error_position]))

Syntax error at 'e'

---

[1]

Note that due to parser lookahead, the position may be slightly off the position of the actual error.