Add a command to trim the history instead of clearing it completely

[flowln]

This is intended as a less nuclear alternative to history_clear, allowing you to discard some older history while maintaining the newer, potentially more useful, records.

Summary of Changes for Release Notes

Added

• history_clear was extended to accept the optional size parameter. If the parameter is passed with an API call, the history is trimmed to the specified size leaving the most recent items.

[dmgav]

@flowln Thank you for contributing to the project. The proposed functionality is useful, but in my opinion adding new API is not justified. I would suggest extending the existing history_clear API to accept optional size parameter and trim the history if the parameter is set (not None). The API call should also fail if the value is invalid (must be positive integer or 0).
It the future I would also add another parameter (named item_uid or similar) that would remove all entries from the history starting from specified item. This may be useful for applications where the history is periodically backed by external service.

[flowln]

@flowln Thank you for contributing to the project. The proposed functionality is useful, but in my opinion adding new API is not justified. I would suggest extending the existing history_clear API to accept optional size parameter and trim the history if the parameter is set (not None). The API call should also fail if the value is invalid (must be positive integer or 0). It the future I would also add another parameter (named item_uid or similar) that would remove all entries from the history starting from specified item. This may be useful for applications where the history is periodically backed by external service.

Your suggestion is fine by me, I can implement that. Originally I wanted to retain the semantics there seems to have in the current API with queue operations: clear always clears everything, while other commands like remove and remove_batch clear some part of the whole. I think it would be nice to keep the API consistent like that, but it's not a strict requirement. What are your thoughts about that @dmgav?

[dmgav]

The API that support editing the queue are naturally more extensive. Operations on history are very limited. I think it is better to extend queue_clear API in this case. Internally we can use separate methods to execute the operation, for example keeping trim_history method in plan_queue_ops.py is fine.