More actions
MYSTIC PYTHON DOCUMENTATION
~~~~~~~~~~~~~~~~~~~~~~~~~~~
ABOUT PYTHON AND MYSTIC
~~~~~~~~~~~~~~~~~~~~~~~
Mystic BBS has an embedded Python engine for both BBS modifications and
games, as well as completely scriptable servers.
For BBS related modifications, Python can be executed by a menu command or
through an MCI display code. This means that any prompt or command on a
menu can be replaced with a custom Python script developed by you.
In the case of the servers, Mystic takes care of all of the difficult stuff,
managing the connections, IP blocking and blacklisting, server threading and
messages, logging, etc. Mystic simply allows you to create Python extension
that handles only the client's interaction with the server.
REQUIREMENTS
~~~~~~~~~~~~
The requirements are as simple as having Python 2.7 installed on your
operating system. Mystic will automatically detect if Python is installed
upon startup, and dynamically embed the language into itself. This means
that Python is COMPLETELY OPTIONAL and its not a dependancy required to use
Mystic BBS. If it exists, great! Mystic will allow you to use it!
In Windows python27.dll can be copied into the Mystic directory or you can
include it into the operating system library path. The Python installation
may already do this for you.
In Linux, Mystic looks for libpython2.7.so.1.0
In OSX, Mystic looks for libpython2.7.dylib
MAKE SURE YOU ARE USING THE CORRECT VERSION FOR YOUR PROCESSOR. IF YOU ARE
USING 32-BIT MYSTIC YOU MUST BE USING THE 32-BIT PYTHON! IF YOU ARE USING
THE 64-BIT MYSTIC THEN YOU NEED THE 64-BIT PYTHON
WHY PYTHON 2.7 WHEN THERE IS A 3.X
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The answer to this question is not simple, as there are a lot of reasons why
2.X was selected over 3.X. This does not mean that 3.X will not be
supported in the future, but it likely wouldn't be until 2.X has become very
matured in Mystic. Anyway, reasons:
1. Better package support for 2.X
2. String handling is more in line with how Mystic works.
3. Has had many years of heavy use and proven stability.
4. The syntax and API is not likely to change and break Mystic
5. It is still the default Python version of Ubuntu 14.04 LTS
6. It is still the default Python version of OSX El Capitan
7. More programming resources (tutorials, websites, etc) for 2.X
PROBLEMS WHEN ATTEMPTING TO EXECUTE A PYTHON SCRIPT
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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%
FROM PYTHON DOCS:
These environment variables influence Pythons behavior, they are processed
before the command-line switches other than -E. It is customary that
command-line switches override environmental variables where there is a
conflict.
PYTHONHOME
Change the location of the standard Python libraries. By default, the
libraries are searched in prefix/lib/pythonversion and
exec_prefix/lib/pythonversion, where prefix and exec_prefix are
installation-dependent directories, both defaulting to /usr/local.
When PYTHONHOME is set to a single directory, its value replaces both
prefix and exec_prefix. To specify different values for these, set
PYTHONHOME to prefix:exec_prefix.
PYTHONPATH
Augment the default search path for module files. The format is the same
as the shells PATH: one or more directory pathnames separated by
os.pathsep (e.g. colons on Unix or semicolons on Windows). Non-existent
directories are silently ignored.
In addition to normal directories, individual PYTHONPATH entries may
refer to zipfiles containing pure Python modules (in either source or
compiled form). Extension modules cannot be imported from zipfiles.
The default search path is installation dependent, but generally begins
with prefix/lib/pythonversion (see PYTHONHOME above). It is always
appended to PYTHONPATH.
An additional directory will be inserted in the search path in front of
PYTHONPATH as described above under Interface options. The search path
can be manipulated from within a Python program as the variable sys.path
CREATING A PYTHON MODULE FOR MYSTIC
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For BBS modules, you first must import the BBS module:
import mystic_bbs as bbs
This will give you all of the BBS related functions addressable with a bbs.
prefix.
Note that in any loops you have in your BBS, you must trap the "shutdown"
boolean so that if it is true, your script will exit when Mystic requests
a shutdown.
MYSTIC PYTHON INTEGRATED BBS FUNCTIONS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
(THIS IS A WORK IN PROGRESS... PLANNING STAGES. IF THERE IS SOMETHING YOU
WANT PLEASE ASK)
IMPLEMENTED BBS-SPECIFIC FUNCTIONS:
write
writeln
menucmd
getkey
shutdown
getstr
getuser
onekey
keypressed
param_str
param_count
PLANNED:
Of course you get all of the Python stuff plus these functions:
RETURNS FUNCTION NAME PARAMETERS
INPUT/OUTPUT:
(none) clear (none)
(none) cleareol (none)
(char, bool) getkey (none)
(string) getstr (<mode>byte, <fieldsize>byte, <maxsize>byte, <default>string)
(bool) getyn (<text>string, <default>bool)
(none) gotoxy (<x>byte, <y>byte)
(bool) keypressed (<waitTime>?) or separate waitKey function with MS timer?
(char) moreprompt (none)
(none) movex (<x>byte)
(none) movey (<x>byte)
(char) onekey (<keys>string, <echo>bool)
(char,integer) onekeyrange (<keys>string, <min>integer, <max>integer
(none) out (string)
(none) outln (string)
(none) pause (none)
(none) pipe (string)
(none) pipeln (string)
(none) purgeinput (none)
(bool) showfile (<file>string, <baudrate>integer, <pause>bool)
(none) stuffkey (<keys>string)
(byte) textattr (none)
(byte) wherex (none)
(byte) wherey (none)
(none) write (string)
(none) writeln (string)
(none) writexy (<x>byte, <y>byte, <attr>byte, text<string>)
(none) writexypipe (<x>byte, <y>byte, <attr>byte, <pad>byte, text<string>
STRING FUNCTIONS:
(byte) mcilen (string)
(string) mci2str (string)
MISCELLANOUS / UNSORTED:
(bool) access (<acs>string)
(none) appendtext (<filename>string, <text>string)
(byte) getcodepage (none)
(byte) getgraphics (none)
(bool) ignoregroups (<optional on or off>bool) * IF this can be done they do same for codepage, textattr,graphics etc
(string) getprompt (<promptnumber>integer)
(none) hangup (none)
(none) log (<level>byte, <category>char, <text>string)
(none) menucmd (<cmd>string, <data>string)
(byte) node (none)
(none) setprompt (<promptnumber>integer, <text>string)
(bool) shutdown (none)
(none) upgradeuser (<level>byte)
key missing things TODO:
need to pass paramenters to the program somehow
need formatDate and various conversion functions
thisuser, user, msg areas, msg headers, msg text, file areas, file list
ansi buffer,
msg editor, ansi editor, text editor
box, listbox, screen save/restore, extended input
getattr putattr
getmailstats
getmsgbasestats
helper string functions from MPL?