pymake package#

Subpackages#

Submodules#

Module contents#

pymake is a python package for building MODFLOW-based and other Fortran, C, and C++ programs. The package downloads the source files a target is released with and builds it with the meson build system, using the build file the target provides where there is one and writing one where there is not. The source files a generated build file lists are ordered with a directed acyclic graph of the module dependencies. A GNU makefile can be written for a target as well.

class Pymake(name='pymake', verbose=None)[source]#

Bases: object

Pymake class for interacting with pymake functionality. This is essentially a wrapper for all of the pymake functions needed to download and build a target.

argv_reset_settings(args)[source]#

Reset settings using command line arguments.

Parameters:

args (Namespace object) – reset self.variables using command line arguments

build(target=None, srcdir=None, modify_exe_name=False)[source]#

Build the target.

Parameters:

  • target (str) – target name. If target is None self.target is used. (default is None)

  • srcdir (str) – path to directory with source files. (default is None)

  • modify_exe_name (bool) – boolean that determines if the target name can be modified to include precision (dbl) and debugging (d) indicators.

compress_targets()[source]#

Compress targets in build_targets list.

download_setup(target, url=None, download_path='.', verify=True, timeout=30)[source]#

Setup download.

Parameters:

  • target (str) – target name

  • url (str) – url of asset

  • download_path (str) – path where the asset will be saved

  • verify (bool) – boolean defining ssl verification

  • timeout (int) – download timeout in seconds (default is 30)

download_target(target, url=None, download_path='.', verify=True, timeout=30)[source]#

Setup and download url.

Parameters:

  • target (str) – target name

  • url (str) – url of asset

  • download_path (str) – path where the asset will be saved

  • verify (bool) – boolean defining ssl verification

  • timeout (int) – download timeout in seconds (default is 30)

Returns:

success – boolean flag indicating download success

Return type:

bool

download_url()[source]#

Download files from the url.

Returns:

success – boolean flag indicating download success

Return type:

bool

finalize()[source]#

Finalize Pymake class.

reset(target)[source]#

Reset PyMake object variables for a target.

Parameters:

target (str) – target name

set_build_target_bool(target=None)[source]#

Evaluate if the executable exists and if so and the command line argument –keep is specified then the executable is not built.

Parameters:

target (str) – target name. If target is None self.target will be used. (default is None)

Returns:

build – boolean indicating if the executable should be built

Return type:

bool

update_build_targets()[source]#

Add target to build_targets list if it is not in the list.

update_target(target, modify_target=False)[source]#

Update target name with executable extension on Windows and based on pymake settings.

Parameters:

  • target (str) – target name

  • modify_target (bool) – boolean indicating if the target name can be modified based on pymake double and debug settings (default is False)

Returns:

target – updated target name

Return type:

str

build_apps(targets=None, pymake_object=None, download_dir=None, appdir=None, verbose=None, double=False, mesondir=None, exclude=None, clean=True)[source]#

Build all of the current targets or a subset of targets.

Parameters:

  • targets (str or list of str) – targets to build. If targets is None, all current targets will be built. Default is None

  • pymake_object (Pymake()) – Pymake object created outside of build_apps

  • download_dir (str) – download directory path

  • appdir (str) – target path

  • double (bool) – force double precision. (default is False)

  • mesondir (str) – Main meson.build file path. the directory a target is downloaded to is used when mesondir is None (default is None)

  • exclude (str or list of str) – list of targets to exclude from build

  • clean (bool) – boolean determining of final download should be removed

Returns:

returncode – integer value indicating successful completion (0) or failure (>0)

Return type:

int

download_and_unzip(url, pth='./', delete_zip=True, verify=True, timeout=30, max_requests=10, chunk_size=2048000, verbose=False)[source]#

Download and unzip a zip file from a url.

Parameters:

  • url (str) – url address for the zip file

  • pth (str) – path where the zip file will be saved (default is the current path)

  • delete_zip (bool) – boolean indicating if the zip file should be deleted after it is unzipped (default is True)

  • verify (bool) – boolean indicating if the url request should be verified

  • timeout (int) – url request time out length (default is 30 seconds)

  • max_requests (int) – number of url download request attempts (default is 10)

  • chunk_size (int) – maximum url download request chunk size (default is 2048000 bytes)

  • verbose (bool) – boolean indicating if output will be printed to the terminal

