Skip to content

Feat: add python sdk for Agones game server#4496

Merged
markmandel merged 20 commits intoagones-dev:mainfrom
hiromesh:feature/python-sdk
Apr 20, 2026
Merged

Feat: add python sdk for Agones game server#4496
markmandel merged 20 commits intoagones-dev:mainfrom
hiromesh:feature/python-sdk

Conversation

@hiromesh
Copy link
Copy Markdown
Contributor

@hiromesh hiromesh commented Apr 1, 2026

What type of PR is this?

/kind feature

What this PR does / Why we need it:

Adds a Python SDK for the Agones game server platform, providing a gRPC client for communicating with the Agones sidecar.

The SDK follows the same architecture and API patterns as the existing Go, Rust, and Node.js SDKs:

  • Core SDK: GameServer lifecycle management (Ready, Allocate, Shutdown, Reserve, Health, GetGameServer, WatchGameServer, SetLabel, SetAnnotation)
  • Alpha SDK: Player tracking (PlayerConnect, PlayerDisconnect, capacity/count management)
  • Beta SDK: Counters and Lists (get/set/increment/decrement counters, get/set/append/delete lists)

Commits:

  1. feat: add initial Python SDK for Agones game server
    • agones/sdk.py, agones/alpha.py, agones/beta.py — SDK implementation
    • agones/_generated/ — generated gRPC/protobuf code
    • generate.sh — proto code generation script (strips HTTP/swagger annotations)
    • pyproject.toml — package configuration
    • tests/test_sdk.py, tests/test_alpha.py, tests/test_beta.py — 37 unit tests
  2. docs: add Python Client SDK documentation and update README
    • site/content/en/docs/Guides/Client SDKs/python.md — full SDK documentation page
    • site/content/en/docs/Guides/Client SDKs/_index.md — added Python to SDK index
    • sdks/README.md — added Python entry
    • sdks/python/README.md — simplified to point to site docs
  3. feat: add Python SDK Dockerfile and scripts
    • build/build-sdk-images/python/Dockerfile — Docker build image
    • build/build-sdk-images/python/gen.sh — code generation entrypoint
    • build/build-sdk-images/python/test.sh — test runner entrypoint
    • build/includes/sdk.mk — added Python targets and conformance test
    • build/scripts/sdk-update-version/main.go — added pyproject.toml to version update list

Testing:

$ pytest tests/ -v
37 passed in 0.19s

All tests use unittest.mock.MagicMock to mock gRPC stubs (same approach as Go's sdkMock and Node.js's spyOn).

Which issue(s) this PR fixes:

None — new feature.

Special notes for your reviewer:

  • The generated gRPC code (agones/_generated/) is checked in, same approach as the Node.js SDK
  • generate.sh strips HTTP/swagger annotations from proto files before compilation to avoid unnecessary runtime dependencies
  • Conformance test port allocation: GRPC 9006 / HTTP 9106 (no conflict with existing SDKs)

hiromesh added 3 commits April 1, 2026 14:57
- Introduced core SDK functionality for managing GameServer lifecycle, including methods for connecting, marking readiness, and handling player connections.
- Implemented Alpha and Beta features for player tracking and counters/lists management.
- Added gRPC code generation script and necessary configuration files.
- Included README documentation for installation and usage instructions.
- Created .gitignore to exclude unnecessary files from version control.

Signed-off-by: hiromesh <417969567@qq.com>
- Added Python Client SDK documentation with installation and usage instructions.
- Updated README to include a link to the new Python Client SDK.
- Enhanced the main SDK documentation index to reference the Python SDK.

Signed-off-by: hiromesh <417969567@qq.com>
- Introduced Dockerfile for building Python SDK images, including installation of Python and necessary packages.
- Added code generation script (gen.sh) for setting up a Python virtual environment and installing grpcio-tools.
- Included test script (test.sh) for running pytest with required dependencies.
- Updated Makefile to support Python SDK commands for generation and conformance testing.

Signed-off-by: hiromesh <417969567@qq.com>
@github-actions github-actions Bot added kind/feature New features for Agones size/XL labels Apr 1, 2026
@github-actions
Copy link
Copy Markdown

github-actions Bot commented Apr 1, 2026

This PR exceeds the recommended size of 1000 lines. Please make sure you are NOT addressing multiple issues with one PR. Note this PR might be rejected due to its size.

