Ogsapi - A Python API Wrapper for OGS

3rd Party Apps for OGS
1

Hey Everyone!

I am at the point where I feel comfortable letting other people look at this API wrapper I am writing for the OGS API. Its still VERY MUCH in the development stages, and absolutely no one should be using it for real projects, yet. That being said, I want to see if anyone here is Pythonically Inclined, and might be able to give some general review of the code, or just give general thoughts.

My goal is to expose as much of both the REST API, and the Realtime API as possible through functions. That way, anyone who wants to create a Python project that hooks into OGS will have a much easier time, and not have to worry about the specific API calls and whatnot.

Here is the Github link
Here is the Gitlab link (This is the one I am actually working through, Github is just because it’s basically a social media platform at this point lol)

I have also already uploaded it to PyPI, so you can just install it with:

python3 -m pip install ogsapi

Let me know your opinions on the current documentation, code format, or anything really. I am going to try and get the rest of the API endpoints implemented as soon as possible.

Disclaimer: I am not a developer by any stretch of the imagination. My code is likely horrendous, slow, terrible, bad, atrocious, and did I mention bad?

12 Likes
2

That’s awesome! I feel like a lot of Python is the language of choice for a lot of folks here (see the Project Euler thread), so this will be very useful - I look forward to trying it out!

Also, yay copyleft!

5 Likes
3

I pretty much exclusively write in Python, so it was the obvious choice for me lol. Hopefully others can eventually get some use out of it.

And always copyleft! :smile:

5 Likes
4

Heyo! Just a small update on this:

Most of the bare minimum game features should be implemented. I just got received moves to pass to the end client via callbacks. That means that I am only missing clock management, sending challenges, and handling the counting phase.

I am still trying to get all the random endpoints on the normal REST API implemented, but I think a good portion of them are accounted for.

After all the functions that handle talking directly to the API are done, I plan to start implementing some helper functions to take care of complicated multi stepped tasks more easily.

Here is the latest release link: 0.3.0 · Dakota Marshall / OGS-Python · GitLab

2 Likes
5

Howdy y’all! Back again with another quick update on this. Added some new features and whatnot

  • Added relevant game data to the OGSGame class
  • Implemented clock handling
  • Implemented handling of undo actions
  • Added asdict() method to OGSGame to get game data as a dict

But I also spent the time going through and documenting the code with docstrings, and setup mkdocks to act as a documentation wiki. You can view that here: https://ogs-python.dakotamarshall.net/

It’s not super polished yet, but it builds the documentation from the code automatically, so it should always be up-to-date (for the most part anyway)

At this point I feel comfortable saying that you could probably start toying around with this if you want, though I want to stress that the code is probably bad, and you still shouldnt rely on this for anything important. That being said, I would love to get some feedback on this if anyone has a chance to use it / wants to contribute to the project! Just let me know.

Here is the release page if you want to have a look: 0.4.1 · Dakota Marshall / OGS-Python · GitLab

1 Like
6

Nice project!

I’m working on something similar, just not on Python, so I gave your code a look to find some inspiration.

I noticed a minor typo on the event ‘undo_canceled’ (OGS uses the British-English spelling), so I took the liberty to send you a merge request with a fix. It’s nothing really, but if it’s OK I could help you on implementing features (callbacks, etc.).

I’m currently focusing on the real-time API, and I have a question: where did you find the events that you listed in your checklist? This doc is fairly bad, and I know a better one exists, but somehow I cannot find it anymore. Hopefully, that’s the one you used and you have a link to share.

1 Like
7

Thanks! I’ll take a look at the MR and merge it when I have some time tomorrow. As for helping, I am welcome to any idea / improvements people may have. I am very much a newbie at programming, so any contributions are very welcome :slight_smile:

I made a post awhile ago asking about contributing to the documentation, and anoek threw me this link. It’s the documentation for their goban client, and in it documents all of the RT API calls it sends and receives. I believe it is completely up to date with at least all the calls goban makes.

8

Ah yes! That’s where I initially heard about it, thanks for helping me find it!

1 Like
9

Heyo! Just another update on this for anyone interested! Been a bit since I’ve been able to work on this, but I had time to sit down and add more of the missing features.

  • Added socket level callbacks for error and notification events
  • Added Game Phase change handler and callback
  • Fixed undo cancelled to be the British canceled. Thank you, @aureo !
  • Implemented proper challenge creation, You can now define the challenge settings, and send it out as an open challenge, or to a specific player.
  • Added realtime API game functions for:
    • pause/resume
    • cancel game
    • cancel / accept undo
    • sending chat

I also refactored the code to be a bit more readable, mainly putting the major classes into their own files since the file was getting well over 1000 lines… :sweat_smile:

Let me know if you get a chance to check it out and have feedback! 0.6.1 · Dakota Marshall / OGS-Python · GitLab

1 Like
10

