====== Python Implementation Notes ======

This section documents notes that relate to the implementation of Python in Mystic BBS. As new functions or additional changes are made, you will see them noted below.

The ability to incorporate Python code with Mystic BBS began with the arrival of Mystic 1.12 Alpha 1


  + PYTHON is here!  New menu command 'GY' will execute a Python 2.7 syntax
    script.  By default Mystic looks in the script directory for .MPY files,
    using the same logic as MPX.  If you supply a file with no extention,
    Mystic will add .mpy onto it.  If you do not supply a path, then Mystic
    will look in the current theme's script directory, and then the default
    script directory if fallback is enabled.
  
      Example:
  
         Command: GY
            Data: testpython
  
      The above executes testpython.mpy from the Scripts directory
  
      Example:
  
         Command: GY
            Data: c:\mystic\derp\herpderp
  
      The above executes herderp.mpy from the c:\mystic\derp directory, or
      if it is not found and fallback is enabled for the current theme, Mystic
      will look in the default scripts directory.
  
  + Moved the Python intialization code to only execute the first time a
    script is ran, so that if Python is incorrectly installed it will not
    prevent Mystic from loading with an error.
  
    If you get a "Import error: no module named site" when you DO try to
    execute a Python script, its because you have Python on your system but
    it is not completely installed.  You'll need to set your environment
    variables.  For example if you have Python installed in C:\Python27:
  
      SET PYTHONHOME=C:\PYTHON27
      SET PYTHONPATH=C:\PYTHON27\LIB
      SET PATH=%PYTHONHOME%;%PATH%
  
  + Prompts beginning with a # will now execute a Python script similar to
    MPL and display files:
  
       @myansi     <- Shows myansi from your theme's text dir
       !mympl      <- Execute mympl.mpx from theme's script dir
       #mypython   <- Execute mypython.mpy from theme's script dir
  
    In the small case that you ever need to start a prompt with one of
    these characters, you can prefix it with the "dummy" MCI code <pipe>XX
  
  + Added "getuser" and "onekey" functions into Python and updated the
    testpython.mpy in the default install.  This will continue to be updated
    as new functions and features are added and I need to test them.
     
  + Added a keypressed function to Python engine   
    
  + Mystic now prints a message if Python is executed when it is not detected
    on the system.
  
  + Mystic now prints a message if Python fails to initialize when executing
    Python.
  
  + Python scripts can now be executed from the command line, just like MPL
    scripts.  The format is the same except -Y is used, so for example:
  
      mystic -uSysop -ppassword -ytestpython
      
  + Mystic now logs whenever a Python script is executed.
  
  + New Python function "getuserid(ID)" returns a user dictionary of the user
   associated with ID.  If no user is found it will return None:
  
     import mystic_bbs as bbs;
  
     user = bbs.getuserid(1)
  
     if not user is None:
       bbs.writeln(user["handle"]);
    
  + New Python function "getmbase(num)" returns a Message Base dictionary of
   the record physically located at (num).  This example will print all of
   the message bases out:
  
     import mystic_bbs as bbs;
  
     count = 0;
  
     while not bbs.shutdown():
       mbase = bbs.getmbase(count);
  
       if mbase is None:
         break;
  
       bbs.writeln(mbase["name"]);
  
       count = count + 1;
  
     bbs.writeln("List complete. |PA");
  
  + New Python function "getmbaseid(ID)" returns a Message Base dictionary of
   the Message Base with ID of (ID).
  
  + New Python functions for reading Message Bases:
  
     msg_open, msg_seek, msg_found, msg_next, msg_prev, msg_gethdr,
     msg_gettxt, msg_close
  
    Rather than try to document them all here there is a "msgread.mpy"
    in the default Mystic installation as an example of how to use these 
    functions. This example implements a very basic message reader using the
    user's current message base. Check out the 'related links' section on this
    Wiki page to see an example of this script.
    

=== Related Links ===

  * [[python_examples|Mystic BBS Python Examples]]