get_repo_assets(github_repo=None, version=None, error_return=False, verify=True)[source]#

Return a dictionary containing the file name and the link to the asset contained in a github repository.

Parameters:

  • github_repo (str) – Repository name, such as MODFLOW-USGS/modflow6. If github_repo is None set to ‘MODFLOW-USGS/executables’

  • version (str) – github repository release tag

  • error_return (bool) – boolean indicating if None will be returned if there are GitHub API issues

  • verify (bool) – boolean indicating if the url request should be verified

Returns:

result_dict – dictionary of file names and links

Return type:

dict

get_temporary_directories(appdir=None, target=None)[source]#

Get paths to temporary object, module, and source files.

Parameters:

  • appdir (str) – path for executable

  • target (str) – target name to be appended to the temporary directories. Default is None

Returns:

  • obj_temp (str) – path to temporary object files

  • mod_temp (str) – path to temporary module files

  • src_temp (str) – path to temporary source files

getmfexes(pth='.', version=None, platform=None, exes=None, verbose=False, verify=True)[source]#

Get the latest MODFLOW binary executables from a github site (MODFLOW-USGS/executables) for the specified operating system and put them in the specified path.

Parameters:

  • pth (str) – Location to put the executables (default is current working directory)

  • version (str) – Version of the MODFLOW-USGS/executables release to use. If version is None the github repo will be queried for the version number.

  • platform (str) – Platform that will run the executables. Valid values include mac, macarm, linux, win32 and win64. If platform is None, then routine will download the latest asset from the github repository.

  • exes (str or list of strings) – executable or list of executables to retain

  • verbose (bool) – boolean indicating if output will be printed to the terminal

  • verify (bool) – boolean indicating if the url request should be verified

getmfnightly(pth='.', platform=None, exes=None, verbose=False, verify=True)[source]#

Get the latest MODFLOW 6 binary nightly-build executables from github (MODFLOW-USGS/modflow6-nightly-build) for the specified operating system and put them in the specified path.

Parameters:

  • pth (str) – Location to put the executables (default is current working directory)

  • platform (str) – Platform that will run the executables. Valid values include mac, macarm, linux, win32 and win64. If platform is None, then routine will download the latest asset from the github repository.

  • exes (str or list of strings) – executable or list of executables to retain

  • verbose (bool) – boolean indicating if output will be printed to the terminal

  • verify (bool) – boolean indicating if the url request should be verified

linker_update_environment(cc='gcc', fc='gfortran', verbose=False)[source]#

Add additional LDFLAGS to the environment based on OS and compilers.

Parameters:

  • fc (str) – fortran compiler

  • cc (str) – c or cpp compiler

  • verbose (bool) – boolean for verbose output to terminal

Return type:

None

main(srcdir=None, target=None, fc='gfortran', cc='gcc', makeclean=True, double=False, debug=False, include_subdirs=False, fflags=None, cflags=None, syslibs=None, makefile=False, makefile_only=False, dryrun=None, makefiledir='.', srcdir2=None, extrafiles=None, excludefiles=None, sharedobject=False, appdir=None, verbose=False, inplace=False, mesondir=None)[source]#

Main pymake function.

