Helpers¶

General Helpers¶

Helpers for general Python functionality.

google.api_core.general_helpers.wraps(wrapped)[source]¶: A functools.wraps helper that handles partial objects on Python 2.

Datetime Helpers¶

Helpers for datetime.

class google.api_core.datetime_helpers.DatetimeWithNanoseconds[source]¶

Bases: datetime.datetime

Track nanosecond in addition to normal datetime attrs.

Nanosecond can be passed only as a keyword argument.

classmethod from_rfc3339(stamp)[source]¶

Parse RFC 3339-compliant timestamp, preserving nanoseconds.

Parameters: stamp (str) – RFC 3339 stamp, with up to nanosecond precision
Returns: an instance matching the timestamp string
Return type: DatetimeWithNanoseconds
Raises: ValueError – if stamp does not match the expected format

classmethod from_timestamp_pb(stamp)[source]¶

Parse RFC 3339-compliant timestamp, preserving nanoseconds.

Parameters: stamp (Timestamp) – timestamp message
Returns: an instance matching the timestamp message
Return type: DatetimeWithNanoseconds

property nanosecond¶

nanosecond precision.

Type: Read-only

rfc3339()[source]¶

Return an RFC 3339-compliant timestamp.

Returns: Timestamp string according to RFC 3339 spec.
Return type: (str)

timestamp_pb()[source]¶

Return a timestamp message.

Returns: Timestamp message
Return type: (Timestamp)

google.api_core.datetime_helpers.from_iso8601_date(value)[source]¶

Convert a ISO8601 date string to a date.

Parameters: value (str) – The ISO8601 date string.
Returns: A date equivalent to the date string.
Return type: datetime.date

google.api_core.datetime_helpers.from_iso8601_time(value)[source]¶

Convert a zoneless ISO8601 time string to a time.

Parameters: value (str) – The ISO8601 time string.
Returns: A time equivalent to the time string.
Return type: datetime.time

google.api_core.datetime_helpers.from_microseconds(value)[source]¶

Convert timestamp in microseconds since the unix epoch to datetime.

Parameters

value (float) – The timestamp to convert, in microseconds.

Returns

The datetime object equivalent to the timestamp in: UTC.

Return type

datetime.datetime

google.api_core.datetime_helpers.from_rfc3339(value)[source]¶

Convert a microsecond-precision timestamp to datetime.

Parameters

value (str) – The RFC3339 string to convert.

Returns

The datetime object equivalent to the timestamp in: UTC.

Return type

datetime.datetime

google.api_core.datetime_helpers.from_rfc3339_nanos(value)[source]¶

Convert a nanosecond-precision timestamp to a native datetime.

Note

Python datetimes do not support nanosecond precision; this function therefore truncates such values to microseconds.

Parameters

value (str) – The RFC3339 string to convert.

Returns

The datetime object equivalent to the timestamp in: UTC.

Return type

datetime.datetime

Raises

ValueError – If the timestamp does not match the RFC 3339 regular expression.

google.api_core.datetime_helpers.to_microseconds(value)[source]¶

Convert a datetime to microseconds since the unix epoch.

Parameters: value (datetime.datetime) – The datetime to covert.
Returns: Microseconds since the unix epoch.
Return type: int

google.api_core.datetime_helpers.to_milliseconds(value)[source]¶

Convert a zone-aware datetime to milliseconds since the unix epoch.

Parameters: value (datetime.datetime) – The datetime to covert.
Returns: Milliseconds since the unix epoch.
Return type: int

google.api_core.datetime_helpers.to_rfc3339(value, ignore_zone=True)[source]¶

Convert a datetime to an RFC3339 timestamp string.

Parameters

value (datetime.datetime) – The datetime object to be converted to a string.
ignore_zone (bool) – If True, then the timezone (if any) of the datetime object is ignored and the datetime is treated as UTC.

Returns

The RFC3339 formated string representing the datetime.

Return type

str