Copy link
Copy Markdown
Member

@markmandel markmandel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a huge PR 😄 so tough to review - but let's see if it passes CI at least!

Comment thread build/build-sdk-images/python/Dockerfile Outdated
@markmandel
Copy link
Copy Markdown
Member

/gcbrun

@agones-bot
Copy link
Copy Markdown
Collaborator

Build Failed 😭

Build Id: 4cc02a9e-8564-4474-9261-5fdda1e658b3

Status: FAILURE

To get permission to view the Cloud Build view, join the agones-discuss Google Group.

- Replaced sed commands with a Python script to modify import statements for relative imports in generated gRPC files.
- Removed obsolete license classifier from pyproject.toml.

Signed-off-by: hiromesh <417969567@qq.com>
@github-actions
Copy link
Copy Markdown

github-actions Bot commented Apr 2, 2026

This PR exceeds the recommended size of 1000 lines. Please make sure you are NOT addressing multiple issues with one PR. Note this PR might be rejected due to its size.

@github-actions
Copy link
Copy Markdown

github-actions Bot commented Apr 2, 2026

This PR exceeds the recommended size of 1000 lines. Please make sure you are NOT addressing multiple issues with one PR. Note this PR might be rejected due to its size.

@hiromesh
Copy link
Copy Markdown
Contributor Author

hiromesh commented Apr 2, 2026

/gcbrun

@hiromesh
Copy link
Copy Markdown
Contributor Author

hiromesh commented Apr 2, 2026

/gcbrun

found the issue: generate.sh was using sed -i '' (macos-only syntax) which fails on linux.
fixed by replacing with a portable python snippet.

@markmandel
Copy link
Copy Markdown
Member

/gcbrun

@agones-bot
Copy link
Copy Markdown
Collaborator

Build Failed 😭

Build Id: c8baa8f7-c622-4b89-9105-9eee017856f7

Status: FAILURE

To get permission to view the Cloud Build view, join the agones-discuss Google Group.

- Introduced a new test script (sdktest.sh) for setting up a Python virtual environment and running the Agones SDK client.
- Added a comprehensive Python client implementation (testSDKClient.py) for managing player connections, counters, and lists within the Agones game server.

Signed-off-by: hiromesh <417969567@qq.com>
@github-actions
Copy link
Copy Markdown

github-actions Bot commented Apr 3, 2026

This PR exceeds the recommended size of 1000 lines. Please make sure you are NOT addressing multiple issues with one PR. Note this PR might be rejected due to its size.

@hiromesh
Copy link
Copy Markdown
Contributor Author

hiromesh commented Apr 3, 2026

/gcbrun

thanks for triggering the build — really helpful!

found the issue: the missing sdktest.sh + conformance test client which the sdk conformance step requires.

fix is pushed : )

@markmandel
Copy link
Copy Markdown
Member

/gcbrun

@agones-bot
Copy link
Copy Markdown
Collaborator

Build Failed 😭

Build Id: 6a25bccc-6ded-47ed-a369-a62872e6bdd6

Status: FAILURE

To get permission to view the Cloud Build view, join the agones-discuss Google Group.

Comment thread sdks/python/generate.sh Outdated
Comment thread sdks/python/pyproject.toml Outdated
Comment thread sdks/python/pyproject.toml Outdated
Comment thread sdks/python/pyproject.toml
Comment thread sdks/python/pyproject.toml
Comment thread sdks/python/agones/sdk.py
Comment thread test/sdk/python/testSDKClient.py
- Updated the game server callback to ensure that the annotation is set only once by introducing a flag.
- This change prevents redundant calls to `sdk.set_annotation` during the game server event handling.

Signed-off-by: hiromesh <417969567@qq.com>
@agones-bot
Copy link
Copy Markdown
Collaborator

Build Succeeded 🥳

Build Id: f69043b8-7554-4441-b799-bc44d52fd26e

The following development artifacts have been built, and will exist for the next 30 days:

A preview of the website (the last 30 builds are retained):

To install this version:

git fetch https://github.com/googleforgames/agones.git pull/4496/head:pr_4496 && git checkout pr_4496
helm install agones ./install/helm/agones --namespace agones-system --set agones.image.registry=us-docker.pkg.dev/agones-images/ci --set agones.image.tag=1.58.0-dev-d056ef0

