Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/s3transfer/subscribers.py: 52%

1# Copyright 2016 Amazon.com, Inc. or its affiliates. All Rights Reserved. 

2# 

3# Licensed under the Apache License, Version 2.0 (the "License"). You 

4# may not use this file except in compliance with the License. A copy of 

5# the License is located at 

6# 

7# http://aws.amazon.com/apache2.0/ 

8# 

9# or in the "license" file accompanying this file. This file is 

10# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF 

11# ANY KIND, either express or implied. See the License for the specific 

12# language governing permissions and limitations under the License. 

13from functools import lru_cache 

14 

15from s3transfer.compat import accepts_kwargs 

16from s3transfer.exceptions import InvalidSubscriberMethodError 

17 

18 

19class BaseSubscriber: 

20 """The base subscriber class 

21 

22 It is recommended that all subscriber implementations subclass and then 

23 override the subscription methods (i.e. on_{subsribe_type}() methods). 

24 """ 

25 

26 VALID_SUBSCRIBER_TYPES = ['queued', 'progress', 'done'] 

27 

28 def __new__(cls, *args, **kwargs): 

29 cls._validate_subscriber_methods() 

30 return super().__new__(cls) 

31 

32 @classmethod 

33 @lru_cache() 

34 def _validate_subscriber_methods(cls): 

35 for subscriber_type in cls.VALID_SUBSCRIBER_TYPES: 

36 subscriber_method = getattr(cls, 'on_' + subscriber_type) 

37 if not callable(subscriber_method): 

38 raise InvalidSubscriberMethodError( 

39 'Subscriber method %s must be callable.' 

40 % subscriber_method 

41 ) 

42 

43 if not accepts_kwargs(subscriber_method): 

44 raise InvalidSubscriberMethodError( 

45 'Subscriber method %s must accept keyword ' 

46 'arguments (**kwargs)' % subscriber_method 

47 ) 

48 

49 def on_queued(self, future, **kwargs): 

50 """Callback to be invoked when transfer request gets queued 

51 

52 This callback can be useful for: 

53 

54 * Keeping track of how many transfers have been requested 

55 * Providing the expected transfer size through 

56 future.meta.provide_transfer_size() so a HeadObject would not 

57 need to be made for copies and downloads. 

58 

59 :type future: s3transfer.futures.TransferFuture 

60 :param future: The TransferFuture representing the requested transfer. 

61 """ 

62 pass 

63 

64 def on_progress(self, future, bytes_transferred, **kwargs): 

65 """Callback to be invoked when progress is made on transfer 

66 

67 This callback can be useful for: 

68 

69 * Recording and displaying progress 

70 

71 :type future: s3transfer.futures.TransferFuture 

72 :param future: The TransferFuture representing the requested transfer. 

73 

74 :type bytes_transferred: int 

75 :param bytes_transferred: The number of bytes transferred for that 

76 invocation of the callback. Note that a negative amount can be 

77 provided, which usually indicates that an in-progress request 

78 needed to be retried and thus progress was rewound. 

79 """ 

80 pass 

81 

82 def on_done(self, future, **kwargs): 

83 """Callback to be invoked once a transfer is done 

84 

85 This callback can be useful for: 

86 

87 * Recording and displaying whether the transfer succeeded or 

88 failed using future.result() 

89 * Running some task after the transfer completed like changing 

90 the last modified time of a downloaded file. 

91 

92 :type future: s3transfer.futures.TransferFuture 

93 :param future: The TransferFuture representing the requested transfer. 

94 """ 

95 pass