Skip to content

Commit

Permalink
refactor(speech): versioned v1 client (#10942)
Browse files Browse the repository at this point in the history
  • Loading branch information
@dbolduc
dbolduc committed Feb 24, 2023
1 parent a2a691f commit a574ad2
Show file tree
Hide file tree
Showing 40 changed files with 752 additions and 528 deletions.
Binary file modified ci/abi-dumps/google_cloud_cpp_speech.expected.abi.dump.gz
View file
Binary file not shown.
3 changes: 2 additions & 1 deletion ci/etc/expected_install_directories
View file
Original file line number Diff line number Diff line change
Expand Up @@ -480,9 +480,10 @@
./include/google/cloud/spanner/admin/internal
./include/google/cloud/spanner/admin/mocks
./include/google/cloud/speech
./include/google/cloud/speech/internal
./include/google/cloud/speech/mocks
./include/google/cloud/speech/v1
./include/google/cloud/speech/v1/internal
./include/google/cloud/speech/v1/mocks
./include/google/cloud/speech/v2
./include/google/cloud/speech/v2/internal
./include/google/cloud/speech/v2/mocks
Expand Down
3 changes: 2 additions & 1 deletion generator/generator_config.textproto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1604,7 +1604,8 @@ service {
# Speech
service {
service_proto_path: "google/cloud/speech/v1/cloud_speech.proto"
product_path: "google/cloud/speech"
product_path: "google/cloud/speech/v1"
forwarding_product_path: "google/cloud/speech"
initial_copyright_year: "2022"
retryable_status_codes: ["kUnavailable"]
}
Expand Down
1 change: 1 addition & 0 deletions google/cloud/speech/BUILD.bazel
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ licenses(["notice"]) # Apache 2.0

service_dirs = [
"",
"v1/",
"v2/",
]

Expand Down
8 changes: 5 additions & 3 deletions google/cloud/speech/CMakeLists.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,14 +24,16 @@ set(DOXYGEN_EXAMPLE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/quickstart")

unset(mocks_globs)
unset(source_globs)
set(service_dirs "" "v2/")
set(service_dirs "" "v1/" "v2/")
foreach (dir IN LISTS service_dirs)
string(REPLACE "/" "_" ns "${dir}")
list(APPEND source_globs "${dir}*.h" "${dir}*.cc" "${dir}internal/*")
list(APPEND mocks_globs "${dir}mocks/*.h")
list(APPEND DOXYGEN_EXAMPLE_PATH
"${CMAKE_CURRENT_SOURCE_DIR}/${dir}samples")
list(APPEND DOXYGEN_EXCLUDE_SYMBOLS "speech_${ns}internal")
if (NOT dir STREQUAL "")
list(APPEND DOXYGEN_EXAMPLE_PATH
"${CMAKE_CURRENT_SOURCE_DIR}/${dir}samples")
endif ()
endforeach ()

include(GoogleCloudCppDoxygen)
Expand Down
14 changes: 7 additions & 7 deletions google/cloud/speech/doc/main.dox
View file
Original file line number Diff line number Diff line change
Expand Up @@ -92,12 +92,12 @@ library. Use the `google::cloud::EndpointOption` when initializing the client
library to change this default.

<!-- inject-endpoint-snippet-start -->
For example, this will override the default endpoint for `speech::SpeechClient`:
For example, this will override the default endpoint for `speech_v1::SpeechClient`:

@snippet speech_client_samples.cc set-client-endpoint

Follow these links to find examples for other \c *Client classes:
[speech::SpeechClient](@ref speech::SpeechClient-endpoint-snippet)
[speech_v1::SpeechClient](@ref speech_v1::SpeechClient-endpoint-snippet)
[speech_v2::SpeechClient](@ref speech_v2::SpeechClient-endpoint-snippet)

<!-- inject-endpoint-snippet-end -->
Expand All @@ -113,7 +113,7 @@ to explicitly load a service account key file.
@snippet speech_client_samples.cc with-service-account

Follow these links to find examples for other \c *Client classes:
[speech::SpeechClient](@ref speech::SpeechClient-service-account-snippet)
[speech_v1::SpeechClient](@ref speech_v1::SpeechClient-service-account-snippet)
[speech_v2::SpeechClient](@ref speech_v2::SpeechClient-service-account-snippet)

<!-- inject-service-account-snippet-end -->
Expand Down Expand Up @@ -145,15 +145,15 @@ can override the default policies.

// <!-- inject-endpoint-pages-start -->

/*! @page speech::SpeechClient-endpoint-snippet Override speech::SpeechClient Endpoint Configuration
/*! @page speech_v1::SpeechClient-endpoint-snippet Override speech_v1::SpeechClient Endpoint Configuration

@snippet google/cloud/speech/samples/speech_client_samples.cc set-client-endpoint
@snippet google/cloud/speech/v1/samples/speech_client_samples.cc set-client-endpoint

*/

/*! @page speech::SpeechClient-service-account-snippet Override speech::SpeechClient Authentication Defaults
/*! @page speech_v1::SpeechClient-service-account-snippet Override speech_v1::SpeechClient Authentication Defaults

@snippet google/cloud/speech/samples/speech_client_samples.cc with-service-account
@snippet google/cloud/speech/v1/samples/speech_client_samples.cc with-service-account

*/

Expand Down
38 changes: 3 additions & 35 deletions google/cloud/speech/mocks/mock_speech_connection.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,47 +20,15 @@
#define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPEECH_MOCKS_MOCK_SPEECH_CONNECTION_H

#include "google/cloud/speech/speech_connection.h"
#include <gmock/gmock.h>
#include "google/cloud/speech/v1/mocks/mock_speech_connection.h"

namespace google {
namespace cloud {
namespace speech_mocks {
GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN

/**
* A class to mock `SpeechConnection`.
*
* Application developers may want to test their code with simulated responses,
* including errors, from an object of type `SpeechClient`. To do so,
* construct an object of type `SpeechClient` with an instance of this
* class. Then use the Google Test framework functions to program the behavior
* of this mock.
*
* @see [This example][bq-mock] for how to test your application with GoogleTest.
* While the example showcases types from the BigQuery library, the underlying
* principles apply for any pair of `*Client` and `*Connection`.
*
* [bq-mock]: @googleapis_dev_link{bigquery,bigquery-read-mock.html}
*/
class MockSpeechConnection : public speech::SpeechConnection {
public:
MOCK_METHOD(Options, options, (), (override));

MOCK_METHOD(StatusOr<google::cloud::speech::v1::RecognizeResponse>, Recognize,
(google::cloud::speech::v1::RecognizeRequest const& request),
(override));

MOCK_METHOD(
future<StatusOr<google::cloud::speech::v1::LongRunningRecognizeResponse>>,
LongRunningRecognize,
(google::cloud::speech::v1::LongRunningRecognizeRequest const& request),
(override));

MOCK_METHOD((std::unique_ptr<::google::cloud::AsyncStreamingReadWriteRpc<
google::cloud::speech::v1::StreamingRecognizeRequest,
google::cloud::speech::v1::StreamingRecognizeResponse>>),
AsyncStreamingRecognize, (), (override));
};
/// @deprecated Use speech_v1_mocks::MockSpeechConnection directly.
using ::google::cloud::speech_v1_mocks::MockSpeechConnection;

GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
} // namespace speech_mocks
Expand Down
181 changes: 3 additions & 178 deletions google/cloud/speech/speech_client.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,190 +20,15 @@
#define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPEECH_SPEECH_CLIENT_H

#include "google/cloud/speech/speech_connection.h"
#include "google/cloud/future.h"
#include "google/cloud/options.h"
#include "google/cloud/polling_policy.h"
#include "google/cloud/status_or.h"
#include "google/cloud/version.h"
#include <google/longrunning/operations.grpc.pb.h>
#include <memory>
#include "google/cloud/speech/v1/speech_client.h"

namespace google {
namespace cloud {
namespace speech {
GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN

///
/// Service that implements Google Cloud Speech API.
///
/// @par Equality
///
/// Instances of this class created via copy-construction or copy-assignment
/// always compare equal. Instances created with equal
/// `std::shared_ptr<*Connection>` objects compare equal. Objects that compare
/// equal share the same underlying resources.
///
/// @par Performance
///
/// Creating a new instance of this class is a relatively expensive operation,
/// new objects establish new connections to the service. In contrast,
/// copy-construction, move-construction, and the corresponding assignment
/// operations are relatively efficient as the copies share all underlying
/// resources.
///
/// @par Thread Safety
///
/// Concurrent access to different instances of this class, even if they compare
/// equal, is guaranteed to work. Two or more threads operating on the same
/// instance of this class is not guaranteed to work. Since copy-construction
/// and move-construction is a relatively efficient operation, consider using
/// such a copy when using this class from multiple threads.
///
class SpeechClient {
public:
explicit SpeechClient(std::shared_ptr<SpeechConnection> connection,
Options opts = {});
~SpeechClient();

///@{
/// @name Copy and move support
SpeechClient(SpeechClient const&) = default;
SpeechClient& operator=(SpeechClient const&) = default;
SpeechClient(SpeechClient&&) = default;
SpeechClient& operator=(SpeechClient&&) = default;
///@}

///@{
/// @name Equality
friend bool operator==(SpeechClient const& a, SpeechClient const& b) {
return a.connection_ == b.connection_;
}
friend bool operator!=(SpeechClient const& a, SpeechClient const& b) {
return !(a == b);
}
///@}

///
/// Performs synchronous speech recognition: receive results after all audio
/// has been sent and processed.
///
/// @param config Required. Provides information to the recognizer that
/// specifies how to
/// process the request.
/// @param audio Required. The audio data to be recognized.
/// @param opts Optional. Override the class-level options, such as retry and
/// backoff policies.
/// @return
/// @googleapis_link{google::cloud::speech::v1::RecognizeResponse,google/cloud/speech/v1/cloud_speech.proto#L647}
///
/// [google.cloud.speech.v1.RecognizeRequest]:
/// @googleapis_reference_link{google/cloud/speech/v1/cloud_speech.proto#L76}
/// [google.cloud.speech.v1.RecognizeResponse]:
/// @googleapis_reference_link{google/cloud/speech/v1/cloud_speech.proto#L647}
///
StatusOr<google::cloud::speech::v1::RecognizeResponse> Recognize(
google::cloud::speech::v1::RecognitionConfig const& config,
google::cloud::speech::v1::RecognitionAudio const& audio,
Options opts = {});

///
/// Performs synchronous speech recognition: receive results after all audio
/// has been sent and processed.
///
/// @param request
/// @googleapis_link{google::cloud::speech::v1::RecognizeRequest,google/cloud/speech/v1/cloud_speech.proto#L76}
/// @param opts Optional. Override the class-level options, such as retry and
/// backoff policies.
/// @return
/// @googleapis_link{google::cloud::speech::v1::RecognizeResponse,google/cloud/speech/v1/cloud_speech.proto#L647}
///
/// [google.cloud.speech.v1.RecognizeRequest]:
/// @googleapis_reference_link{google/cloud/speech/v1/cloud_speech.proto#L76}
/// [google.cloud.speech.v1.RecognizeResponse]:
/// @googleapis_reference_link{google/cloud/speech/v1/cloud_speech.proto#L647}
///
StatusOr<google::cloud::speech::v1::RecognizeResponse> Recognize(
google::cloud::speech::v1::RecognizeRequest const& request,
Options opts = {});

///
/// Performs asynchronous speech recognition: receive results via the
/// google.longrunning.Operations interface. Returns either an
/// `Operation.error` or an `Operation.response` which contains
/// a `LongRunningRecognizeResponse` message.
/// For more information on asynchronous speech recognition, see the
/// [how-to](https://cloud.google.com/speech-to-text/docs/async-recognize).
///
/// @param config Required. Provides information to the recognizer that
/// specifies how to
/// process the request.
/// @param audio Required. The audio data to be recognized.
/// @param opts Optional. Override the class-level options, such as retry and
/// backoff policies.
/// @return
/// @googleapis_link{google::cloud::speech::v1::LongRunningRecognizeResponse,google/cloud/speech/v1/cloud_speech.proto#L668}
///
/// [google.cloud.speech.v1.LongRunningRecognizeRequest]:
/// @googleapis_reference_link{google/cloud/speech/v1/cloud_speech.proto#L87}
/// [google.cloud.speech.v1.LongRunningRecognizeResponse]:
/// @googleapis_reference_link{google/cloud/speech/v1/cloud_speech.proto#L668}
///
future<StatusOr<google::cloud::speech::v1::LongRunningRecognizeResponse>>
LongRunningRecognize(
google::cloud::speech::v1::RecognitionConfig const& config,
google::cloud::speech::v1::RecognitionAudio const& audio,
Options opts = {});

///
/// Performs asynchronous speech recognition: receive results via the
/// google.longrunning.Operations interface. Returns either an
/// `Operation.error` or an `Operation.response` which contains
/// a `LongRunningRecognizeResponse` message.
/// For more information on asynchronous speech recognition, see the
/// [how-to](https://cloud.google.com/speech-to-text/docs/async-recognize).
///
/// @param request
/// @googleapis_link{google::cloud::speech::v1::LongRunningRecognizeRequest,google/cloud/speech/v1/cloud_speech.proto#L87}
/// @param opts Optional. Override the class-level options, such as retry and
/// backoff policies.
/// @return
/// @googleapis_link{google::cloud::speech::v1::LongRunningRecognizeResponse,google/cloud/speech/v1/cloud_speech.proto#L668}
///
/// [google.cloud.speech.v1.LongRunningRecognizeRequest]:
/// @googleapis_reference_link{google/cloud/speech/v1/cloud_speech.proto#L87}
/// [google.cloud.speech.v1.LongRunningRecognizeResponse]:
/// @googleapis_reference_link{google/cloud/speech/v1/cloud_speech.proto#L668}
///
future<StatusOr<google::cloud::speech::v1::LongRunningRecognizeResponse>>
LongRunningRecognize(
google::cloud::speech::v1::LongRunningRecognizeRequest const& request,
Options opts = {});

///
/// Performs bidirectional streaming speech recognition: receive results while
/// sending audio. This method is only available via the gRPC API (not REST).
///
/// @param opts Optional. Override the class-level options, such as retry and
/// backoff policies.
/// @return A bidirectional streaming interface with request (write) type:
/// @googleapis_link{google::cloud::speech::v1::StreamingRecognizeRequest,google/cloud/speech/v1/cloud_speech.proto#L114}
/// and response (read) type:
/// @googleapis_link{google::cloud::speech::v1::StreamingRecognizeResponse,google/cloud/speech/v1/cloud_speech.proto#L758}
///
/// [google.cloud.speech.v1.StreamingRecognizeRequest]:
/// @googleapis_reference_link{google/cloud/speech/v1/cloud_speech.proto#L114}
/// [google.cloud.speech.v1.StreamingRecognizeResponse]:
/// @googleapis_reference_link{google/cloud/speech/v1/cloud_speech.proto#L758}
///
std::unique_ptr<::google::cloud::AsyncStreamingReadWriteRpc<
google::cloud::speech::v1::StreamingRecognizeRequest,
google::cloud::speech::v1::StreamingRecognizeResponse>>
AsyncStreamingRecognize(Options opts = {});

private:
std::shared_ptr<SpeechConnection> connection_;
Options options_;
};
/// @deprecated Use speech_v1::SpeechClient directly.
using ::google::cloud::speech_v1::SpeechClient;

GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
} // namespace speech
Expand Down
Loading

0 comments on commit a574ad2

Please sign in to comment.