@hiromesh
Copy link
Copy Markdown
Contributor Author

Build Succeeded 🥳

Build Id: f69043b8-7554-4441-b799-bc44d52fd26e

The following development artifacts have been built, and will exist for the next 30 days:

A preview of the website (the last 30 builds are retained):

To install this version:

git fetch https://github.com/googleforgames/agones.git pull/4496/head:pr_4496 && git checkout pr_4496
helm install agones ./install/helm/agones --namespace agones-system --set agones.image.registry=us-docker.pkg.dev/agones-images/ci --set agones.image.tag=1.58.0-dev-d056ef0

finally, all passed 😭

Copy link
Copy Markdown
Member

@markmandel markmandel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice work!

We finally worked out what the Apache header needs to be:
#4514

So can we switch that over too please?

Comment thread site/content/en/docs/Guides/Client SDKs/python.md Outdated
Comment thread site/content/en/docs/Guides/Client SDKs/python.md Outdated
Comment thread site/content/en/docs/Guides/Client SDKs/python.md
- Changed copyright attribution from "Google LLC" to "Contributors to Agones a Series of LF Projects, LLC" across multiple Python scripts and SCSS files to reflect the correct ownership.

Signed-off-by: hiromesh <417969567@qq.com>
@github-actions
Copy link
Copy Markdown

This PR exceeds the recommended size of 1000 lines. Please make sure you are NOT addressing multiple issues with one PR. Note this PR might be rejected due to its size.

…ructions

- Added a publish date to the Python Game Server Client SDK documentation.
- Simplified the installation instructions by removing the code blocks and providing a direct link to install from source on GitHub.

Signed-off-by: hiromesh <417969567@qq.com>
@github-actions
Copy link
Copy Markdown

This PR exceeds the recommended size of 1000 lines. Please make sure you are NOT addressing multiple issues with one PR. Note this PR might be rejected due to its size.

@hiromesh
Copy link
Copy Markdown
Contributor Author

Nice work!

We finally worked out what the Apache header needs to be: #4514

So can we switch that over too please?

done, updated to the new header.

@github-actions
Copy link
Copy Markdown

This PR exceeds the recommended size of 1000 lines. Please make sure you are NOT addressing multiple issues with one PR. Note this PR might be rejected due to its size.

Copy link
Copy Markdown
Member

@markmandel markmandel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good other than that small thing. @galalmounir you were looking at this previously -- anything else you'd like to check in your review, or are you happy with this?

Comment thread sdks/python/agones/_generated/alpha/alpha_pb2.py
@markmandel
Copy link
Copy Markdown
Member

/gcbrun

@agones-bot
Copy link
Copy Markdown
Collaborator

Build Failed 😭

Build Id: 6b7ff78d-a9af-4858-bb54-9c98080be38d

Status: FAILURE

To get permission to view the Cloud Build view, join the agones-discuss Google Group.

@markmandel
Copy link
Copy Markdown
Member

Step #4 - "cpp-sdk-conformance-restore-cache": Error response from daemon: manifest for us-docker.pkg.dev/agones-images/ci/restore_cache:latest not found: manifest unknown: Failed to fetch "latest"
Step #2 - "htmltest-restore-cache": Using default tag: latest
Step #2 - "htmltest-restore-cache": Error response from daemon: manifest for us-docker.pkg.dev/agones-images/ci/restore_cache:latest not found: manifest unknown: Failed to fetch "latest"
Step #5 - "rust-sdk-build-restore-cache": Using default tag: latest
Step #5 - "rust-sdk-build-restore-cache": Error response from daemon: manifest for us-docker.pkg.dev/agones-images/ci/restore_cache:latest not found: manifest unknown: Failed to fetch "latest"
ERROR: failed to pull because we ran out of retries.
ERROR
ERROR: failed to pull because we ran out of retries.
ERROR: build step 5 "us-docker.pkg.dev/agones-images/ci/restore_cache" failed: error pulling build step 5 "us-docker.pkg.dev/agones-images/ci/restore_cache": retry budget exhausted (10 attempts): step exited with non-zero status: 1
ERROR: failed to pull because we ran out of retries.
ERROR: failed to pull because we ran out of retries.

ruh roh

@markmandel
Copy link
Copy Markdown
Member

That's no on you though

