===================
HowTo: Create a PYZ
===================
.. include:: ..\version.h
.. include:: howto-reference.h

.. contents:: Table of Contents
   :backlinks: top

*New in version 4.60*.

-------
Preface
-------

The PYZ format provides the ability to package a set of scripts together
as one file, and execute that set of scripts as one entity.

This document outlines the process of creating a script.

Related Links
-------------

 * `HowTo: Create a Basic MineSightŪ Grail Script`_

Assumptions
-----------

It is assumed that you are familiar with the MineSightŪ 3D, and the
basic mechanics of a python script.

You will require MineSightŪ 3D version 4.60 to run a PYZ file. You will
also require MPYTHON version 1.1 to use the "mpython" command on a PYZ
file from the command line. If you do not have MPYTHON 1.1, you can use
the :file:`mspz.exe` to launch a PYZ from the command line.

---------------
Getting Started
---------------

To create a PYZ all you need is a zip utility program. In our examples
we are using the :file:`zip.exe` that is available from `UnxUtils`_.

The layout of a PYZ is simple. You need to follow these rules,

  1. The PYZ must have a root file with the same name. If your pyz is
     called "run-code.pyz", then your root file must be called
     "run-code.py".

  1. Your root file must have a :f:`gmain`, and that :f:`gmain` must
     follow the rules of a standard MineSightŪ script.

As an example, lets convert the file
:file:`%MEDEXE%/scripts/samples/pyz-boilerplate.py` into a PYZ file.
First we will rename the file to :file:`sample.py`. 

   :: 
   
       copy %MEDEXE%/scripts/samples/pyz-boilerplate.py sample.py

next we will build the PYZ file using :file:`zip.exe` as follows,

   ::

      zip.exe sample.pyz sample.py

now we have a PYZ file that can be executed in MS3D, MSCOMPASS, or via
the command line using :file:`mspz.exe` (note, MPYTHON 1.1 automatically
forwards to :file:`mspz.exe`).

If you want to package a single PYZ out of a set of files, you would
repeat the above example with something like,

   ::

      zip.exe sample.pyz sample.py some_lib.py other_lib.py

and now, your root file, :file:`sample.py`, will be executed, and the
:file:`some_lib.py` and :file:`other_lib.py` will be available to the
script. In other words, if your script had,

   .. python::

      import some_lib
      import other_lib

it would import the files that you put into your PYZ package. 

-----------
Boilerplate
-----------

The :file:`%MEDEXE%/scripts/samples/pyz-boilerplate.py` will always show
the most up-to-date method of creating a good root file for your PYZ
package.


.. _UnxUtils: http://unxutils.sourceforge.net