Skip to content

Python 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!

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

# Create a new virtual environment
uv init
bash
# Create a new virtual environment
python3 -m venv .venv

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

# Activate the environment (Windows)
.venv\Scripts\activate
bash
# Install poetry
curl -sSL https://install.python-poetry.org | python3 -

# Create new project
poetry init
poetry shell
bash
# Install pipenv
pip install pipenv

# Create environment and activate shell
pipenv install
pipenv shell

Installation

bash
uv add minekube-gate-grpc-python minekube-gate-protocolbuffers-python --index https://buf.build/gen/python
bash
python3 -m pip install minekube-gate-grpc-python minekube-gate-protocolbuffers-python --extra-index-url https://buf.build/gen/python
bash
poetry add minekube-gate-grpc-python minekube-gate-protocolbuffers-python --source buf.build/gen/python
bash
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:

python
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:
bash
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"
    }
  ]
}
bash
python3 main.py
bash
poetry run python main.py
bash
pipenv run python main.py

Learn More

Released under the Apache 2.0 License. (web version: 037ca6cf)