- Introduced a license header to all generated Python files in the SDK to ensure proper attribution and compliance with the Apache License, Version 2.0.
- Updated the `generate.sh` script to automatically prepend the license header to newly generated files.

Signed-off-by: hiromesh <417969567@qq.com>
@github-actions
Copy link
Copy Markdown

This PR exceeds the recommended size of 1000 lines. Please make sure you are NOT addressing multiple issues with one PR. Note this PR might be rejected due to its size.

Copy link
Copy Markdown
Contributor

@galalmounir galalmounir left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! 🔥

Since we're going to do the pip workflow in a separate PR, we'll need an issue created for it so we dont lose track

@hiromesh
Copy link
Copy Markdown
Contributor Author

LGTM! 🔥

Since we're going to do the pip workflow in a separate PR, we'll need an issue created for it so we dont lose track

done #4524

@hiromesh
Copy link
Copy Markdown
Contributor Author

/gcbrun

@markmandel
Copy link
Copy Markdown
Member

/gcbrun

Should work now. Things broke.

Also because security, only approvers or releasers can kick off CI builds.

@markmandel markmandel enabled auto-merge (squash) April 20, 2026 20:56
@agones-bot
Copy link
Copy Markdown
Collaborator

Build Succeeded 🥳

Build Id: 508d2e3c-085f-4e06-8bb6-3f57cc5e7b68

The following development artifacts have been built, and will exist for the next 30 days:

A preview of the website (the last 30 builds are retained):

To install this version:

git fetch https://github.com/googleforgames/agones.git pull/4496/head:pr_4496 && git checkout pr_4496
helm install agones ./install/helm/agones --namespace agones-system --set agones.image.registry=us-docker.pkg.dev/agones-images/ci --set agones.image.tag=1.58.0-dev-4d84b20

@markmandel markmandel merged commit 9e03474 into agones-dev:main Apr 20, 2026
4 checks passed
lazy-slackoth pushed a commit to lazy-slackoth/agones that referenced this pull request Apr 22, 2026
* feat: add initial Python SDK for Agones game server

- Introduced core SDK functionality for managing GameServer lifecycle, including methods for connecting, marking readiness, and handling player connections.
- Implemented Alpha and Beta features for player tracking and counters/lists management.
- Added gRPC code generation script and necessary configuration files.
- Included README documentation for installation and usage instructions.
- Created .gitignore to exclude unnecessary files from version control.

Signed-off-by: hiromesh <417969567@qq.com>

* docs: add Python Client SDK documentation and update README

- Added Python Client SDK documentation with installation and usage instructions.
- Updated README to include a link to the new Python Client SDK.
- Enhanced the main SDK documentation index to reference the Python SDK.

Signed-off-by: hiromesh <417969567@qq.com>

* feat: add Python SDK Dockerfile and scripts

- Introduced Dockerfile for building Python SDK images, including installation of Python and necessary packages.
- Added code generation script (gen.sh) for setting up a Python virtual environment and installing grpcio-tools.
- Included test script (test.sh) for running pytest with required dependencies.
- Updated Makefile to support Python SDK commands for generation and conformance testing.

Signed-off-by: hiromesh <417969567@qq.com>

* refactor: update import statements in Python SDK generation script

- Replaced sed commands with a Python script to modify import statements for relative imports in generated gRPC files.
- Removed obsolete license classifier from pyproject.toml.

Signed-off-by: hiromesh <417969567@qq.com>

* feat: add Python SDK test script and client implementation

- Introduced a new test script (sdktest.sh) for setting up a Python virtual environment and running the Agones SDK client.
- Added a comprehensive Python client implementation (testSDKClient.py) for managing player connections, counters, and lists within the Agones game server.

Signed-off-by: hiromesh <417969567@qq.com>

* fix: prevent multiple annotations in Python SDK game server callback

- Updated the game server callback to ensure that the annotation is set only once by introducing a flag.
- This change prevents redundant calls to `sdk.set_annotation` during the game server event handling.

Signed-off-by: hiromesh <417969567@qq.com>

* refactor: update Google APIs directory in Python SDK generation script

- Changed the path for the Google APIs proto definitions to use the canonical location from the repo root instead of the Rust SDK vendored version.
- This update simplifies the generation process and ensures consistency with the latest proto definitions.

Signed-off-by: hiromesh <417969567@qq.com>

* fix: update repository URLs in Python SDK configuration

