Package: pymafia
pymafiapymafiais a Python module and bridge for reflecting KoLmafia's Java environment. It aims to provide an easy-to-use environment for scriptingKingdom of Loathing(KoL) in Python by reflecting and wrapping the community-developedKoLmafiadesktop tool. Whileother languagesfor scripting KoL exist, they are arguably less approachable to non-developers.Installationpymafiais available at thePython Package Index (PyPI):pip install pymafiapymafiausesJPypeto reflect KoLmafia's Java environment, so you will need to install a Java Development Kit (JDK) on your operating system — KoLmafia's developers recommendAdoptium v17. For information on troubleshooting your Java installation, seeJPype's troubleshooting guide.UsageTo get started, simply importpymafiaor any of its components. Doing so will download a KoLmafia jar file (if it is not present in the configured location) and start a Java Virtual Machine (JVM) with the jar file included in the JVM's classpath. This process can take over a minute depending on your internet connection.You can choose the revision of KoLmafia to use or location to run it from by setting these properties in thepymafia_configmodule prior to importingpymafia. The revision defaults to the last known working revision at the time of release and the location defaults to a folder named "kolmafia" in the current working directory.>>>importpymafia_config>>>pymafia_config.set_revision(27467)>>>pymafia_config.set_location("C:\\Users\\Documents\\kolmafia\\")>>>importpymafia# Start the JVMOnce you have configuredpymafiaand started, you will most likely want to launch the KoLmafia GUI and login to your character. Both of these actions can be performed using theutilsmodule.>>>frompymafia.utilsimportlaunch_gui,login>>>launch_gui()>>>login("devster6")Note that almost allpymafiaobjects are available at the top level, although this is subject to change.>>>frompymafiaimportlaunch_guiAccessing KoLmafiaThe reflected KoLmafia jar file can be accessed through aKoLmafiawrapper class instance calledkm. Most, if not all, of KoLmafia's Java classes are available as attributes onkm.>>>frompymafia.kolmafiaimportkm>>>km.AdventureResult<javaclass'net.sourceforge.kolmafia.AdventureResult'>These classes behave similar to how they do in Java with the exception of returning Python objects when possible. For more information on type conversion, seeJPype's type matching guide.>>> km.AdventureResult.tallyItem("big rock")
<java object 'net.sourceforge.kolmafia.AdventureResult'>

>>> km.AdventureResult.tallyItem("big rock").isBountyItem()
FalseASH and Special DatatypesAll of KoLmafia's runtime library functions can be accessed through theashsubmodule, which returns aLibraryFunctioninstance.>>>frompymafiaimportash>>>ash.gameday_to_stringLibraryFunction("gameday_to_string")TheLibraryFunctionis a thin wrapper around the desired Java method that will automatically convert the inputs and outputs of the wrapped method to and from Java objects, respectively. This conversion means that the functions accept and return Python objects, including KoLmafia'sspecial datatypes, which have been implemented in thedatatypessub-package.>>>frompymafia.datatypesimportLocation>>>ash.gameday_to_string()"Dougtember 3">>>ash.to_item("big rock")Item("big rock")>>>ash.appearance_rates(Location("Noob Cave")){Monster("none"):0.0,Monster("crate"):100.0}As demonstrated above, the datatypes can be instantiated directly from their name, id, or string representation where applicable. Each datatype has a set of properties that mirror those available from theirKoLmafia proxy recordequivalent.>>>frompymafia.datatypesimportFamiliar,Item>>>Item("big rock").tradeableTrue>>>Familiar("God Lobster").hatchlingItem("God Lobster Egg")Each datatype also has anall()class method that returns every non-none instance of that type.>>>frompymafia.datatypesimportStat>>>Stat.all()[Stat("Muscle"),Stat("Mysticality"),Stat("Moxie")]Many datatypes contain predefined class instances as class variables for convenient reference. Notably, all datatypes define aNONEclass variable.>>>Coinmaster.NONECoinmaster('none')>>>Slot.HATSlot('hat')Non-Documented FunctionalityThere are  modules and subpackages and available withinpymafiathat have not been described here; I hope to provide comprehensive documentation in the future.ContributingTo contribute topymafia, you will need to set up a development environment using the following steps:InstallpoetryClone this repositoryRunpoetry installinside the cloned repositoryAcknowledgementsThis project was inspired by Samuel Gaus'sfrattlesnakeand tadpoleloop'spymafiarepositories.