Generator Script Interface

class pystencilssfg.SourceFileGenerator(sfg_config=None, keep_unknown_argv=False)

Context manager that controls the code generation process in generator scripts.

The SourceFileGenerator must be used as a context manager by calling it within a with statement in the top-level code of a generator script. Upon entry to its context, it creates an SfgComposer which can be used to populate the generated files. When the managed region finishes, the code files are generated and written to disk at the locations defined by the configuration. Existing copies of the target files are deleted on entry to the managed region, and if an exception occurs within the managed region, no files are exported.

Parameters:

• sfg_config (Optional[SfgConfig]) – Inline configuration for the code generator

• keep_unknown_argv (bool) – If True, any command line arguments given to the generator script that the SourceFileGenerator does not understand are stored in sfg.context.argv.

Configuration

class pystencilssfg.config.SfgConfig(extensions=None, header_only=None, outer_namespace=None, codestyle=None, clang_format=None, output_directory=None)

Configuration options for the SourceFileGenerator.

Parameters:

• extensions (Category[FileExtensions])

• header_only (BasicOption[bool])

• outer_namespace (BasicOption[str | _GlobalNamespace])

• codestyle (Category[CodeStyle])

• clang_format (Category[ClangFormatOptions])

• output_directory (Option[Path, str | Path])

extensions: Category[FileExtensions] = None

File extensions of the generated files

Options in this category:

FileExtensions.header	File extension for generated header file.
FileExtensions.impl	File extension for generated implementation file.

header_only: BasicOption[bool] = None

If set to True, generate only a header file.

This will cause all definitions to be generated inline.

outer_namespace: BasicOption[str | _GlobalNamespace] = None

The outermost namespace in the generated file. May be a valid C++ nested namespace qualifier (like a::b::c) or GLOBAL_NAMESPACE if no outer namespace should be generated.

GLOBAL_NAMESPACE

Indicates the C++ global namespace.

codestyle: Category[CodeStyle] = None

Options affecting the code style emitted by pystencils-sfg.

Options in this category:

CodeStyle.indent_width

The number of spaces successively nested blocks should be indented with

clang_format: Category[ClangFormatOptions] = None

Options governing the code style used by the code generator

Options in this category:

ClangFormatOptions.code_style	Code style to be used by clang-format.
ClangFormatOptions.force	If set to True, abort code generation if clang-format binary cannot be found.
ClangFormatOptions.skip	If set to True, skip formatting using clang-format.
ClangFormatOptions.binary	Path to the clang-format executable

output_directory: Option[Path, str | Path] = None

Directory to which the generated files should be written.

Categories, Parameter Types, and Special Values

class pystencilssfg.config._GlobalNamespace

pystencilssfg.config.GLOBAL_NAMESPACE = <pystencilssfg.config._GlobalNamespace object>

Indicates the C++ global namespace.

class pystencilssfg.config.FileExtensions(header=None, impl=None)

BasicOption category containing output file extensions.

Parameters:

• header (BasicOption[str])

• impl (BasicOption[str])

header: BasicOption[str] = None

File extension for generated header file.

impl: BasicOption[str] = None

File extension for generated implementation file.

class pystencilssfg.config.CodeStyle(indent_width=None, includes_sorting_key=None)

Options affecting the code style used by the source file generator.

Parameters:

• indent_width (BasicOption[int])

• includes_sorting_key (BasicOption[Callable[[HeaderFile], Any]])

indent_width: BasicOption[int] = None

The number of spaces successively nested blocks should be indented with

includes_sorting_key: BasicOption[Callable[[HeaderFile], Any]] = None

Key function that will be used to sort #include statements in generated files.

Pystencils-sfg will instruct clang-tidy to forego include sorting if this option is set.

class pystencilssfg.config.ClangFormatOptions(code_style=None, force=None, skip=None, binary=None)

Options affecting the invocation of clang-format for automatic code formatting.

Parameters:

• code_style (BasicOption[str])

• force (BasicOption[bool])

• skip (BasicOption[bool])

• binary (BasicOption[str])

code_style: BasicOption[str] = None

Code style to be used by clang-format. Passed verbatim to --style argument of the clang-format CLI.

Similar to clang-format itself, the default value is file, such that a .clang-format file found in the build tree will automatically be used.

force: BasicOption[bool] = None

If set to True, abort code generation if clang-format binary cannot be found.

skip: BasicOption[bool] = None

If set to True, skip formatting using clang-format.

binary: BasicOption[str] = None

Path to the clang-format executable