parselglossy.api module#

Top-level functions for parselglossy.

parselglossy.api.document(template: Union[str, Path], outfile: Optional[Union[str, Path]] = None, header: str = 'Input parameters') str[source]#

Generate documentation in reStructuredText format from validation template.

Parameters
  • template (Union[str, Path]) – Which validation template to use.

  • output (Union[str, Path]) – Where to save the generated documentation. Defaults to None.

  • header (str) – Header for the documentation page. Defaults to Input parameters.

Return type

The documentation page as a string.

parselglossy.api.generate(template: Union[str, Path], *, where: Union[str, Path] = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/parselglossy/checkouts/v0.8.0/docs/input_parser'), grammar: Union[str, Path, List[Path]] = 'standard', tokenize: Optional[str] = None, docfile: str = 'input.rst', doc_header: str = 'Input parameters') Path[source]#

Generate parser for client.

Parameters
  • template (Union[str, Path]) – Which validation template to use.

  • where (Union[str, Path]) – Where to generate the parsing module. Default to input_parser folder under current working directory.

  • grammar (Union[str, Path, List[Path]]) – The file containing the grammar to use to tokenize user input. Defaults to standard, i.e. use one of the grammars packaged with the library, based on pyparsing.

  • tokenize (Optional[str]) – The commands to perform lexing of the input with a custom grammar. The result of these commands must be a variable named ir of type Dict[str, Any]. Defaults to None.

  • docfile (str) – The name of the documentation file for the input. Defaults to input.rst.

  • doc_header (str) – Header for the documentation page. Defaults to Input parameters.

Return type

Location of generated parser Python module as a Path object.

Notes

This function will generate a Python module for parsing inputs as defined by the template and grammar provided as parameters.

The user can provide a grammar as (a list of) external file(s). There are a few constraints:

  • The function performing tokenization must return an object of Dict[str, Any] type: a, potentially recursive, dictionary of keys and values.

  • Commands to perform tokenization are passed via the tokenize input parameters. This is a string that will copied verbatim in the generated code, relevant import statements have to be included in this string!

  • The result of the commands in tokenize must be a variable named ir.

  • It is the responsibility of the user to satisfy any dependencies of the parsing grammar they provided.

Raises

ParselglossyError

parselglossy.api.lex(infile: Union[str, Path], grammar: str = 'standard', ir_file: Optional[Union[str, Path]] = None) Dict[str, Any][source]#

Run grammar of choice on input string.

Parameters
  • infile (Union[str, Path]) – The string to be parsed.

  • grammar (str) – Grammar to be used.

  • ir_file (Union[str, Path]) – File to write intermediate representation to (JSON format). None by default, which means file is not written out.

Return type

The contents of the input string as a dictionary.

parselglossy.api.parse(infile: Union[str, Path], template: Union[str, Path], outfile: Optional[Union[str, Path]] = None, grammar: str = 'standard', dump_ir: bool = False) Dict[str, Any][source]#

Parse input file.

Parameters
  • infile (Union[str, Path]) – The input file to be parsed.

  • template (Union[str, Path]) – Which validation template to use.

  • outfile (Optional[Union[str, Path]]) – The output file. Defaults to None, which means writing to <infile>_fr.json.

  • grammar (str) – Which grammar to use. Defaults to standard.

  • dump_ir (bool) – Whether to write out the intermediate representation to file (JSON format). False by default. If true the filename if <infile>_ir.json

Return type

The validated input as a dictionary.

parselglossy.api.validate(infile: Union[str, Path], template: Union[str, Path], fr_file: Optional[Union[str, Path]] = None) Dict[str, Any][source]#

Validate intermediate representation into final representation.

Parameters
  • infile (Union[str, Path]) – The file with the intermediate representation (JSON format).

  • template (Union[str, Path]) – Which validation template to use.

  • fr_file (Union[str, Path]) – File to write final representation to (JSON format). None by default, which means file is not written out.

Return type

The validated input as a dictionary.