- Changed the repository and issues URLs in pyproject.toml to reflect the new Agones organization on GitHub.
- This update ensures that users are directed to the correct resources for the Agones project.

Signed-off-by: hiromesh <417969567@qq.com>

* fix: update dependencies in Python SDK configuration and enhance game server watching

- Updated grpcio and protobuf dependencies to specific versions for improved compatibility.
- Enhanced the watch_game_server method to include error handling and retry logic, ensuring more robust operation during GameServer updates.

Signed-off-by: hiromesh <417969567@qq.com>

* fix: improve game server UID handling in Python SDK client

- Replaced the single-use flag with a threading event to manage the game server UID retrieval more effectively.
- Updated the annotation setting logic to ensure it occurs after the UID is successfully obtained, enhancing the reliability of the operation.

Signed-off-by: hiromesh <417969567@qq.com>

* fix: enhance game server watching with blocking stream

- Introduced a blocking stream for the WatchGameServer method to simulate real-time updates.
- This change allows the test to handle game server state changes more effectively, improving the reliability of the test suite.

Signed-off-by: hiromesh <417969567@qq.com>

* fix: improve health ping handling in AgonesSDK

- Refactored the health ping method to run the health stream in a separate thread, allowing for non-blocking operation.
- Added error logging to capture any exceptions that occur during the health stream, enhancing the robustness of the health check process.

Signed-off-by: hiromesh <417969567@qq.com>

* chore: update copyright notices in Python and SCSS files

- Changed copyright attribution from "Google LLC" to "Contributors to Agones a Series of LF Projects, LLC" across multiple Python scripts and SCSS files to reflect the correct ownership.

Signed-off-by: hiromesh <417969567@qq.com>

* docs: update Python SDK guide with publish date and installation instructions

- Added a publish date to the Python Game Server Client SDK documentation.
- Simplified the installation instructions by removing the code blocks and providing a direct link to install from source on GitHub.

Signed-off-by: hiromesh <417969567@qq.com>

* feat: add license header to generated Python files

- Introduced a license header to all generated Python files in the SDK to ensure proper attribution and compliance with the Apache License, Version 2.0.
- Updated the `generate.sh` script to automatically prepend the license header to newly generated files.

Signed-off-by: hiromesh <417969567@qq.com>

---------

Signed-off-by: hiromesh <417969567@qq.com>
Co-authored-by: Mark Mandel <mark@compoundtheory.com>
Signed-off-by: Alexander Taran <a.taran@strikerz.inc>
lazy-slackoth pushed a commit to lazy-slackoth/agones that referenced this pull request Apr 22, 2026
* feat: add initial Python SDK for Agones game server

- Introduced core SDK functionality for managing GameServer lifecycle, including methods for connecting, marking readiness, and handling player connections.
- Implemented Alpha and Beta features for player tracking and counters/lists management.
- Added gRPC code generation script and necessary configuration files.
- Included README documentation for installation and usage instructions.
- Created .gitignore to exclude unnecessary files from version control.

Signed-off-by: hiromesh <417969567@qq.com>

* docs: add Python Client SDK documentation and update README

- Added Python Client SDK documentation with installation and usage instructions.
- Updated README to include a link to the new Python Client SDK.
- Enhanced the main SDK documentation index to reference the Python SDK.

Signed-off-by: hiromesh <417969567@qq.com>

* feat: add Python SDK Dockerfile and scripts

- Introduced Dockerfile for building Python SDK images, including installation of Python and necessary packages.
- Added code generation script (gen.sh) for setting up a Python virtual environment and installing grpcio-tools.
- Included test script (test.sh) for running pytest with required dependencies.
- Updated Makefile to support Python SDK commands for generation and conformance testing.

Signed-off-by: hiromesh <417969567@qq.com>

* refactor: update import statements in Python SDK generation script

- Replaced sed commands with a Python script to modify import statements for relative imports in generated gRPC files.
- Removed obsolete license classifier from pyproject.toml.

Signed-off-by: hiromesh <417969567@qq.com>

* feat: add Python SDK test script and client implementation

- Introduced a new test script (sdktest.sh) for setting up a Python virtual environment and running the Agones SDK client.
- Added a comprehensive Python client implementation (testSDKClient.py) for managing player connections, counters, and lists within the Agones game server.

Signed-off-by: hiromesh <417969567@qq.com>

* fix: prevent multiple annotations in Python SDK game server callback

