Source code for xdress.main
"""Top-level xdress entry point.
:author: Anthony Scopatz <scopatz@gmail.com>
XDress Comand Line Interface
============================
This module is where all of the API generation routines reside.
Until now the type system, automatic description, and cython code generation have
all be independent of what classes they are wrapping.
The main module is normally run via the command line interface as follows:
.. code-block:: bash
path/to/proj/ $ xdress
This has the following usage::
path/to/proj/ $ xdress -h
usage: Generates XDress API [-h] [--rc RC] [--plugins PLUGINS [PLUGINS ...]]
[--debug] [-v] [--dumpdesc] [--package PACKAGE]
[--packagedir PACKAGEDIR] [--sourcedir SOURCEDIR]
[--builddir BUILDDIR] [--bash-completion]
[--no-bash-completion]
[-I INCLUDES [INCLUDES ...]]
[-D DEFINES [DEFINES ...]]
[-U UNDEFINES [UNDEFINES ...]] [-p PARSERS]
[--clear-parser-cache-period CLEAR_PARSER_CACHE_PERIOD]
[--dumpast FILE] [--max-callbacks MAX_CALLBACKS]
[--extra-types EXTRA_TYPES] [--make-extra-types]
[--no-make-extra-types]
[--stlcontainers-module STLCONTAINERS_MODULE]
[--make-stlcontainers] [--no-make-stlcontainers]
optional arguments:
-h, --help show this help message and exit
--rc RC Path to run control file
--plugins PLUGINS [PLUGINS ...]
Plugins to include
--debug Build in debugging mode
-v, --verbose Print more output.
--dumpdesc Print the description cache
--package PACKAGE The Python package name for the generated wrappers
--packagedir PACKAGEDIR
Path to package directory, same as 'package' if not
specified
--sourcedir SOURCEDIR
Path to source directory
--builddir BUILDDIR Path to build directory
--bash-completion enable bash completion
--no-bash-completion disable bash completion
-I INCLUDES [INCLUDES ...], --includes INCLUDES [INCLUDES ...]
Additional include directories
-D DEFINES [DEFINES ...], --defines DEFINES [DEFINES ...]
Set additional macro definitions
-U UNDEFINES [UNDEFINES ...], --undefines UNDEFINES [UNDEFINES ...]
Unset additional macro definitions
-p PARSERS Parser(s) name, list, or dict
--clear-parser-cache-period CLEAR_PARSER_CACHE_PERIOD
Number of parser calls to perform before clearing the
internal cache. This prevents nasty memory overflow
issues.
--dumpast FILE Prints the abstract syntax tree of a file.
--max-callbacks MAX_CALLBACKS
The maximum number of callbacks for function pointers
--extra-types EXTRA_TYPES
Module and header file name for xdress extra types.
--make-extra-types make extra types wrapper
--no-make-extra-types
don't make extra types wrapper
--stlcontainers-module STLCONTAINERS_MODULE
Module name for C++ standard library container
wrappers.
--make-stlcontainers make C++ STL container wrappers
--no-make-stlcontainers
don't make C++ STL container wrappers
Sidecar Description Files
=========================
One main advantage of xdress is that every source file may have its own sidecar
Python file. This file includes additional information (docstrings, additional APIs,
etc.) about the classes and functions in the source file that it is next to. For
example, given header and source files named src/my_code.h and src/my_code.cpp then
the sidecar is called src/my_code.py.
These sidecars may contain a variable named ``mod`` which describes module elements
(classes and functions) coming from this source file. The mod variable may either
be a dictionary or a callable which returns a dictionary. This dictionary has the
following top-level keys:
:<names>: str, names of function and classes that are present in this source file.
The value for each name key is a partial or full description dictionary for
this module variable. See ``autodescribe.py`` for more details on description
dictionaries.
:docstring: str, optional, this is a documentation string for the module.
:extra: dict, optional, this stores arbitrary metadata that may be used with
different backends. It is not added by any auto-describe routine but may be
inserted later if needed. One example use case is that the Cython generation
looks for the pyx, pxd, and cpppxd keys for strings of supplemental Cython
code to insert directly into the wrapper. This is not generally used at the
module level.
Sidecar files are guaranteed to be executed only once. (Note that they are
execfile'd rather than imported.) Furthermore, the description dictionaries
that live under the name keys are merged with the automatically generated
descriptions. The sidecar descriptions take precedence over the automatically
generated ones.
Awesome abuses/hacks/side effects are possible since these sidecar files are
pure Python code. One major use case is to modify the type system from within a
sidecar. This is useful for adding refinement types or type specializations that
are pertinent to just that source code. This is done by creating a TypeSystem
instance in the sidecar, naming it ``ts``, and adding any user-modifications.
The sidecar's ``ts`` TypeSystem will automatically update the default run control
TypeSystem (``rc.ts``). For this reason, its often useful for the sidecar file's
type system to be empty.
Sidecar Example
---------------
The following example displays the contents of a sample sidecar file which adds
a refinement type (implemented elsewhere) to the type system so that it may be
used to declare additional attr and method APIs.
.. code-block:: python
# Start by adding refinement type hooks for 'sepeff_t', which is a type of map
from xdress.typesystem import TypeSystem
ts = TypeSystem.empty()
ts.register_refinement('sepeff_t', ('map', 'int32', 'float64'),
cython_cyimport='bright.typeconverters',
cython_pyimport='bright.typeconverters',
cython_py2c='bright.typeconverters.sepeff_py2c({var})',)
# Define a partial class description, will be merged into a full description
# by main() with the description coming from autodescriber.
desc = {
'docstrings': {
'class': "I am reprocess class",
'attrs': {
'sepeff': "I am an attr",
},
'methods': {
'initialize': "init with me",
'calc_params': "make some params",
'calc': "run me",
},
},
'attrs': {
'sepeff': 'sepeff_t', # redefine attr as refinement type
},
'methods': {
# Add a constructor which takes as its first argument the new refinement
('Reprocess', ('sepeff', 'sepeff_t'), ('name', 'str', '""')): None,
},
}
# Module description
mod = {'Reprocess': desc,
'docstring': "Python wrapper for Reprocess.",}
Main API
========
"""
from __future__ import print_function
import os
import io
import sys
import argparse
import warnings
from pprint import pprint, pformat
try:
import argcomplete
except ImportError:
argcomplete = None
from .utils import NotSpecified, RunControl, DEFAULT_RC_FILE, DEFAULT_PLUGINS, \
exec_file, parse_global_rc
from .plugins import Plugins
if sys.version_info[0] >= 3:
basestring = str
[docs]def main():
"""Entry point for xdress API generation."""
warnings.simplefilter('default')
# Preprocess plugin names, which entails preprocessing the rc file
preparser = argparse.ArgumentParser("XDress Pre-processor", add_help=False)
preparser.add_argument('--rc', default=NotSpecified,
help="path to run control file")
preparser.add_argument('--plugins', default=NotSpecified, nargs="+",
help="plugins to include")
preparser.add_argument('--bash-completion', default=True, action='store_true',
help="enable bash completion", dest="bash_completion")
preparser.add_argument('--no-bash-completion', action='store_false',
help="disable bash completion", dest="bash_completion")
prens = preparser.parse_known_args()[0]
predefaultrc = RunControl(rc=DEFAULT_RC_FILE, plugins=DEFAULT_PLUGINS)
prerc = RunControl()
prerc._update(predefaultrc)
prerc.rc = prens.rc
rcdict = {}
if os.path.isfile(prerc.rc):
exec_file(prerc.rc, rcdict, rcdict)
prerc.rc = rcdict['rc'] if 'rc' in rcdict else NotSpecified
prerc.plugins = rcdict['plugins'] if 'plugins' in rcdict else NotSpecified
prerc._update([(k, v) for k, v in prens.__dict__.items()])
# run plugins
plugins = Plugins(prerc.plugins)
parser = plugins.build_cli()
if argcomplete is not None and prerc.bash_completion:
argcomplete.autocomplete(parser)
ns = parser.parse_args()
rc = plugins.merge_rcs()
rc._update(parse_global_rc())
rc._update(rcdict)
rc._update([(k, v) for k, v in ns.__dict__.items()])
plugins.setup()
plugins.execute()
plugins.teardown()
plugins.exit()
if __name__ == '__main__':
main()
