Metadata-Version: 2.1
Name: pymafia
Version: 0.2.2
Summary: A Python module and bridge for reflecting KoLmafia's Java environment
Home-page: https://github.com/MrFizzyBubbs/pymafia
License: MIT
Author: MrFizzyBubbs
Author-email: MrFizzyBubbs@protonmail.com
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Dist: JPype1 (>=1.4.1,<2.0.0)
Requires-Dist: wrapt (>=1.15.0,<2.0.0)
Project-URL: Repository, https://github.com/MrFizzyBubbs/pymafia
Description-Content-Type: text/markdown

# pymafia

*pymafia* is a Python module and bridge for reflecting KoLmafia's Java environment. It aims to provide an easy-to-use environment for scripting [Kingdom of Loathing](https://www.kingdomofloathing.com/) (KoL) in Python by reflecting and wrapping the community-developed [KoLmafia](https://github.com/kolmafia/kolmafia) desktop tool. While [other languages](https://loathing-associates-scripting-society.github.io/KoL-Scripting-Resources/) for scripting KoL exist, they are arguably less approachable to non-developers. 

## Installation
*pymafia* is available at the [Python Package Index (PyPI)](https://pypi.org/project/pymafia/):

```
pip install pymafia
```

*pymafia* uses [JPype](https://github.com/kivy/pyjnius) to reflect KoLmafia's Java environment, so you will need to install a Java Development Kit (JDK) on your operating system — KoLmafia's developers recommend [Adoptium v17](https://adoptium.net/index.html). For information on troubleshooting your Java installation, see [JPype's troubleshooting guide](https://jpype.readthedocs.io/en/latest/install.html#if-it-fails).

## Usage
To get started, simply import *pymafia* or any of its components. Doing so will download a KoLmafia jar file (if it is not present in the current working directory) 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 change the revision of KoLmafia to use by setting the revision in the `pymafia_config` module prior to importing *pymafia*.

```python
>>> import pymafia_config

>>> pymafia_config.set_revision(27467)

>>> pymafia_config.set_revision("latest")
```

Once you have set your desired revision, you will most likely want to launch the KoLmafia GUI and login to your character. Both of these actions can be performed using the `utils` module.

```python
>>> from pymafia.utils import launch_gui, login

>>> launch_gui()

>>> login("devster6")
```

Note that almost all *pymafia* objects are available at the top level, although this is subject to change.

```python
>>> from pymafia import launch_gui
```

### Accessing KoLmafia
The reflected KoLmafia jar file can be accessed through a `KoLmafia` wrapper class instance called `km`. Most, if not all, of KoLmafia's Java classes are available as attributes on `km`.

```python
>>> from pymafia.kolmafia import km

>>> km.AdventureResult
<java class 'net.sourceforge.kolmafia.AdventureResult'>
```

The Java classes behave similar to how they do in Java with the exception of returning Python objects when possible. For more information on the type conversions, see [JPype's type matching guide](https://jpype.readthedocs.io/en/latest/userguide.html#type-matching).

```
>>> km.AdventureResult.tallyItem("big rock")
<java object 'net.sourceforge.kolmafia.AdventureResult'>

>>> km.AdventureResult.tallyItem("big rock").isBountyItem()
False
```

### ASH and Special Datatypes
All of KoLmafia's runtime library functions can be accessed through the `ash` submodule, which returns a `LibraryFunction` instance. 

```python
>>> from pymafia import ash

>>> ash.gameday_to_string
LibraryFunction("gameday_to_string")
```

The `LibraryFunction` is 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's [special datatypes](https://wiki.kolmafia.us/index.php/Data_Types#Special_Datatypes), which have been implemented in the `datatypes` sub-package.

```python
>>> from pymafia.datatypes import Location

>>> 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 their [KoLmafia proxy record](https://wiki.kolmafia.us/index.php/Proxy_Records) equivalent.

```python
>>> from pymafia.datatypes import Familiar, Item

>>> Item("big rock").tradeable
True

>>> Familiar("God Lobster").hatchling
Item("God Lobster Egg")
```

Each datatype also has an `all()` class method that returns every non-none instance of that type.

```python
>>> from pymafia.datatypes import Stat

>>> Stat.all()
[Stat("Muscle"), Stat("Mysticality"), Stat("Moxie")]
```

Many datatypes contain predefined class instances as class variables for convenient reference. Notably, all datatypes define a `NONE` class variable.

```python
>>> Coinmaster.NONE
Coinmaster('none')

>>> Slot.HAT
Slot('hat')
```

## Contributing
To contribute to *pymafia*, you will need to set up a development environment using the following steps:
1. Install [poetry](https://python-poetry.org/)
2. Clone this repository
3. Run `poetry install` inside the cloned repository


## Acknowledgements

This project was inspired by Samuel Gaus's [frattlesnake](https://github.com/gausie/frattlesnake) and tadpoleloop's [pymafia](https://github.com/tadpoleloop/pymafia) repositories.