- Updated the game server callback to ensure that the annotation is set only once by introducing a flag.
- This change prevents redundant calls to `sdk.set_annotation` during the game server event handling.

Signed-off-by: hiromesh <417969567@qq.com>

* refactor: update Google APIs directory in Python SDK generation script

- Changed the path for the Google APIs proto definitions to use the canonical location from the repo root instead of the Rust SDK vendored version.
- This update simplifies the generation process and ensures consistency with the latest proto definitions.

Signed-off-by: hiromesh <417969567@qq.com>

* fix: update repository URLs in Python SDK configuration

- Changed the repository and issues URLs in pyproject.toml to reflect the new Agones organization on GitHub.
- This update ensures that users are directed to the correct resources for the Agones project.

Signed-off-by: hiromesh <417969567@qq.com>

* fix: update dependencies in Python SDK configuration and enhance game server watching

- Updated grpcio and protobuf dependencies to specific versions for improved compatibility.
- Enhanced the watch_game_server method to include error handling and retry logic, ensuring more robust operation during GameServer updates.

Signed-off-by: hiromesh <417969567@qq.com>

* fix: improve game server UID handling in Python SDK client

- Replaced the single-use flag with a threading event to manage the game server UID retrieval more effectively.
- Updated the annotation setting logic to ensure it occurs after the UID is successfully obtained, enhancing the reliability of the operation.

Signed-off-by: hiromesh <417969567@qq.com>

* fix: enhance game server watching with blocking stream

- Introduced a blocking stream for the WatchGameServer method to simulate real-time updates.
- This change allows the test to handle game server state changes more effectively, improving the reliability of the test suite.

Signed-off-by: hiromesh <417969567@qq.com>

* fix: improve health ping handling in AgonesSDK

- Refactored the health ping method to run the health stream in a separate thread, allowing for non-blocking operation.
- Added error logging to capture any exceptions that occur during the health stream, enhancing the robustness of the health check process.

Signed-off-by: hiromesh <417969567@qq.com>

* chore: update copyright notices in Python and SCSS files

- Changed copyright attribution from "Google LLC" to "Contributors to Agones a Series of LF Projects, LLC" across multiple Python scripts and SCSS files to reflect the correct ownership.

Signed-off-by: hiromesh <417969567@qq.com>

* docs: update Python SDK guide with publish date and installation instructions

- Added a publish date to the Python Game Server Client SDK documentation.
- Simplified the installation instructions by removing the code blocks and providing a direct link to install from source on GitHub.

Signed-off-by: hiromesh <417969567@qq.com>

* feat: add license header to generated Python files

- Introduced a license header to all generated Python files in the SDK to ensure proper attribution and compliance with the Apache License, Version 2.0.
- Updated the `generate.sh` script to automatically prepend the license header to newly generated files.

Signed-off-by: hiromesh <417969567@qq.com>

---------

Signed-off-by: hiromesh <417969567@qq.com>
Co-authored-by: Mark Mandel <mark@compoundtheory.com>
Signed-off-by: Alexander Taran <a.taran@strikerz.inc>
lazy-slackoth pushed a commit to lazy-slackoth/agones that referenced this pull request Apr 22, 2026
* feat: add initial Python SDK for Agones game server

- Introduced core SDK functionality for managing GameServer lifecycle, including methods for connecting, marking readiness, and handling player connections.
- Implemented Alpha and Beta features for player tracking and counters/lists management.
- Added gRPC code generation script and necessary configuration files.
- Included README documentation for installation and usage instructions.
- Created .gitignore to exclude unnecessary files from version control.

Signed-off-by: hiromesh <417969567@qq.com>

* docs: add Python Client SDK documentation and update README

- Added Python Client SDK documentation with installation and usage instructions.
- Updated README to include a link to the new Python Client SDK.
- Enhanced the main SDK documentation index to reference the Python SDK.

Signed-off-by: hiromesh <417969567@qq.com>

* feat: add Python SDK Dockerfile and scripts

- Introduced Dockerfile for building Python SDK images, including installation of Python and necessary packages.
- Added code generation script (gen.sh) for setting up a Python virtual environment and installing grpcio-tools.
- Included test script (test.sh) for running pytest with required dependencies.
- Updated Makefile to support Python SDK commands for generation and conformance testing.

Signed-off-by: hiromesh <417969567@qq.com>

