PYINSIM 1.6.4 BETA
I've uploaded pyinsim 1.6 BETA below. The new version of the library has been largely rewritten and contains many changes and additions, especially to the core InSim class. The idea behind this release is to clean up a lot of the old guff left over from earlier versions, so I can focus on pyinsim 2.0 and Python 3.0 support. That being said it is still the best version of pyinsim evar!
I'll try to give a rough overview of what's new in pyinsim 1.6!
Documentation
The documentation for the module has been rewritten and brought up date, with lots more information and better organisation, which should make using the documentation much easier. As before you can access the full API reference by opening the file 'documentation.html' included in the package download.
Examples
The examples included in the package have been rewritten and brought up to date as well, and several more new ones have been added! Again you can access the examples by browsing the 'examples' folder once you have unzipped the package.
Helper Functions
All of the old helper functions have been tweaked, tested and brought up-to-date, and in addition several (hopefully) useful ones have been added.
- strFromUnicode() - Convert a unicode string back into a LFS encoded string (thanks to morpha )
- collision() - Determine if two rectangles are colliding
- timeToMs() - Convert time list [h, m, s, t] back into milliseconds
- newEvt() - Create an event identifier for creating and raising your own custom events
- version() - Determine if the correct version of pyinsim is installed
Exceptions
A lot of work has been done on exceptions and pyinsim will no-longer raise general socket.errors, but instead has a set of new unique exception classes.
- InSimError - General InSim related errors
- InSimVersion - Incorrect version of InSim detected (more below)
- OutError - General OutSim and OutGauge related errors
- OutTimeout - An OutSim or OutGauge connection has timed out
In addition you no longer need to bind an event to EVT_ERROR to catch exceptions on the internal packet receive thread (although you can if you still want). Errors which occur on internal threads are now printed to std::err like all exceptions, which makes debugging pyinsim programs much easier and less confusing!
Performance
The overall performance of the module has been improved, through the use of pre-compiled structs and other code changes. As discussed in posts above __slots__ are used for MCI, NLP, OutGauge and OutSim packets, in order to reduce the memory overhead of creating these packets when using a small receive interval. For other packets the __slots__ are available but have actually been commented out, so you can reactivate them by doing a find and replace on 'pyinsim.py' and changing '#__slots__' to '__slots__'. It's high-tech engineering, I know.
API
As mentioned above most of the API changes reside in the InSim class, which has been largely rewritten. The most important change is that the
InSim.connect() method has been removed and replaced with the new InSim.init().
The new
Insim.init() method connects to LFS, sends the ISI packet, checks the InSim version, and starts a separate UDP connection when necessary. This means that the InSim connection process has been simplified to a single function call.
import pyinsim
insim = pyinsim.InSim()
try:
insim.init('localhost', 29999, IName='^3pyinsim') # Optional ISI args
except pyinsim.InSimVersion:
print 'Invalid InSim version detected'
except pyinsim.InSimError as err:
print 'InSim Error:', err
This code-snippet also demonstrates how to use the new exception classes, both to catch a InSimVersion exception, and a general InSimError.
The second major change is that
InSim.run() has been removed, as the new socket code makes it obsolete. In pyinsim 1.6 your program should remain active as long as LFS is connected (hopefully
)! Some more testing may be needed on this functionality, but it certainly works with Python 2.6.4.
In additon several old methods have been changed into instance variables, mainly InSim.isConnected(), InSim.getName() and InSim.setName(). This simply means that whereas before you did:
if insim.isConnected():
pass
You would now do:
if insim.connected:
pass
Lastly several new methods have been added that add some extra functionality to the class:
- InSim.sendm() - Shorthand for sending MST and MSX packets
- InSim.timer() - Execute a function callback after a timeout has elapsed
- InSim.event() - Raise a custom event
It is recommended that you checkout the full API reference to see all of the additions and changes, as it's hard to sum everything up in a few paragraphs. Obviously it goes without saying that these changes make pyinsim 1.6 incompatible with code written for previous versions, but hopefully these adjustments mean that I will not have to change the API for future release and can work on keeping future versions backwards compatible. That being said, the beta API could still change subtly before 1.6 goes final.
Download
So there we have what's new in pyinsim 1.6 BETA. You do need to have Python 2.6 in order for it to run, which you can download from the
official Python site. For installation instructions checkout the readme.txt file included in the download.
Note: As it is a beta it may still have one or two bugs, and some things may change before the final release, so you have been warned. Aside from that I'd be happy hear any comments or criticism you have regarding the module.