Converts the repository into a proper python package

.gitignore

@@ -1,5 +1,13 @@
+# CMake
 Makefile
-py_export
 CMakeFiles
 CMakeCache.txt
+*.cmake
+
+# Python
 __pycache__
+.python-version
+.venv
+*.egg-info/
+uv.lock
+build/

README.md

@@ -1,11 +1,71 @@
-## Python DFHack RPC client  
+# Python DFHack RPC client  
 (originally 'Blendwarf' by Alef - http://www.bay12forums.com/smf/index.php?topic=178089.0)
 
-### Instructions for Linux:  
-(requires packages cmake, python3-protobuf)
+## Usage
 
-Generate python protobuf code:  
-`$ cmake . && make`  
+By default this package includes all of the code necessary to connect to DFHack (version 51.13-r1) through its custom RPC protocal. Use the following steps to test this out.
 
-Test some remote calls:  
-`$ python3 ./blendwarf.py`  
+### Clone dfhack-client-python Repository
+
+```bash
+git clone https://github.com/McArcady/dfhack-client-python.git
+```
+
+### Install dfhack-client-python
+
+```bash
+cd dfhack-client-python
+pip install .
+```
+
+### Run Dwarf Fortress with DFHack
+
+At this point make sure both Dwarf Fortress and DFHack are installed. Open Dwarf Fortress and load into a game (the game can be paused).
+
+### Run the Example Script
+
+```bash
+python ./example/blendwarf.py
+```
+If everything is working and you have successfully connected to your game via RPC, you will see a print out containing the number of units in your currently open game!
+
+## Development
+
+In order to make changes to this package or generate python files for other version of DFHack. Follow the steps below.
+
+### Requirements
+
+- python 3
+- cmake
+- protobuf
+
+### Fetch Protobuf Files (Optional)
+
+If you need to fetch a different version of .proto files, you can run the `./scripts/fetch_proto_files.py` script. You must pass a valid DFHack tag name as an argument.
+```bash
+python ./scripts/fetch_proto_files.py --tag="51.13-r1"
+```
+*This will dump all `.proto` files into the `./proto/51.13-r1/` directory*
+
+### Generate Python Protobuf Code
+
+To generate the necessary python files from the `./proto/<tag>/` directory, run the `./scripts/generate_python.py` script. You must pass the `<tag>` in as an argument
+
+```bash
+python ./scripts/generate_python.py --tag="51.13-r1"
+```
+*This will generate one python file in `./src/dfhack_client_python/py_export/` per .proto file in `./proto/<tag>/` for the provided `<tag>`*
+
+### Install the Package
+
+Now that all the python code is generated, make sure to install the package
+
+```bash
+pip install -e .
+```
+
+### Test Your Changes
+At this point you can run the `./examples/blendwarf.py` script to test your changes. Make sure Dwarf Fortress is running, DFHack is installed, and you are loaded into a game.
+```bash
+python ./examples/blendwarf.py
+```

cmake/CMakeLists.txt

@@ -0,0 +1,26 @@
+cmake_minimum_required(VERSION 3.13)
+project(blendwarf NONE)
+
+# Make version configurable via command line
+option(TAG "DFHack version tag to use (e.g., 51.13-r1)" "51.13-r1")
+
+set(PROTOC-BIN "protoc")
+set(PROTO-DIR "${CMAKE_CURRENT_SOURCE_DIR}/../proto/${TAG}")
+set(PY-DIR "${CMAKE_CURRENT_SOURCE_DIR}/../src/dfhack_client_python/py_export")
+
+# Dynamically find all .proto files in the PROTO-DIR
+file(GLOB PROTO_FILES "${PROTO-DIR}/*.proto")
+
+# Create the protoc command with all found .proto files
+add_custom_command(OUTPUT protos
+  COMMAND ${CMAKE_COMMAND} -E make_directory ${PY-DIR}
+  COMMAND ${CMAKE_COMMAND} -E touch ${PY-DIR}/__init__.py
+  COMMAND "${PROTOC-BIN}"
+  -I${PROTO-DIR}
+  --python_out=${PY-DIR}
+  ${PROTO_FILES}
+)
+
+add_custom_target(DONE ALL
+  DEPENDS protos
+)

examples/blendwarf.py

@@ -0,0 +1,22 @@
+import asyncio
+# Import connection management functions
+from dfhack_client_python.dfhack_remote import remote, connect, close
+# Import protobuf message types
+from dfhack_client_python.py_export.CoreProtocol_pb2 import StringMessage
+from dfhack_client_python.py_export.RemoteFortressReader_pb2 import UnitList
+
+## Declare DFHack exported interfaces
+@remote
+async def GetVersion(output: StringMessage = None): pass
+
+@remote(plugin='RemoteFortressReader')
+async def GetUnitList(output: UnitList = None): pass
+
+# Test
+async def main():
+    await connect()
+    print( "DFHack Version: ", (await GetVersion()).value )
+    print( "Units: ", len((await GetUnitList()).creature_list))
+    await close()
+
+asyncio.run(main())