Skip to content

Using the client

The Client class is used to interact with the WOM API. You use the client to make requests via its difference service properties.

Services available on the client include:

Instantiating the client

import wom

client = wom.Client(
    "api_abc123",  # The wom api key to use.
    user_agent="@jonxslays",
    api_base_url="https://api.wiseoldman.net/v2",
)

Api base url and user agent are both optional, but user agent is highly encouraged. The client defaults to using the production wom api url. If you are running a local instance of the wom api you can set the base url to your instance.

Info

You only need a single instance of the Client to make requests to WOM. If you feel like you need multiple Client instances you should reconsider the architecture of your application, and how you can reuse your existing Client resource. Some niche scenarios could warrant more than one Client, but these use cases aren't common for most users.

Handling client resources

The wom Client uses an aiohttp.ClientSession under the hood, so it is important that you call Client.start and Client.close appropriately.

# ...continued from above

await client.start()

# Make requests here...

await client.close()

You will receive errors/warnings if you do not properly start the client before using it, or close it before your program terminates.

Example client usage

import asyncio

import wom


async def main() -> None:
    # Instantiate the client
    client = wom.Client()

    # Start the client
    await client.start()

    # You can also alter some client properties after instantiation
    client.set_api_base_url("https://api.wiseoldman.net/v2")
    client.set_api_key("my-new-api-key")
    client.set_user_agent("@jonxslays")

    # Oops that api key was bogus, lets remove it
    client.unset_api_key()

    # Make requests with the client
    result = await client.groups.get_details(139)

    if result.is_ok:
        # The result is ok, so we can unwrap here
        details = result.unwrap()
        print(details.group)
        print(details.memberships)
    else:
        # Lets see what went wrong
        print(f"Error: {result.unwrap_err()}")

    # Close the client
    await client.close()


if __name__ == "__main__":
    asyncio.run(main())