Python Package API documentation

This module provides functions to write SConstruct files to process Stata projects.

Additional SCons Options

--assume-done: list of file patterns

Skip execution, but mark all targets as up-to-date, for each script file in file pattern list

--assume-built: list of file patterns

If all targets for a task are specified, skip the task execution, but mark all targets as up-to-date.

--show-config: <existence>

List configuration read from files.

--config-files: string

Override the user-config files to read for configuration.

pystatacons.decider_str_lookup

Dictionary mapping string to objects that SCons' Decider function can handle. Can be used to easily specify our new Decider function 'content-timestamp-newer' which only runs a task if a depenency is different than last time SCons ran and a dependency is newer than all the targets (this means that if you run scripts outside of SCons, we won't rebuild them): Decider(pystatacons.decider_str_lookup['content-timestamp-newer'])

Type:

dict

pystatacons.special_sig_fns

Dictionary used by patch functions to have extension-specific signature functions. Can be updated with entries file-extension: function. The function should take a filename and return a string signature.

Type:

dict

pystatacons.init_env(env=None, tools=[], patch_scons_sig_fns=True, skip_scons_vs_check=False)

Sets up an environment for Stata.

Reads configuration data and saves to env['CONFIG']. By default it will check for and read two ini files ('config_project.ini' then 'config_local.ini'), though can be overridden using the '--config-files=....' option. If the config_local.ini is the first one, does not exist and 'utils/config_local_template.ini' does, the latter is copied to the former location.

Displays the config if the '--show-config' option was specified. Runs a Stata Tool to find Stata automatically. If this is not in a typical location then you can specify the full path as the value for a 'stata_exe' key under a '[Programs]' header in the configuration file. Attaches the 'StataBuild' Builder method to the environment. Optionally patches SCons to allow for file-extension-specific signature functions.

Parameters:

  • env (SConsEnvironment) -- Environment to configure for Stata support. If not provided will instantiate a DefaultEnvironment with the os.environ and no tools (many Stata users don't have defaults ones that SCons would complain about not finding).

  • tools (list) -- List of tools to initialize the returned environment with.

  • patch_scons_sig_fns (bool) -- Whether to patch the SCons file signature functions to support special signature functions by file extensions. Default support is provided for .dta files.

  • skip_scons_vs_check (bool) -- If false, will not output a warning when using a version of SCons that has not been tested.

Return type:

SConsEnvironment

pystatacons.stata_run_params_factory(self, target, source=None, do_file=None, params='', file_cmd='do', full_cmd=None, depends=None)

Factory function to create Builder instances for Stata tasks.

Typically called as env.StataBuild() and omitting the first (self) argument. Marks all targets as Precious() (more intuitive for Stata users, and facilitates --assume-done/built).

Build time: Tasks that specify file_cmd, params, or full_cmd will have their stata batch-mode log-file names so that it's the typical name with a short hash signature at the end (to ensure uniqueness). By default, successful tasks have their batch-mode log files deleted. An alternative is to put them in a directory Specified by the value of the 'success_batch_log_dir' key in the '[SCons]' header in a configuration file. By default, Stata's current directory when executing the script is the project root. This can be changed by specifying the value of the 'stata_chdir' key in the '[SCons]' header. If set to '1', then Stata will change to the directory of the script. If it is set as string, then Stata will change to this directory. On Windows, running Stata in batch-mode will typically briefly steal the focus. If the pywin32 Python package is installed, we will execute Stata batch-mode tasks in a hidden desktop to prevent this. (Does not work 100% of the time in Stata for some unknown reason.) As these processes are hidden, process IDs are printed to allow someone to kill the process manually if desired using Task Manager's Details tab. To disable this hidden-desktop behavior, set the 'win_stata_hidden' key's value to False in the section [Programs].

Parameters:

  • self (SConsEnvironment) -- Environment

  • target (list | str) -- Targets of the task

  • source (list | str) -- Sources of the task. If mulitple, then the first should be the Stata script file.

  • do_file (str) -- Alternative way of specifying the do file.

  • params (str) -- Parameters to the script execution

  • file_cmd (str) -- Override 'do' command for the script.

  • file_cmd -- Alternative to (file_cmd, script file, params) for specifying the full command

  • depends (list) -- Additional dependencies of the task. Equivalent to using Depends().

  • full_cmd (str) --

Return type:

NodeList