Not really on topic, but I thought 2 L’s is the British spelling. From M-W:

While both canceled and cancelled are acceptable for the past tense of cancel, the version with one L is more common in American English, while the version with two L’s is more common in British English.

Anyway, awesome to see this project growing! Do you have an (example) application/script for this library?

1 Like
11

Maybe I have em mixed up, but I’ve always spelt cancelled with two L’s, so maybe I’ve just been doing it wrong like my whole life lol :sweat_smile:

As for an example script, I do! It’s not the best, but there is an example.py in the repo that shows a basic class that would use the library. I haven’t made a full fledged example client yet, but that’s something I want to do for sure :slight_smile:

I also have a wiki built at https://ogs-python.dakotamarshall.net/ that has some more instructions, as well as a full library doc built with mkdocstrings!

1 Like
12

Tried to make a small script tonight, but had issues. First of all, here’s the (very minimal) script hello.py:

from ogsapi.client import OGSClient

print("got here")

And here is the error I get:

(.venv) ogscli2 % python3 hello.py  
Traceback (most recent call last):
  File ".../ogscli2/hello.py", line 1, in <module>
    from ogsapi.client import OGSClient
  File ".../ogscli2/.venv/lib/python3.11/site-packages/ogsapi/client.py", line 2, in <module>
    from ogssocket import OGSSocket
ModuleNotFoundError: No module named 'ogssocket'

I went inside site-packages (is that allowed? :sweat_smile:) and replaced from ogssocket with from .ogssocket (relative imports), and then get a different issue:

ImportError: cannot import name 'OGSApiException' from partially initialized module 'ogsapi.client' (most likely due to a circular import) (.../ogscli2/.venv/lib/python3.11/site-packages/ogsapi/client.py)

Would it make sense to:

  • use relative imports, and
  • define OGSApiException in its own file to prevent circular dependencies?

And if not, any ideas what I can do to make this work?

13

Oh man, I thought I had this working, but it looks like I messed something up while testing lol.

Both of those are great suggestions! This is my first time packaging any of my python code, and my first time writing something big enough to justify multiple files, so it seems like I misunderstood a few things about how importing works while working with packages.

I can probably get this updated tomorrow after work!

1 Like
14

I opened a Merge Request with the proposed changes! example.py seems to work again now (with a couple small modifications)

I’m not so familiar with GitLab these days, but I think I remember they support CI/CD stuff. You can probably have a script or some basic unit tests run every time the main branch is updated, and alert you if they failed with exception.

1 Like
15

Thanks for doing that! Had time during lunch to review and merge, now released in: v0.7.0 · Dakota Marshall / OGS-Python · GitLab

I am already using their CI/CD for building the package, deploying to PyPI, and building my documentation, unit tests have been on the list, but now that people besides me are trying to use it, that is what I am implementing tonight lol.

Let me know if you have any questions / issues on using the module! And of course any suggested feedback is more than welcome lol

1 Like
16

Thank you!

Oh cool! The documentation is excellent and very appreciated :grin:

1 Like
17

Hey Everyone! Back with a new update, v1.0.0! It being 1.0 is exaggerated, but with how different logging works now, and the callbacks being reworked, and the Websocket no longer connecting by default, it felt right to bump the major release. For those curious, here are the path notes from the last few versions:

Features

  • Added methods for getting games as a PNG or SGF
  • Added methods for getting list of game reviews for a game
  • The client no longer connects to the Realtime API by default, you must now manually call the socket_connect method to connect. This will make working with just the REST API easier, not having to deal with the Websocket
  • All realtime socket events are now being sent to two different event handlers, instead of one for each event. One for the realtime API in general, and one for each game you are connected to. See the Usage documentation for more details
  • Added methods to OGSClient to manually connect and disconnect to the realtime API
  • Added get_player_games to OGSClient. Gets list of games from a palyer
  • Added loguru as a logging backend
  • Added plenty of debug, info, success, and error logs to make troublehsooting hopefully easier

Fixes

  • Fixed issues causing errors during import
    • Removed circular dependency
    • Moved class imports to local imports vs absolute

Misc

  • Create OGSRestAPI class for handling direct calls to API
  • Create OGSCredentials class for handling the user credentials
  • Move Socket token grabbing to OGSRestAPI
  • Updated documentation to reflect that when using the Websocket, you are responsible for disconnecting from the server via socket_disconnect, otherwise a Keyboard Inturrupt will be required to close out
  • Removed the redundant destructor on OGSClient that disconnected from the websocket, it wasnt working correctly, and now it will be the users responsibility anyway
  • Refactored the OGSGame class to put the game and clock data into their own dataclasses respectively.
  • Updated documentation to reflect logging changes

Check out the release: v1.1.0 · Dakota Marshall / OGS-Python · GitLab
And of course the updated package is on PyPI: ogsapi · PyPI

3 Likes