google.api_core.datetime_helpers.utcnow()[source]¶: A datetime.datetime.utcnow() alias to allow mocking in tests.

gRPC Helpers¶

Helpers for grpc.

class google.api_core.grpc_helpers.ChannelStub(responses=[])[source]¶

Bases: grpc.Channel

A testing stub for the grpc.Channel interface.

This can be used to test any client that eventually uses a gRPC channel to communicate. By passing in a channel stub, you can configure which responses are returned and track which requests are made.

For example:

channel_stub = grpc_helpers.ChannelStub()
client = FooClient(channel=channel_stub)

channel_stub.GetFoo.response = foo_pb2.Foo(name='bar')

foo = client.get_foo(labels=['baz'])

assert foo.name == 'bar'
assert channel_stub.GetFoo.requests[0].labels = ['baz']

Each method on the stub can be accessed and configured on the channel. Here’s some examples of various configurations:

# Return a basic response:

channel_stub.GetFoo.response = foo_pb2.Foo(name='bar')
assert client.get_foo().name == 'bar'

# Raise an exception:
channel_stub.GetFoo.response = NotFound('...')

with pytest.raises(NotFound):
    client.get_foo()

# Use a sequence of responses:
channel_stub.GetFoo.responses = iter([
    foo_pb2.Foo(name='bar'),
    foo_pb2.Foo(name='baz'),
])

assert client.get_foo().name == 'bar'
assert client.get_foo().name == 'baz'

# Use a callable

def on_get_foo(request):
    return foo_pb2.Foo(name='bar' + request.id)

channel_stub.GetFoo.response = on_get_foo

assert client.get_foo(id='123').name == 'bar123'

close()[source]¶: grpc.Channel.close implementation.

requests = None¶

A list of all requests made on this channel in order. The tuple is of method name, request message.

Type: Sequence[Tuple[str, protobuf.Message]]

stream_stream(method, request_serializer=None, response_deserializer=None)[source]¶: grpc.Channel.stream_stream implementation.

stream_unary(method, request_serializer=None, response_deserializer=None)[source]¶: grpc.Channel.stream_unary implementation.

subscribe(callback, try_to_connect=False)[source]¶: grpc.Channel.subscribe implementation.

unary_stream(method, request_serializer=None, response_deserializer=None)[source]¶: grpc.Channel.unary_stream implementation.

unary_unary(method, request_serializer=None, response_deserializer=None)[source]¶: grpc.Channel.unary_unary implementation.

unsubscribe(callback)[source]¶: grpc.Channel.unsubscribe implementation.

google.api_core.grpc_helpers.create_channel(target, credentials=None, scopes=None, ssl_credentials=None, **kwargs)[source]¶

Create a secure channel with credentials.

Parameters

target (str) – The target service address in the format ‘hostname:port’.
credentials (google.auth.credentials.Credentials) – The credentials. If not specified, then this function will attempt to ascertain the credentials from the environment using google.auth.default().
scopes (Sequence[str]) – A optional list of scopes needed for this service. These are only used when credentials are not specified and are passed to google.auth.default().
ssl_credentials (grpc.ChannelCredentials) – Optional SSL channel credentials. This can be used to specify different certificates.
kwargs – Additional key-word args passed to grpc_gcp.secure_channel() or grpc.secure_channel().

Returns

The created channel.

Return type

grpc.Channel

google.api_core.grpc_helpers.wrap_errors(callable_)[source]¶

Wrap a gRPC callable and map grpc.RpcErrors to friendly error classes.

Errors raised by the gRPC callable are mapped to the appropriate google.api_core.exceptions.GoogleAPICallError subclasses. The original grpc.RpcError (which is usually also a grpc.Call) is available from the response property on the mapped exception. This is useful for extracting metadata from the original error.

Parameters: callable_ (Callable) – A gRPC callable.
Returns: The wrapped gRPC callable.
Return type: Callable

Helpers¶

General Helpers¶

Datetime Helpers¶

gRPC Helpers¶

google-api-core

Navigation

Related Topics