Metadata-Version: 1.1
Name: starlink-pywrapper
Version: 0.3rc1
Summary: Provides a wrapper around the Starlink software suite commands.
Home-page: http://github.com/Starlink/starlink-pywrapper
Author: SF Graves
Author-email: s.graves@eaobservatory.org
License: GPLv3+
Description: .. inclusion-marker-do-not-remove
        Provides a wrapper around the Starlink software suite commands.
        
        **This package requires a separate working Starlink installation to be
        available.** It allow easy 'pythonic' calling of Starlink commands
        from python, by settuping the environmental variables inside Python
        and then using `subprocess.Popen` to run the Starlink binaries.
        
        The wrapped Starlink packages are each provided in their own python
        module, available as `starlink.<modulename>`, and the within the
        package as starlink.<modulename>.<commandname>.
        
        
        Using this package
        ==================
        
        Setting up the package
        ----------------------
        
        First of all, you will have to let this module know where your
        Starlink software suite is installed. You can either directly set the
        location inside python as:
        
        >>> from starlink import wrapper
        >>> wrapper.change_starpath('/path/to/my/starlink/installation')
        
        Alternatively, before you start Python you could set the STARLINK_DIR
        environmental variable to the location of your starlink
        installation. For example, in a BASH shell you could run `export
        STARLINK_DIR=~/star-2017A`.
        
        
        To see which Starlink is currently being used examine the variable
        `wrapper.starpath`.
        
        or if you are using a module you can do e.g.:
        
        >>> print(kappa.wrapper.starpath)
        
        
        Running the commands.
        ---------------------
        
        You will need to import each Starlink package that you want to use. For
        example, to run the `stats` command from KAPPA on a file `myndf.sdf`
        you would do:
        
        >>> from starlink import kappa
        >>> statsvals = kappa.stats('myndf.sdf')
        
        Each command will return a namedtuple object with all of the output found
        in `$ADAM_USER/commandname.sdf`.
        
        To see a field in a namedtuple result, you can do:
        
        >>> print(statsvals.mean)
        
        or to see what fields are available, you can do:
        
        >>> print(statsvals._fields)
        
        (Or inside an ipython terminal session or jupyter notebook you can tab
        complete to see the list of available fields.)
        
        Getting help.
        -------------
        
        This package includes docstrings for each command, summarising the
        command and its arguments and keywords. This can be seen in the normal
        python way, e.g.
        
        >>> help(kappa.ndftrace)
        
        At the bottom of the command it should also give you the URL to see
        the full documentation in the Starlink User Notes.
        
        To see the available commands in a package, there is a utiliity
        'starhelp' that will show you the name and the short one-line
        description for each command. You can use it on a Starlink module like so:
        
        >>> from starlink.utilities import starhelp
        >>> starhelp(kappa)
        
        
        `starhelp` can also be called with a command name as the argument: it
        will then show you the full documentation for that command within your
        python session.
        
        >>> starhelp(kappa.stats)
        
        
        Directly running a command without using the specific package.
        --------------------------------------------------------------
        
        
        You can also directly run a starlink command using
        :meth:`starlink.wrapper.starcomm` method. This method is used by the starlink
        modules to run the commands.
        
        >>> from starlink import wrapper
        >>> results = wrapper.starcomm('$KAPPA_DIR/ndftrace', 'ndftrace', 'myndf.sdf')
        
        This can be helpful if there is something wrong with the
        automatically-generated argument and keyword options in the specific
        commands, or if you are trying to run a command that is not included
        in the regular packages.
        
        Logging and seeing the full output.
        -----------------------------------
        
        These modules use the standard python logging module. To see the normal
        stdout of a starlink command, as well as the details of the commanline , you will need to set the logging module
        to DEBUG, i.e.:
        
        >>> import logging
        >>> logger = logging.getLogger()
        >>> logger.setLevel(logging.DEBUG)
        
        You can also return all the information that is normally written to screen by
        setting the extra keyword argument `returnstdout=True`. This will cause your command
        to return a two part tuple of `(<normal-output>, <string-of-output-from-screen>)`.
        
        
        ORAC-DR and PICARD
        ------------------
        
        ORAC-DR and Picard work slighly differently from the other Starlink packages.
        
        
        Details of package
        ==================
        
        The commands in this package are (mostly) automatically generated from
        a Starlink build using a helper script. This script is present in the
        git repo for this project
        (https://github.com/Starlink/starlink-pywrapper , see the
        'helperfunctions' directory), but is not distributed when you install
        the software. Currently the FLUXES package is the only manually
        created command.
        
        
        This package uses subprocess.Popen to wrap the Starlink command calls,
        and sets up the necessary environmental variables itself. It uses the
        Starlink module to access the output data written into
        $ADAM_USER/commandname.sdf and return it to the user. It is not
        necessary to setup Starlink before using this script (e.g. by running
        `source $STARLINK_DIR/etc/profile` or similar), but you do have to
        tell the package where $STARLINK_DIR is, either by setting the
        environmental variable before starting Python, or by calling the
        `starlink.wrapper.change_starpath` command with the appropriate
        location.
        
        This package uses a local, temporary $ADAM_USER created in the current working
        directory and deleted on exit, so it is safe to have multiple scripts
        running concurrently on the same machine.
        
        This package should be regenerated for each Starlink release; normally
        most commands will stay unchanged on a new release, but there are
        normally a few additional commands (or deletion of obsolete commands),
        and the call signature for some commands may also change.
        
        
        
        Known Issues
        ============
        
        1. When calling Starlink commands that are really python scripts, such
        as :meth:`starlink.smurf.jsasplit`, the module will not raise a proper error
        . Please ensure you can see the DEBUG info to identify problems.
        (This can be fixed if the scripts raise an exit code on error).
        
        2. If running a command (such as :meth:`starlink.kappa.display` that launches a
        GWM xwindow, the command will hang until you close the window. (DSB's
        starutil.py module in SMURF has a solution to this already).
        
        3. Also with GWM windows: these are missing the row of buttons along
        the bottom, unless the python call reuses an existing xw launched
        directly from Starlink. It is not known why.
        
Platform: UNKNOWN
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
