Python Client

Gate provides a Python API for integrating with your Python applications. You can use the API to interact with Gate programmatically using either gRPC or HTTP protocols.

Environment Setup

Best DX

We recommend using uv for beginners and experienced developers alike!

uv (Recommended)

# Install uv (on macOS/Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a new virtual environment
uv init

venv

# Create a new virtual environment
python3 -m venv .venv

# Activate the environment (Unix)
source .venv/bin/activate

# Activate the environment (Windows)
.venv\Scripts\activate

poetry

# Install poetry
curl -sSL https://install.python-poetry.org | python3 -

# Create new project
poetry init
poetry shell

pipenv

# Install pipenv
pip install pipenv

# Create environment and activate shell
pipenv install
pipenv shell

Installation

uv (Recommended)

uv add minekube-gate-grpc-python minekube-gate-protocolbuffers-python --index https://buf.build/gen/python

pip

python3 -m pip install minekube-gate-grpc-python minekube-gate-protocolbuffers-python --extra-index-url https://buf.build/gen/python

poetry

poetry add minekube-gate-grpc-python minekube-gate-protocolbuffers-python --source buf.build/gen/python

pipenv

pipenv install minekube-gate-grpc-python minekube-gate-protocolbuffers-python --extra-index-url https://buf.build/gen/python

Usage Example

Here's a basic example of using the Gate Python API to connect to Gate and list servers:

main.py

import grpc
import json
from google.protobuf import json_format
from minekube.gate.v1 import gate_service_pb2 as gatepb
from minekube.gate.v1 import gate_service_pb2_grpc as gateapi


def main():
    # Create a gRPC channel
    channel = grpc.insecure_channel('localhost:8080')

    # Create a stub (client)
    stub = gateapi.GateServiceStub(channel)

    try:
        # List servers
        response = stub.ListServers(gatepb.ListServersRequest())
        # Convert to JSON and print
        json_response = json_format.MessageToDict(response)
        print(json.dumps(json_response, indent=2))

    except grpc.RpcError as e:
        print(f"RPC failed: {e}")

    finally:
        channel.close()


if __name__ == '__main__':
    main()

Running the Example

1. Make sure Gate is running with the API enabled
2. Save one of the example scripts above to main.py
3. Run the script:

uv (Recommended)

uv run main.py
{
  "servers": [
    {
      "name": "server3",
      "address": "localhost:25568"
    },
    {
      "name": "server4",
      "address": "localhost:25569"
    },
    {
      "name": "server1",
      "address": "localhost:25566"
    },
    {
      "name": "server2",
      "address": "localhost:25567"
    }
  ]
}

python

python3 main.py

poetry

poetry run python main.py

pipenv

pipenv run python main.py

Learn More

• uv Documentation - Learn more about the recommended Python package manager
• gRPC Python Documentation - Learn more about using gRPC with Python