* refactor: update import statements in Python SDK generation script

- Replaced sed commands with a Python script to modify import statements for relative imports in generated gRPC files.
- Removed obsolete license classifier from pyproject.toml.

Signed-off-by: hiromesh <417969567@qq.com>

* feat: add Python SDK test script and client implementation

- Introduced a new test script (sdktest.sh) for setting up a Python virtual environment and running the Agones SDK client.
- Added a comprehensive Python client implementation (testSDKClient.py) for managing player connections, counters, and lists within the Agones game server.

Signed-off-by: hiromesh <417969567@qq.com>

* fix: prevent multiple annotations in Python SDK game server callback

- Updated the game server callback to ensure that the annotation is set only once by introducing a flag.
- This change prevents redundant calls to `sdk.set_annotation` during the game server event handling.

Signed-off-by: hiromesh <417969567@qq.com>

* refactor: update Google APIs directory in Python SDK generation script

- Changed the path for the Google APIs proto definitions to use the canonical location from the repo root instead of the Rust SDK vendored version.
- This update simplifies the generation process and ensures consistency with the latest proto definitions.

Signed-off-by: hiromesh <417969567@qq.com>

* fix: update repository URLs in Python SDK configuration

- Changed the repository and issues URLs in pyproject.toml to reflect the new Agones organization on GitHub.
- This update ensures that users are directed to the correct resources for the Agones project.

Signed-off-by: hiromesh <417969567@qq.com>

* fix: update dependencies in Python SDK configuration and enhance game server watching

- Updated grpcio and protobuf dependencies to specific versions for improved compatibility.
- Enhanced the watch_game_server method to include error handling and retry logic, ensuring more robust operation during GameServer updates.

Signed-off-by: hiromesh <417969567@qq.com>

* fix: improve game server UID handling in Python SDK client

- Replaced the single-use flag with a threading event to manage the game server UID retrieval more effectively.
- Updated the annotation setting logic to ensure it occurs after the UID is successfully obtained, enhancing the reliability of the operation.

Signed-off-by: hiromesh <417969567@qq.com>

* fix: enhance game server watching with blocking stream

- Introduced a blocking stream for the WatchGameServer method to simulate real-time updates.
- This change allows the test to handle game server state changes more effectively, improving the reliability of the test suite.

Signed-off-by: hiromesh <417969567@qq.com>

* fix: improve health ping handling in AgonesSDK

- Refactored the health ping method to run the health stream in a separate thread, allowing for non-blocking operation.
- Added error logging to capture any exceptions that occur during the health stream, enhancing the robustness of the health check process.

Signed-off-by: hiromesh <417969567@qq.com>

* chore: update copyright notices in Python and SCSS files

- Changed copyright attribution from "Google LLC" to "Contributors to Agones a Series of LF Projects, LLC" across multiple Python scripts and SCSS files to reflect the correct ownership.

Signed-off-by: hiromesh <417969567@qq.com>

* docs: update Python SDK guide with publish date and installation instructions

- Added a publish date to the Python Game Server Client SDK documentation.
- Simplified the installation instructions by removing the code blocks and providing a direct link to install from source on GitHub.

Signed-off-by: hiromesh <417969567@qq.com>

* feat: add license header to generated Python files

- Introduced a license header to all generated Python files in the SDK to ensure proper attribution and compliance with the Apache License, Version 2.0.
- Updated the `generate.sh` script to automatically prepend the license header to newly generated files.

Signed-off-by: hiromesh <417969567@qq.com>

---------

Signed-off-by: hiromesh <417969567@qq.com>
Co-authored-by: Mark Mandel <mark@compoundtheory.com>
Signed-off-by: Alexander Taran <a.taran@strikerz.inc>
lacroixthomas pushed a commit to lacroixthomas/agones that referenced this pull request Apr 22, 2026
* feat: add initial Python SDK for Agones game server

- Introduced core SDK functionality for managing GameServer lifecycle, including methods for connecting, marking readiness, and handling player connections.
- Implemented Alpha and Beta features for player tracking and counters/lists management.
- Added gRPC code generation script and necessary configuration files.
- Included README documentation for installation and usage instructions.
- Created .gitignore to exclude unnecessary files from version control.

Signed-off-by: hiromesh <417969567@qq.com>

* docs: add Python Client SDK documentation and update README

