Ctrl+K

fgen.wrapper_building

fgen.wrapper_building#

fgen’s wrapper building module

fgen.wrapper_building.formatting

Functions to use to format generated code

fgen.wrapper_building.fortran_manager_module

Generation of the Fortran manager module

fgen.wrapper_building.fortran_wrapper_module

Generation of the Fortran wrapper module

fgen.wrapper_building.python_enums_module

Generation of the Python enums module

fgen.wrapper_building.python_init_module

Generation of the Python init module

fgen.wrapper_building.python_wrapper_module

Generation of the Python wrapper module

ModuleWrapperGeneratorCallableLike#

class ModuleWrapperGeneratorCallableLike(*args, **kwargs)[source]#

Bases: Protocol[T_contra]

Callable that can generate a wrapper for a module

WrittenWrappers#

class WrittenWrappers(manager_file, wrapper_file)[source]#

Bases: object

Written wrappers

manager_file: pathlib.Path#

Path to the manager file

wrapper_file: pathlib.Path#

Path to the wrapper file

PackageWrapperGeneratorCallableLike#

class PackageWrapperGeneratorCallableLike(*args, **kwargs)[source]#

Bases: Protocol

Callable that can generate a wrapper for a package

try_to_write_file#

try_to_write_file(file, contents)[source]#

Try to write a file to disk, logging an exception if this fails.

Parameters:

  • file (pathlib.Path) – File to write to.

  • contents (str) – Contents to write in the file.

Return type:

None

write_file_with_checks#

write_file_with_checks(file, desc, generate_content, keep_existing=False, force=False)[source]#

Write a file, first checking what to do if the file already exists.

Parameters:

  • file (pathlib.Path) – Path in which the file will be written if the checks pass.

  • desc (str) – Description of the file which will be written if the checks pass. Only used for logging.

  • generate_content (typing.Callable[[], str]) – Function which generates the contents of the file. This is only called if the file is to be written.

  • keep_existing (bool) – Whether to always keep existing files. If this is True, if a file exists, it is not overwritten.

  • force (bool) – Whether to force overwrite an existing file. If this is True, if a file exists, it is overwritten.

Returns:

pathlib.Path – Path to the written file (or existing file if it already exists)

Raises:

  • FileExistsError – file exists and no flags are set to specify what to do.

  • ValueError – Both keep_existing and force are True. force will never be used in this case, hence an error is raised.

write_module_wrappers#

write_module_wrappers(package, shared, module, manager_directory, wrapper_directory, python_directory, extension, force)[source]#

Write the wrappers for a module

Parameters:
Returns:

fgen.wrapper_building.WrittenWrappers – The written wrappers

write_module_wrapper#

write_module_wrapper(desc, generator_function, builder, file_suffix, outdir, force)[source]#

Write a wrapper for a module

Parameters:
Returns:

pathlib.Path – Path to the file that was written

write_package_wrapper#

write_package_wrapper(package, desc, generator_function, outdir, filename, keep_existing=False, force=False)[source]#

Write a wrapper for the package

Parameters:

  • package (fgen.data_models.package.Package) – Package for which to write the wrapper.

  • desc (str) – Description of the wrapper being written (used for logging).

  • generator_function (fgen.wrapper_building.PackageWrapperGeneratorCallableLike) – Function to call to generate the wrapper’s contents.

  • outdir (pathlib.Path) – Directory in which to write the wrapper.

  • filename (str) – Name of the file in which to write the wrapper.

  • keep_existing (bool) – Whether to keep existing files, irrespective of the value of force.

  • force (bool) – Whether to force overwrite existing files.

Return type:

None

process_package#

process_package(package, shared, extension, manager_directory, wrapper_directory, python_directory, force=True)[source]#

Auto-generate python and fortran code for a package

This function writes 3 files for each module that is being wrapped:

  • manager: Lifecycle handling for derived types (in Fortran)

  • wrapper: Provides a fortran wrapper to the generated functions that can be

    made available to Python

  • python module: Python interface for creating and manipulating derived types.

This function may also write other files necessary for wrapping the package as a whole. This includes generating a __init__.py file if it doesn’t already exist in the python directory.

Parameters:

  • package (fgen.data_models.package.Package) – Package to generate wrappers for

  • shared (fgen.data_models.package_shared_elements.PackageSharedElements) – Shared elements which should be consistent across the package’s generated wrappers

  • extension (str) –

    Package name for the compiled extension module

    Typically, this is of the form my_module._lib

  • manager_directory (pathlib.Path) – Directory in which to write the derived type lifecycle manager(s)

  • wrapper_directory (pathlib.Path) – Directory to write the Python-Fortran wrapper(s).

  • python_directory (pathlib.Path) – Directory in which to write the python module(s).

  • force (bool) – If True, overwrite any existing files

Returns:

list[fgen.wrapper_building.WrittenWrappers] – The wrappers that were written

Raises:

FileExistsError – If not force and a targeted file exists

Contents