Improve StageResult printout (#2760)

#### Reference Issues/PRs
<!--Example: Fixes #1234. See also #3456.-->

#### What does this implement or fix?
Improve the readability of `StageResult` along with atom keys' printout

New `StageResult` printout example:
`StageResult(staged_segments=[Key(type=b, id='sym', version_id=0,
content_hash=0xac454fbcb62cd989, creation_ts=1763562571272342532,
start_index=1735689600000000000, end_index=1735776000000000001),
Key(type=b, id='sym', version_id=0, content_hash=0x14e310dcc399815e,
creation_ts=1763562571272634201, start_index=1735862400000000000,
end_index=1735862400000000001)])`

New key printout example:
`Key(type=b, id='sym', version_id=0, content_hash=0xac454fbcb62cd989,
creation_ts=1763562571272342532, start_index=1735689600000000000,
end_index=1735776000000000001)`

Docstring for the class has been added to the docs website as well.
#### Any other comments?

#### Checklist

<details>
  <summary>
   Checklist for code changes...
  </summary>
 
- [ ] Have you updated the relevant docstrings, documentation and
copyright notice?
- [ ] Is this contribution tested against [all ArcticDB's
features](../docs/mkdocs/docs/technical/contributing.md)?
- [ ] Do all exceptions introduced raise appropriate [error
messages](https://docs.arcticdb.io/error_messages/)?
 - [ ] Are API changes highlighted in the PR description?
- [ ] Is the PR labelled as enhancement or bug so it appears in
autogenerated release notes?
</details>

<!--
Thanks for contributing a Pull Request to ArcticDB! Please ensure you
have taken a look at:
- ArcticDB's Code of Conduct:
https://github.com/man-group/ArcticDB/blob/master/CODE_OF_CONDUCT.md
- ArcticDB's Contribution Licensing:
https://github.com/man-group/ArcticDB/blob/master/docs/mkdocs/docs/technical/contributing.md#contribution-licensing
-->

Author: phoebusm

cpp/arcticdb/CMakeLists.txt

@@ -228,6 +228,7 @@ set(arcticdb_srcs
         entity/ref_key.hpp
         entity/serialized_key.hpp
         entity/stage_result.hpp
+        entity/stage_result.cpp
         entity/type_conversion.hpp
         entity/types.hpp
         entity/type_utils.hpp

cpp/arcticdb/entity/atom_key.hpp

@@ -116,6 +116,8 @@ class AtomKeyImpl {
         return {str_};
     }
 
+    std::string view_human() const;
+
   private:
     StreamId id_;
     VersionId version_id_ = 0;
@@ -328,4 +330,8 @@ struct hash<arcticdb::entity::AtomKeyImpl> {
 namespace arcticdb::entity {
 // This needs to be defined AFTER the formatter for AtomKeyImpl
 inline void AtomKeyImpl::set_string() const { str_ = fmt::format("{}", *this); }
+
+inline std::string AtomKeyImpl::view_human() const {
+    return fmt::format("{}", formattable<AtomKeyImpl, DisplayAtomKeyFormat>(*this));
+}
 } // namespace arcticdb::entity

cpp/arcticdb/entity/key.hpp

@@ -22,6 +22,11 @@ struct DefaultAtomKeyFormat {
     static constexpr char format[] = "{}:{}:{:d}:0x{:x}@{:d}[{},{}]";
 };
 
+struct DisplayAtomKeyFormat {
+    static constexpr char format[] = "Key(type={}, id='{}', version_id={:d}, content_hash=0x{:x}, creation_ts={:d}, "
+                                     "start_index={}, end_index={})";
+};
+
 template<class T, class FormattingTag = DefaultAtomKeyFormat>
 struct FormattableRef {
     const T& ref;

cpp/arcticdb/entity/stage_result.cpp

@@ -0,0 +1,5 @@
+#include <arcticdb/entity/stage_result.hpp>
+
+namespace arcticdb {
+std::string StageResult::view() const { return fmt::format("{}", *this); }
+} // namespace arcticdb

cpp/arcticdb/entity/stage_result.hpp

@@ -10,11 +10,33 @@
 
 #include <arcticdb/entity/atom_key.hpp>
 #include <vector>
+#include <ranges>
+#include <fmt/format.h>
+#include <fmt/ranges.h>
 
 namespace arcticdb {
 struct StageResult {
     explicit StageResult(std::vector<entity::AtomKey> staged_segments) : staged_segments(std::move(staged_segments)) {}
 
     std::vector<entity::AtomKey> staged_segments;
+
+    std::string view() const;
+};
+} // namespace arcticdb
+
+namespace fmt {
+template<>
+struct formatter<arcticdb::StageResult> {
+    template<typename ParseContext>
+    constexpr auto parse(ParseContext& ctx) {
+        return ctx.begin();
+    }
+
+    template<typename FormatContext>
+    auto format(const arcticdb::StageResult& stage_result, FormatContext& ctx) const {
+        auto transform_view =
+                stage_result.staged_segments | std::views::transform([](const auto& key) { return key.view_human(); });
+        return fmt::format_to(ctx.out(), "StageResult(staged_segments=[{}])", fmt::join(transform_view, ", "));
+    }
 };
-} // namespace arcticdb
+} // namespace fmt

cpp/arcticdb/version/python_bindings.cpp

@@ -157,7 +157,7 @@ void register_bindings(py::module& version, py::exception<arcticdb::ArcticExcept
             .def_property_readonly("type", [](const AtomKey& self) { return self.type(); })
             .def(pybind11::self == pybind11::self)
             .def(pybind11::self != pybind11::self)
-            .def("__repr__", &AtomKey::view)
+            .def("__repr__", &AtomKey::view_human)
             .def(py::self < py::self)
             .def(py::pickle(
                     [](const AtomKey& key) {
@@ -375,9 +375,19 @@ void register_bindings(py::module& version, py::exception<arcticdb::ArcticExcept
             .def_property_readonly("creation_ts", &DescriptorItem::creation_ts)
             .def_property_readonly("timeseries_descriptor", &DescriptorItem::timeseries_descriptor);
 
-    py::class_<StageResult>(version, "StageResult")
+    py::class_<StageResult>(version, "StageResult", R"pbdoc(
+        Result returned by the stage method containing information about staged segments.
+        
+        StageResult objects can be passed to finalization methods to specify which staged data to finalize.
+        This enables selective finalization of staged data when multiple stage operations have been performed.
+        
+        Attributes
+        ----------
+        staged_segments : List[AtomKey]
+)pbdoc")
             .def(py::init([]() { return StageResult({}); }))
             .def_property_readonly("staged_segments", [](const StageResult& self) { return self.staged_segments; })
+            .def("__repr__", &StageResult::view)
             .def(py::pickle(
                     [](const StageResult& s) {
                         constexpr int serialization_version = 0;

docs/mkdocs/docs/api/library_types.md

@@ -22,3 +22,4 @@
 
 ::: arcticdb.WriteMetadataPayload
 
+::: arcticdb_ext.version_store.StageResult