Parameters:

  • srcdir (str) – path for directory containing source files

  • target (str) – executable name or path for executable to create

  • fc (str) – fortran compiler

  • cc (str) – c or cpp compiler

  • makeclean (bool) – boolean indicating if intermediate files should be cleaned up after successful build

  • double (bool) – boolean indicating a compiler switch will be used to create an executable with double precision real variables.

  • debug (bool) – boolean indicating is a debug executable will be built

  • include_subdirs (bool) – boolean indicating source files in srcdir subdirectories should be included in the build

  • fflags (list) – user provided list of fortran compiler flags

  • cflags (list) – user provided list of c or cpp compiler flags

  • syslibs (list) – user provided syslibs

  • makefile (bool) – boolean indicating if a GNU make makefile should be created

  • makefile_only (bool) – boolean indicating if a GNU make makefile should be created without building the target (default is False)

  • dryrun (bool) – deprecated name for makefile_only, which replaced it when the pymake build engine was removed (default is None)

  • makefiledir (str) – GNU make makefile path

  • srcdir2 (str) – additional directory with common source files.

  • extrafiles (str) – path for extrafiles file that contains paths to additional source files to include

  • excludefiles (str) – path for excludefiles file that contains filename of source files to exclude from the build

  • sharedobject (bool) – boolean indicating a shared object will be built

  • appdir (str) – path for executable

  • verbose (bool) – boolean indicating if output will be printed to the terminal

  • inplace (bool) – boolean indicating that the source files in srcdir, srcdir2, and defined in extrafiles will be used directly. If inplace is False, source files will be copied to a directory named srcdir_temp. (default is False)

  • mesondir (str) – Main meson.build file path. the current directory is used when mesondir is None (default is None)

Returns:

returncode – return code

Return type:

int

make_plots(srcdir, outdir, include_subdir=False, level=3, extension='.png', verbose=False)[source]#

Create plots of module dependencies.

Parameters:

  • srcdir (str) – path for source files

  • outdir (str) – path for output images

  • include_subdir (bool) – boolean indicating is subdirectories in the source file directory should be included

  • level (int) – dependency level (1 is the minimum)

  • extension (str) – output extension (default is .png)

  • verbose (bool) – boolean indicating if output will be printed to the terminal

meson_build(mesondir, fc=None, cc=None, appdir='.', build_dir='_build', debug=None, fflags=None, cflags=None, syslibs=None)[source]#

Build executable(s) using the meson build system.

Parameters:

  • mesondir (str) – path to the main meson.build file

  • fc (str) – fortran compiler (default is None, which will be the default system Fortran compiler)

  • cc (str) – c or cpp compiler (default is None, which will be the default c/cpp compiler)

  • appdir (str) – path where the executable(s) will be installed. (default is the current working directory)

  • build_dir (str) – directory where meson build files are generated (default is _build)

  • debug (bool) – boolean indicating if a debug executable will be built. the build type is left to the meson build file when None (default is None)

  • fflags (list) – user provided list of fortran compiler flags (default is None)

  • cflags (list) – user provided list of c or cpp compiler flags (default is None)

  • syslibs (list) – user provided list of linker flags (default is None)

Returns:

returncode – return code

Return type:

int

meson_install(mesondir, build_dir='_build')[source]#

Run meson install command.

Parameters:

  • mesondir (str) – path to the main meson.build file

  • build_dir (str) – directory where meson build files are generated (default is _build)

  • debug (bool) – boolean indicating if a debug executable will be built. the build type is left to the meson build file when None (default is None)

  • fflags (list) – user provided list of fortran compiler flags (default is None)

  • cflags (list) – user provided list of c or cpp compiler flags (default is None)

  • syslibs (list) – user provided list of linker flags (default is None)

Returns:

returncode – return code

Return type:

int

meson_setup(mesondir, fc='gfortran', cc='gcc', appdir='.', build_dir='_build', debug=None, fflags=None, cflags=None, syslibs=None)[source]#

Run meson setup command.

Parameters:

  • mesondir (str) – path to the main meson.build file

  • fc (str) – fortran compiler (default is None, which will be the default system Fortran compiler)

  • cc (str) – c or cpp compiler (default is None, which will be the default c/cpp compiler)

  • appdir (str) – path where the executable(s) will be installed. (default is the current working directory)

  • build_dir (str) – directory where meson build files are generated (default is _build)

  • debug (bool) – boolean indicating if a debug executable will be built. the build type is left to the meson build file when None (default is None)

  • fflags (list) – user provided list of fortran compiler flags (default is None)

  • cflags (list) – user provided list of c or cpp compiler flags (default is None)

  • syslibs (list) – user provided list of linker flags (default is None)

Returns:

returncode – return code

Return type:

int

parser(examples=None)[source]#

Construct the parser and return argument values.

Parameters:

examples (str)

Returns:

args – Namespace with command line arguments

Return type:

Namespace object

