diff --git a/PLUGINS.md b/PLUGINS.md index df6d011f..c9debd5b 100644 --- a/PLUGINS.md +++ b/PLUGINS.md @@ -970,22 +970,20 @@ def capi_fleetcarrier(data): | :-------- | :--------------: | :------------------------------------------------------------------------------------------------------- | | `data` | `CAPIData` | `/fleetcarrier` API response | -`CAPIData` is a class, which you can `from companion import CAPIDATA`, and is -based on `UserDict`. The actual data from CAPI queries is thus accessible -via python's normal `data['key']` syntax. However, being a class, it can also -have extra properties, such as `source_host`, as shown above. Plugin authors -are free to use *that* property, **but MUST NOT rely on any other extra -properties present in `CAPIData`, they are for internal use only.** -In the `cmdr_data()` callback, the contents of `data` will always have at least the data returned by a CAPI -`/profile` query. If the player is docked at a station, and the relevant -services are available then the `lastStarport` key's value will have been -augmented with `/market` and/or `/shipyard` data. **But do not assume this -will always be the case**. +`CAPIData` is a class, which you can `from companion import CAPIDATA`, and is based on `UserDict`. The actual data from CAPI queries is thus accessible via python's normal `data['key']` syntax. However, being a class, it can also have extra properties, such as `source_host`, as shown above. -In the `capi_fleetcarrier()` callback, the contents of `data` will be the response from the CAPI `/fleetcarrier` query. See [this documentation](https://github.com/Athanasius/fd-api/blob/main/docs/FrontierDevelopments-CAPI-endpoints.md) for details of the expected content structure and data. +#### Properties of CAPIData permitted for use by plugins -In all cases, `data` will include a `request_cmdr` entry, which will be the name of the active CMDR _at the point the request was made_. In the case of a CAPI request taking a long time to return, the user may have switched CMDR during the request, so this may be different to the current CMDR. +Plugin authors are free to use the following properties of `CAPIData`, **but MUST NOT rely on any other extra properties, they are for internal use only.** + +| Property | Type | Description | +| :------------- | :--------------: | :------------------------------------------------------------------------------------------------------- | +| `data` | `Dict` | The data returned by the CAPI query. For the `cmdr_data()` callback, if the player is docked at a station, and the relevant services are available then the `lastStarport` key's value will have been augmented with `/market` and/or `/shipyard` data. **But do not assume this will always be the case**. | +| `source_host` | `str` | `SERVER_LIVE` \| `SERVER_BETA` \| `SERVER_LEGACY` the current calaxy mode. | +| `request_cmdr` | `str` | The name of the active CMDR _at the point the request was made_. In the case of a CAPI request taking a long time to return, the user may have switched CMDR during the request, so this may be different to the current CMDR. | + +See [this documentation](https://github.com/Athanasius/fd-api/blob/main/docs/FrontierDevelopments-CAPI-endpoints.md) for details of the expected content structure and data for CAPI queries. If there is a killswitch in effect for some of the CAPI endpoints, then the data passed to this function might not be as complete as you expect. Code diff --git a/companion.py b/companion.py index f464e0d6..b7ccd093 100644 --- a/companion.py +++ b/companion.py @@ -68,7 +68,8 @@ class CAPIData(UserDict): self, data: Union[str, Dict[str, Any], 'CAPIData', None] = None, source_host: Optional[str] = None, - source_endpoint: Optional[str] = None + source_endpoint: Optional[str] = None, + request_cmdr: Optional[str] = None ) -> None: if data is None: super().__init__() @@ -83,6 +84,7 @@ class CAPIData(UserDict): self.source_host = source_host self.source_endpoint = source_endpoint + self.request_cmdr = request_cmdr if source_endpoint is None: return @@ -575,8 +577,7 @@ class EDMCCAPIRequest(EDMCCAPIReturn): self, capi_host: str, endpoint: str, query_time: int, tk_response_event: Optional[str] = None, - play_sound: bool = False, auto_update: bool = False, - cmdr: Optional[str] = None + play_sound: bool = False, auto_update: bool = False ): super().__init__( query_time=query_time, tk_response_event=tk_response_event, @@ -584,7 +585,6 @@ class EDMCCAPIRequest(EDMCCAPIReturn): ) self.capi_host: str = capi_host # The CAPI host to use. self.endpoint: str = endpoint # The CAPI query to perform. - self.cmdr: Optional[str] = cmdr # The CMDR name used for the request. class EDMCCAPIResponse(EDMCCAPIReturn): @@ -592,12 +592,10 @@ class EDMCCAPIResponse(EDMCCAPIReturn): def __init__( self, capi_data: CAPIData, - query_time: int, play_sound: bool = False, auto_update: bool = False, - cmdr: Optional[str] = None + query_time: int, play_sound: bool = False, auto_update: bool = False ): super().__init__(query_time=query_time, play_sound=play_sound, auto_update=auto_update) self.capi_data: CAPIData = capi_data # Frontier CAPI response, possibly augmented (station query) - self.capi_data['request_cmdr'] = cmdr # Inject the CMDR name used for the original request into the data class EDMCCAPIFailedRequest(EDMCCAPIReturn): @@ -821,7 +819,7 @@ class Session(object): # r.status_code = 401 # raise requests.HTTPError capi_json = r.json() - capi_data = CAPIData(capi_json, capi_host, capi_endpoint) + capi_data = CAPIData(capi_json, capi_host, capi_endpoint, monitor.cmdr) self.capi_raw_data.record_endpoint( capi_endpoint, r.content.decode(encoding='utf-8'), datetime.datetime.utcnow() @@ -997,8 +995,7 @@ class Session(object): capi_data=capi_data, query_time=query.query_time, play_sound=query.play_sound, - auto_update=query.auto_update, - cmdr=query.cmdr + auto_update=query.auto_update ) ) @@ -1046,8 +1043,7 @@ class Session(object): tk_response_event=tk_response_event, query_time=query_time, play_sound=play_sound, - auto_update=auto_update, - cmdr=monitor.cmdr + auto_update=auto_update ) ) @@ -1076,8 +1072,7 @@ class Session(object): tk_response_event=tk_response_event, query_time=query_time, play_sound=play_sound, - auto_update=auto_update, - cmdr=monitor.cmdr + auto_update=auto_update ) ) ######################################################################