- Added Python Client SDK documentation with installation and usage instructions.
- Updated README to include a link to the new Python Client SDK.
- Enhanced the main SDK documentation index to reference the Python SDK.

Signed-off-by: hiromesh <417969567@qq.com>

* feat: add Python SDK Dockerfile and scripts

- Introduced Dockerfile for building Python SDK images, including installation of Python and necessary packages.
- Added code generation script (gen.sh) for setting up a Python virtual environment and installing grpcio-tools.
- Included test script (test.sh) for running pytest with required dependencies.
- Updated Makefile to support Python SDK commands for generation and conformance testing.

Signed-off-by: hiromesh <417969567@qq.com>

* refactor: update import statements in Python SDK generation script

- Replaced sed commands with a Python script to modify import statements for relative imports in generated gRPC files.
- Removed obsolete license classifier from pyproject.toml.

Signed-off-by: hiromesh <417969567@qq.com>

* feat: add Python SDK test script and client implementation

- Introduced a new test script (sdktest.sh) for setting up a Python virtual environment and running the Agones SDK client.
- Added a comprehensive Python client implementation (testSDKClient.py) for managing player connections, counters, and lists within the Agones game server.

Signed-off-by: hiromesh <417969567@qq.com>

* fix: prevent multiple annotations in Python SDK game server callback

- Updated the game server callback to ensure that the annotation is set only once by introducing a flag.
- This change prevents redundant calls to `sdk.set_annotation` during the game server event handling.

Signed-off-by: hiromesh <417969567@qq.com>

* refactor: update Google APIs directory in Python SDK generation script

- Changed the path for the Google APIs proto definitions to use the canonical location from the repo root instead of the Rust SDK vendored version.
- This update simplifies the generation process and ensures consistency with the latest proto definitions.

Signed-off-by: hiromesh <417969567@qq.com>

* fix: update repository URLs in Python SDK configuration

- Changed the repository and issues URLs in pyproject.toml to reflect the new Agones organization on GitHub.
- This update ensures that users are directed to the correct resources for the Agones project.

Signed-off-by: hiromesh <417969567@qq.com>

* fix: update dependencies in Python SDK configuration and enhance game server watching

- Updated grpcio and protobuf dependencies to specific versions for improved compatibility.
- Enhanced the watch_game_server method to include error handling and retry logic, ensuring more robust operation during GameServer updates.

Signed-off-by: hiromesh <417969567@qq.com>

* fix: improve game server UID handling in Python SDK client

- Replaced the single-use flag with a threading event to manage the game server UID retrieval more effectively.
- Updated the annotation setting logic to ensure it occurs after the UID is successfully obtained, enhancing the reliability of the operation.

Signed-off-by: hiromesh <417969567@qq.com>

* fix: enhance game server watching with blocking stream

- Introduced a blocking stream for the WatchGameServer method to simulate real-time updates.
- This change allows the test to handle game server state changes more effectively, improving the reliability of the test suite.

Signed-off-by: hiromesh <417969567@qq.com>

* fix: improve health ping handling in AgonesSDK

- Refactored the health ping method to run the health stream in a separate thread, allowing for non-blocking operation.
- Added error logging to capture any exceptions that occur during the health stream, enhancing the robustness of the health check process.

Signed-off-by: hiromesh <417969567@qq.com>

* chore: update copyright notices in Python and SCSS files

- Changed copyright attribution from "Google LLC" to "Contributors to Agones a Series of LF Projects, LLC" across multiple Python scripts and SCSS files to reflect the correct ownership.

Signed-off-by: hiromesh <417969567@qq.com>

* docs: update Python SDK guide with publish date and installation instructions

- Added a publish date to the Python Game Server Client SDK documentation.
- Simplified the installation instructions by removing the code blocks and providing a direct link to install from source on GitHub.

Signed-off-by: hiromesh <417969567@qq.com>

* feat: add license header to generated Python files

- Introduced a license header to all generated Python files in the SDK to ensure proper attribution and compliance with the Apache License, Version 2.0.
- Updated the `generate.sh` script to automatically prepend the license header to newly generated files.

Signed-off-by: hiromesh <417969567@qq.com>

---------

Signed-off-by: hiromesh <417969567@qq.com>
Co-authored-by: Mark Mandel <mark@compoundtheory.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

kind/feature New features for Agones size/XL

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants