Provide @available and @deprecated decorators for API endpoints to annotate them against Command Centre releases #69
Description
Is your feature request related to a problem? Please describe.
While working on a client project we realised that they are running v8.9 of the Command Centre software. All of our testing has been against the 9.x releases (even which is advancing rapidly, two releases a year).
Developers necessarily can't know ahead of time which Command Centre their software will be used against e.g our own Terminal or Command line interfaces.
This poses an issue where a feature may not be available and it can only be determined at runtime.
Describe the solution you'd like
The core of our API should make available two decorators:
@available- which would allow the developer to annotate an endpoint being available from a certain version of the Command Centre@deprecated- denoting that an API call has been deprecated and will be remove in a future release
If none of these decorators are applied then its assumed that the API endpoint is generally available, or available since the existence of the Command Centre REST API.
Each decorator should take a formatted SemVer string to denote which version a feature became available or which version of the library a method call will be deprecated (See also warnings package refactor).
For example @available('>9.10')
Describe alternatives you've considered
NA
Additional context
- Python
3.13introduces thedeprecateddecorator in thewarningspackage. At the moment this library is aimed at Python3.11+. - We might want to leave another ticket open once this is implemented to refactor the implementation (if appropriate) to the
warningspackage when the project is rebased for Python3.13 - See also Raise
warningsif an operation has an unintended use #3 - See also
dto/response/discover.pyforDiscoveryResponsewhich has theversionattribute and is queried dynamically from the API in accordance with Forward compatibility (HATEOAS) - Discover all endpoints dynamically fromapiresponse #5 - Read on version range operators to support properly matching the version strings.