repo_latest_version(github_repo=None, verify=True)[source]#

Return a string of the latest version number (tag) contained in a github repository release.

Parameters:

github_repo (str) – Repository name, such as MODFLOW-USGS/modflow6. If github_repo is None set to ‘MODFLOW-USGS/executables’

Returns:

version – string with the latest version/tag number

Return type:

str

to_pydot(dag, filename='mygraph.png')[source]#

Create a png file of a Directed Acyclic Graph.

Parameters:

  • dag (object) – directed acyclic graph

  • filename (str) – path of the graph png

class usgs_program_data[source]#

Bases: object

USGS program database class.

static export_json(fpth='code.json', appdir=None, prog_data=None, current=False, update=True, write_markdown=False, partial_json=False, zip_path=None, verbose=False)[source]#

Export USGS program data as a json file.

Parameters:

  • fpth (str) – Path for the json file to be created. Default is “code.json”

  • appdir (str) – path for code.json. Overrides code.json path defined in fpth. Default is None.

  • prog_data (dict) – User-specified program database. If prog_data is None, it will be created from the USGS program database

  • current (bool) – If False, all USGS program targets are listed. If True, only USGS program targets that are defined as current are listed. Default is False.

  • update (bool) – If True, existing targets in the user-specified program database with values in the USGS program database. If False, existing targets in the user-specified program database will not be updated. Default is True.

  • write_markdown (bool) – If True, write markdown file that includes the target name, version, and the last-modified date of the download asset (url). Default is False.

  • partial_json (bool) – Create a partial code.json based on targets in the parent path for the code.json file. Default is False.

  • zip_path (str) – Zip code.json into zip_path. (default is None)

  • verbose (bool) – boolean for verbose output to terminal

static get_keys(current=False)[source]#

Get target keys from the USGS program database.

Parameters:

current (bool) – If False, all USGS program targets are listed. If True, only USGS program targets that are defined as current are listed. Default is False.

Returns:

keys – list of USGS program targets

Return type:

list

static get_precision(key)[source]#

Get the dictionary for a specified target.

Parameters:

key (str) – Target USGS program

Returns:

precision – List

Return type:

list

static get_program_dict()[source]#

Get the complete USGS program database.

Returns:

program_dict – Dictionary with USGS program attributes for all targets

Return type:

dict

static get_target(key)[source]#

Get the dictionary for a specified target.

Parameters:

key (str) – Target USGS program that may have a path and an extension

Returns:

program_dict – Dictionary with USGS program attributes for the specified key

Return type:

dict

static get_version(key)[source]#

Get the current version of the specified target.

Parameters:

key (str) – Target USGS program

Returns:

version – current version of the specified target

Return type:

str

static list_json(fpth='code.json')[source]#

List an existing code json file.

Parameters:

fpth (str) – Path for the json file to be listed. Default is “code.json”

static list_targets(current=False)[source]#

Print a list of the available USGS program targets.

Parameters:

current (bool) – If False, all USGS program targets are listed. If True, only USGS program targets that are defined as current are listed. Default is False.

static load_json(fpth='code.json')[source]#

Load an existing code json file. Basic error checking is done to make sure the file contains the correct keys.

Parameters:

fpth (str) – Path for the json file to be created. Default is “code.json”

Returns:

json_dict – Valid USGS program database

Return type:

dict

static update_json(fpth='code.json', temp_dict=None)[source]#

UPDATE an existing code json file.

Parameters:

  • fpth (str) – Path for the json file to be listed. Default is “code.json”

  • temp_dict (dict) – Dictionary with USGS program data for a target

zip_all(path, file_pths=None, dir_pths=None, patterns=None, append=False)[source]#

Compress all files in the user-provided list of file paths and directory paths that match the provided file patterns.

Parameters:

  • path (str) – path of the zip file that will be created

  • file_pths (str or list) – file path or list of file paths to be compressed

  • dir_pths (str or list) – directory path or list of directory paths to search for files that will be compressed

  • patterns (str or list) – file pattern or list of file patterns s to match to when creating a list of files that will be compressed

  • append (bool) – boolean indicating if file paths should be appended to an existing zip file