pss-fleet-data-client 0.6.0

A client for the Pixel Starships Fleet Data API.

Pixel Starships Fleet Data API client

An async client library to access the PSS Fleet Data API. Currently supported API version is 1.5.0.

Built with

• httpx
• pssapi.py
• pydantic V2

✨ Features

• Fully typehinted so your favorite IDE can assist you with code completion.
• Easy access to any instance of a PSS Fleet Data API server.
• Fast setup to get you started quickly.

🔍 Future plans

• Support more Python versions

🚀 Demo

To retrieve the last month's tournament results (a specific Collection):

import asyncio
from datetime import datetime, timezone

from pss_fleet_data import ParameterInterval, PssFleetDataClient, utils

# Create the client, specifying the API server's base URL. If you don't specify a base URL, it defaults to https://fleetdata.dolores2.xyz
client = PssFleetDataClient(base_url="https://fleetdata.dolores2.xyz")

async def print_latest_tournament_results():
    # Get the current time
    now = datetime.now(tz=timezone.utc)

    # Tournament results are collected shortly before the start of a new month.
    # Calculate the most recent start of month relative to now.
    most_recent_timestamp = utils.get_most_recent_timestamp(now, ParameterInterval.MONTHLY)

    # Then get the most recent data collected before the calculated timestamp.
    collection = await client.get_most_recent_collection_by_timestamp(most_recent_timestamp)

    # Work with the Collection.
    print(f"Collection with ID {collection.metadata.collection_id} collected at {collection.metadata.timestamp}.")
    print(f"It has collected {collection.metadata.fleet_count} fleets and {len(collection.users)} players.")

    # You can use the Collection's ID in other methods, too, e.g. get the top 100 players at the end of the month.
    _, top_100_users = await client.get_top_100_users_from_collection(collection.metadata.collection_id)
    print(f"The player ranked 3rd last month was: {top_100_users[2].name}")

    # Or obtain the player stats of the 2nd best player last month over time
    user_history = await client.get_user_history(top_100_users[1].id, interval=ParameterInterval.MONTHLY)
    print(
        "Found %i history entries for player %s from %s to %s",
        len(user_history),
        top_100_users[1].name,
        user_history[0].collection.timestamp.isoformat(),
        user_history[-1].collection.timestamp.isoformat(),
    )

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

The library converts localized datetime objects to UTC or assumes UTC, if now timezone information is given. Any datetime objects returned are in UTC.

⚙️ Installation

Python 3.11 or higher is required

To install the latest version of this library, run the following command:

pip install -U pss-fleet-data-client

🖊️ Contribute

If you ran across a bug or have a feature request, please check if there's already an issue for that and if not, open a new one.

If you want to fix a bug or add a feature, please check out the Contribution Guide.

🆘 Support

If you need help using the library or want to contribute, you can join my support Discord at: discord.gg/kKguSec

🔗 Links

• Documentation (tbd)
• Official Support Discord server
• PSS Fleet Data API
• Buy me a can of cat food
• Or a coffee