Debian Codegraph @

boto3/s3/inject.py

raw
1 # Copyright 2015 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 # https://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.
13 import copy as python_copy
14 import logging
15 from functools import partial
16
17 from botocore.exceptions import ClientError
18
19 from boto3 import utils
20 from boto3.compat import is_append_mode
21 from boto3.s3.transfer import (
22 ProgressCallbackInvoker,
23 S3Transfer,
24 TransferConfig,
25 create_transfer_manager,
26 )
27
28 try:
29 from botocore.context import with_current_context
30 except ImportError:
31 from functools import wraps
32
33 def with_current_context(hook=None):
34 def decorator(func):
35 @wraps(func)
36 def wrapper(*args, **kwargs):
37 return func(*args, **kwargs)
38
39 return wrapper
40
41 return decorator
42
43
44 try:
45 from botocore.useragent import register_feature_id
46 except ImportError:
47
48 def register_feature_id(feature_id):
49 pass
50
51
52 logger = logging.getLogger(__name__)
53
54
55 def inject_s3_transfer_methods(class_attributes, **kwargs):
56 utils.inject_attribute(class_attributes, 'upload_file', upload_file)
57 utils.inject_attribute(class_attributes, 'download_file', download_file)
58 utils.inject_attribute(class_attributes, 'copy', copy)
59 utils.inject_attribute(class_attributes, 'upload_fileobj', upload_fileobj)
60 utils.inject_attribute(
61 class_attributes, 'download_fileobj', download_fileobj
62 )
63
64
65 def inject_bucket_methods(class_attributes, **kwargs):
66 utils.inject_attribute(class_attributes, 'load', bucket_load)
67 utils.inject_attribute(class_attributes, 'upload_file', bucket_upload_file)
68 utils.inject_attribute(
69 class_attributes, 'download_file', bucket_download_file
70 )
71 utils.inject_attribute(class_attributes, 'copy', bucket_copy)
72 utils.inject_attribute(
73 class_attributes, 'upload_fileobj', bucket_upload_fileobj
74 )
75 utils.inject_attribute(
76 class_attributes, 'download_fileobj', bucket_download_fileobj
77 )
78
79
80 def inject_object_methods(class_attributes, **kwargs):
81 utils.inject_attribute(class_attributes, 'upload_file', object_upload_file)
82 utils.inject_attribute(
83 class_attributes, 'download_file', object_download_file
84 )
85 utils.inject_attribute(class_attributes, 'copy', object_copy)
86 utils.inject_attribute(
87 class_attributes, 'upload_fileobj', object_upload_fileobj
88 )
89 utils.inject_attribute(
90 class_attributes, 'download_fileobj', object_download_fileobj
91 )
92
93
94 def inject_object_summary_methods(class_attributes, **kwargs):
95 utils.inject_attribute(class_attributes, 'load', object_summary_load)
96
97
98 def bucket_load(self, *args, **kwargs):
99 """
100 Calls s3.Client.list_buckets() to update the attributes of the Bucket
101 resource.
102 """
103 # The docstring above is phrased this way to match what the autogenerated
104 # docs produce.
105
106 # We can't actually get the bucket's attributes from a HeadBucket,
107 # so we need to use a ListBuckets and search for our bucket.
108 # However, we may fail if we lack permissions to ListBuckets
109 # or the bucket is in another account. In which case, creation_date
110 # will be None.
111 self.meta.data = {}
112 try:
113 response = self.meta.client.list_buckets()
114 for bucket_data in response['Buckets']:
115 if bucket_data['Name'] == self.name:
116 self.meta.data = bucket_data
117 break
118 except ClientError as e:
119 if not e.response.get('Error', {}).get('Code') == 'AccessDenied':
120 raise
121
122
123 def object_summary_load(self, *args, **kwargs):
124 """
125 Calls s3.Client.head_object to update the attributes of the ObjectSummary
126 resource.
127 """
128 response = self.meta.client.head_object(
129 Bucket=self.bucket_name, Key=self.key
130 )
131 if 'ContentLength' in response:
132 response['Size'] = response.pop('ContentLength')
133 self.meta.data = response
134
135
136 @with_current_context(partial(register_feature_id, 'S3_TRANSFER'))
137 def upload_file(
138 self, Filename, Bucket, Key, ExtraArgs=None, Callback=None, Config=None
139 ):
140 """Upload a file to an S3 object.
141
142 Usage::
143
144 import boto3
145 s3 = boto3.client('s3')
146 s3.upload_file('/tmp/hello.txt', 'amzn-s3-demo-bucket', 'hello.txt')
147
148 Similar behavior as S3Transfer's upload_file() method, except that
149 argument names are capitalized. Detailed examples can be found at
150 :ref:`S3Transfer's Usage <ref_s3transfer_usage>`.
151
152 :type Filename: str
153 :param Filename: The path to the file to upload.
154
155 :type Bucket: str
156 :param Bucket: The name of the bucket to upload to.
157
158 :type Key: str
159 :param Key: The name of the key to upload to.
160
161 :type ExtraArgs: dict
162 :param ExtraArgs: Extra arguments that may be passed to the
163 client operation. For allowed upload arguments see
164 :py:attr:`boto3.s3.transfer.S3Transfer.ALLOWED_UPLOAD_ARGS`.
165
166 :type Callback: function
167 :param Callback: A method which takes a number of bytes transferred to
168 be periodically called during the upload.
169
170 :type Config: boto3.s3.transfer.TransferConfig
171 :param Config: The transfer configuration to be used when performing the
172 transfer.
173 """
174 with S3Transfer(self, Config) as transfer:
175 return transfer.upload_file(
176 filename=Filename,
177 bucket=Bucket,
178 key=Key,
179 extra_args=ExtraArgs,
180 callback=Callback,
181 )
182
183
184 @with_current_context(partial(register_feature_id, 'S3_TRANSFER'))
185 def download_file(
186 self, Bucket, Key, Filename, ExtraArgs=None, Callback=None, Config=None
187 ):
188 """Download an S3 object to a file.
189
190 Usage::
191
192 import boto3
193 s3 = boto3.client('s3')
194 s3.download_file('amzn-s3-demo-bucket', 'hello.txt', '/tmp/hello.txt')
195
196 Similar behavior as S3Transfer's download_file() method,
197 except that parameters are capitalized. Detailed examples can be found at
198 :ref:`S3Transfer's Usage <ref_s3transfer_usage>`.
199
200 :type Bucket: str
201 :param Bucket: The name of the bucket to download from.
202
203 :type Key: str
204 :param Key: The name of the key to download from.
205
206 :type Filename: str
207 :param Filename: The path to the file to download to.
208
209 :type ExtraArgs: dict
210 :param ExtraArgs: Extra arguments that may be passed to the
211 client operation. For allowed download arguments see
212 :py:attr:`boto3.s3.transfer.S3Transfer.ALLOWED_DOWNLOAD_ARGS`.
213
214 :type Callback: function
215 :param Callback: A method which takes a number of bytes transferred to
216 be periodically called during the download.
217
218 :type Config: boto3.s3.transfer.TransferConfig
219 :param Config: The transfer configuration to be used when performing the
220 transfer.
221 """
222 with S3Transfer(self, Config) as transfer:
223 return transfer.download_file(
224 bucket=Bucket,
225 key=Key,
226 filename=Filename,
227 extra_args=ExtraArgs,
228 callback=Callback,
229 )
230
231
232 def bucket_upload_file(
233 self, Filename, Key, ExtraArgs=None, Callback=None, Config=None
234 ):
235 """Upload a file to an S3 object.
236
237 Usage::
238
239 import boto3
240 s3 = boto3.resource('s3')
241 s3.Bucket('amzn-s3-demo-bucket').upload_file('/tmp/hello.txt', 'hello.txt')
242
243 Similar behavior as S3Transfer's upload_file() method,
244 except that parameters are capitalized. Detailed examples can be found at
245 :ref:`S3Transfer's Usage <ref_s3transfer_usage>`.
246
247 :type Filename: str
248 :param Filename: The path to the file to upload.
249
250 :type Key: str
251 :param Key: The name of the key to upload to.
252
253 :type ExtraArgs: dict
254 :param ExtraArgs: Extra arguments that may be passed to the
255 client operation. For allowed upload arguments see
256 :py:attr:`boto3.s3.transfer.S3Transfer.ALLOWED_UPLOAD_ARGS`.
257
258 :type Callback: function
259 :param Callback: A method which takes a number of bytes transferred to
260 be periodically called during the upload.
261
262 :type Config: boto3.s3.transfer.TransferConfig
263 :param Config: The transfer configuration to be used when performing the
264 transfer.
265 """
266 return self.meta.client.upload_file(
267 Filename=Filename,
268 Bucket=self.name,
269 Key=Key,
270 ExtraArgs=ExtraArgs,
271 Callback=Callback,
272 Config=Config,
273 )
274
275
276 def bucket_download_file(
277 self, Key, Filename, ExtraArgs=None, Callback=None, Config=None
278 ):
279 """Download an S3 object to a file.
280
281 Usage::
282
283 import boto3
284 s3 = boto3.resource('s3')
285 s3.Bucket('amzn-s3-demo-bucket').download_file('hello.txt', '/tmp/hello.txt')
286
287 Similar behavior as S3Transfer's download_file() method,
288 except that parameters are capitalized. Detailed examples can be found at
289 :ref:`S3Transfer's Usage <ref_s3transfer_usage>`.
290
291 :type Key: str
292 :param Key: The name of the key to download from.
293
294 :type Filename: str
295 :param Filename: The path to the file to download to.
296
297 :type ExtraArgs: dict
298 :param ExtraArgs: Extra arguments that may be passed to the
299 client operation. For allowed download arguments see
300 :py:attr:`boto3.s3.transfer.S3Transfer.ALLOWED_DOWNLOAD_ARGS`.
301
302 :type Callback: function
303 :param Callback: A method which takes a number of bytes transferred to
304 be periodically called during the download.
305
306 :type Config: boto3.s3.transfer.TransferConfig
307 :param Config: The transfer configuration to be used when performing the
308 transfer.
309 """
310 return self.meta.client.download_file(
311 Bucket=self.name,
312 Key=Key,
313 Filename=Filename,
314 ExtraArgs=ExtraArgs,
315 Callback=Callback,
316 Config=Config,
317 )
318
319
320 def object_upload_file(
321 self, Filename, ExtraArgs=None, Callback=None, Config=None
322 ):
323 """Upload a file to an S3 object.
324
325 Usage::
326
327 import boto3
328 s3 = boto3.resource('s3')
329 s3.Object('amzn-s3-demo-bucket', 'hello.txt').upload_file('/tmp/hello.txt')
330
331 Similar behavior as S3Transfer's upload_file() method,
332 except that parameters are capitalized. Detailed examples can be found at
333 :ref:`S3Transfer's Usage <ref_s3transfer_usage>`.
334
335 :type Filename: str
336 :param Filename: The path to the file to upload.
337
338 :type ExtraArgs: dict
339 :param ExtraArgs: Extra arguments that may be passed to the
340 client operation. For allowed upload arguments see
341 :py:attr:`boto3.s3.transfer.S3Transfer.ALLOWED_UPLOAD_ARGS`.
342
343 :type Callback: function
344 :param Callback: A method which takes a number of bytes transferred to
345 be periodically called during the upload.
346
347 :type Config: boto3.s3.transfer.TransferConfig
348 :param Config: The transfer configuration to be used when performing the
349 transfer.
350 """
351 return self.meta.client.upload_file(
352 Filename=Filename,
353 Bucket=self.bucket_name,
354 Key=self.key,
355 ExtraArgs=ExtraArgs,
356 Callback=Callback,
357 Config=Config,
358 )
359
360
361 def object_download_file(
362 self, Filename, ExtraArgs=None, Callback=None, Config=None
363 ):
364 """Download an S3 object to a file.
365
366 Usage::
367
368 import boto3
369 s3 = boto3.resource('s3')
370 s3.Object('amzn-s3-demo-bucket', 'hello.txt').download_file('/tmp/hello.txt')
371
372 Similar behavior as S3Transfer's download_file() method,
373 except that parameters are capitalized. Detailed examples can be found at
374 :ref:`S3Transfer's Usage <ref_s3transfer_usage>`.
375
376 :type Filename: str
377 :param Filename: The path to the file to download to.
378
379 :type ExtraArgs: dict
380 :param ExtraArgs: Extra arguments that may be passed to the
381 client operation. For allowed download arguments see
382 :py:attr:`boto3.s3.transfer.S3Transfer.ALLOWED_DOWNLOAD_ARGS`.
383
384 :type Callback: function
385 :param Callback: A method which takes a number of bytes transferred to
386 be periodically called during the download.
387
388 :type Config: boto3.s3.transfer.TransferConfig
389 :param Config: The transfer configuration to be used when performing the
390 transfer.
391 """
392 return self.meta.client.download_file(
393 Bucket=self.bucket_name,
394 Key=self.key,
395 Filename=Filename,
396 ExtraArgs=ExtraArgs,
397 Callback=Callback,
398 Config=Config,
399 )
400
401
402 @with_current_context(partial(register_feature_id, 'S3_TRANSFER'))
403 def copy(
404 self,
405 CopySource,
406 Bucket,
407 Key,
408 ExtraArgs=None,
409 Callback=None,
410 SourceClient=None,
411 Config=None,
412 ):
413 """Copy an object from one S3 location to another.
414
415 This is a managed transfer which will perform a multipart copy in
416 multiple threads if necessary.
417
418 Usage::
419
420 import boto3
421 s3 = boto3.resource('s3')
422 copy_source = {
423 'Bucket': 'amzn-s3-demo-bucket1',
424 'Key': 'mykey'
425 }
426 s3.meta.client.copy(copy_source, 'amzn-s3-demo-bucket2', 'otherkey')
427
428 :type CopySource: dict
429 :param CopySource: The name of the source bucket, key name of the
430 source object, and optional version ID of the source object. The
431 dictionary format is:
432 ``{'Bucket': 'bucket', 'Key': 'key', 'VersionId': 'id'}``. Note
433 that the ``VersionId`` key is optional and may be omitted.
434
435 :type Bucket: str
436 :param Bucket: The name of the bucket to copy to
437
438 :type Key: str
439 :param Key: The name of the key to copy to
440
441 :type ExtraArgs: dict
442 :param ExtraArgs: Extra arguments that may be passed to the
443 client operation. For allowed copy arguments see
444 :py:attr:`boto3.s3.transfer.S3Transfer.ALLOWED_COPY_ARGS`.
445
446 :type Callback: function
447 :param Callback: A method which takes a number of bytes transferred to
448 be periodically called during the copy.
449
450 :type SourceClient: botocore or boto3 Client
451 :param SourceClient: The client to be used for operation that
452 may happen at the source object. For example, this client is
453 used for the head_object that determines the size of the copy.
454 If no client is provided, the current client is used as the client
455 for the source object.
456
457 :type Config: boto3.s3.transfer.TransferConfig
458 :param Config: The transfer configuration to be used when performing the
459 copy.
460 """
461 subscribers = None
462 if Callback is not None:
463 subscribers = [ProgressCallbackInvoker(Callback)]
464
465 config = Config
466 if config is None:
467 config = TransferConfig()
468
469 # copy is not supported in the CRT
470 new_config = python_copy.copy(config)
471 new_config.preferred_transfer_client = "classic"
472
473 with create_transfer_manager(self, new_config) as manager:
474 future = manager.copy(
475 copy_source=CopySource,
476 bucket=Bucket,
477 key=Key,
478 extra_args=ExtraArgs,
479 subscribers=subscribers,
480 source_client=SourceClient,
481 )
482 return future.result()
483
484
485 def bucket_copy(
486 self,
487 CopySource,
488 Key,
489 ExtraArgs=None,
490 Callback=None,
491 SourceClient=None,
492 Config=None,
493 ):
494 """Copy an object from one S3 location to an object in this bucket.
495
496 This is a managed transfer which will perform a multipart copy in
497 multiple threads if necessary.
498
499 Usage::
500
501 import boto3
502 s3 = boto3.resource('s3')
503 copy_source = {
504 'Bucket': 'amzn-s3-demo-bucket1',
505 'Key': 'mykey'
506 }
507 bucket = s3.Bucket('amzn-s3-demo-bucket2')
508 bucket.copy(copy_source, 'otherkey')
509
510 :type CopySource: dict
511 :param CopySource: The name of the source bucket, key name of the
512 source object, and optional version ID of the source object. The
513 dictionary format is:
514 ``{'Bucket': 'bucket', 'Key': 'key', 'VersionId': 'id'}``. Note
515 that the ``VersionId`` key is optional and may be omitted.
516
517 :type Key: str
518 :param Key: The name of the key to copy to
519
520 :type ExtraArgs: dict
521 :param ExtraArgs: Extra arguments that may be passed to the
522 client operation. For allowed copy arguments see
523 :py:attr:`boto3.s3.transfer.S3Transfer.ALLOWED_COPY_ARGS`.
524
525 :type Callback: function
526 :param Callback: A method which takes a number of bytes transferred to
527 be periodically called during the copy.
528
529 :type SourceClient: botocore or boto3 Client
530 :param SourceClient: The client to be used for operation that
531 may happen at the source object. For example, this client is
532 used for the head_object that determines the size of the copy.
533 If no client is provided, the current client is used as the client
534 for the source object.
535
536 :type Config: boto3.s3.transfer.TransferConfig
537 :param Config: The transfer configuration to be used when performing the
538 copy.
539 """
540 return self.meta.client.copy(
541 CopySource=CopySource,
542 Bucket=self.name,
543 Key=Key,
544 ExtraArgs=ExtraArgs,
545 Callback=Callback,
546 SourceClient=SourceClient,
547 Config=Config,
548 )
549
550
551 def object_copy(
552 self,
553 CopySource,
554 ExtraArgs=None,
555 Callback=None,
556 SourceClient=None,
557 Config=None,
558 ):
559 """Copy an object from one S3 location to this object.
560
561 This is a managed transfer which will perform a multipart copy in
562 multiple threads if necessary.
563
564 Usage::
565
566 import boto3
567 s3 = boto3.resource('s3')
568 copy_source = {
569 'Bucket': 'amzn-s3-demo-bucket1',
570 'Key': 'mykey'
571 }
572 bucket = s3.Bucket('amzn-s3-demo-bucket2')
573 obj = bucket.Object('otherkey')
574 obj.copy(copy_source)
575
576 :type CopySource: dict
577 :param CopySource: The name of the source bucket, key name of the
578 source object, and optional version ID of the source object. The
579 dictionary format is:
580 ``{'Bucket': 'bucket', 'Key': 'key', 'VersionId': 'id'}``. Note
581 that the ``VersionId`` key is optional and may be omitted.
582
583 :type ExtraArgs: dict
584 :param ExtraArgs: Extra arguments that may be passed to the
585 client operation. For allowed copy arguments see
586 :py:attr:`boto3.s3.transfer.S3Transfer.ALLOWED_COPY_ARGS`.
587
588 :type Callback: function
589 :param Callback: A method which takes a number of bytes transferred to
590 be periodically called during the copy.
591
592 :type SourceClient: botocore or boto3 Client
593 :param SourceClient: The client to be used for operation that
594 may happen at the source object. For example, this client is
595 used for the head_object that determines the size of the copy.
596 If no client is provided, the current client is used as the client
597 for the source object.
598
599 :type Config: boto3.s3.transfer.TransferConfig
600 :param Config: The transfer configuration to be used when performing the
601 copy.
602 """
603 return self.meta.client.copy(
604 CopySource=CopySource,
605 Bucket=self.bucket_name,
606 Key=self.key,
607 ExtraArgs=ExtraArgs,
608 Callback=Callback,
609 SourceClient=SourceClient,
610 Config=Config,
611 )
612
613
614 @with_current_context(partial(register_feature_id, 'S3_TRANSFER'))
615 def upload_fileobj(
616 self, Fileobj, Bucket, Key, ExtraArgs=None, Callback=None, Config=None
617 ):
618 """Upload a file-like object to S3.
619
620 The file-like object must be in binary mode.
621
622 This is a managed transfer which will perform a multipart upload in
623 multiple threads if necessary.
624
625 Usage::
626
627 import boto3
628 s3 = boto3.client('s3')
629
630 with open('filename', 'rb') as data:
631 s3.upload_fileobj(data, 'amzn-s3-demo-bucket', 'mykey')
632
633 :type Fileobj: a file-like object
634 :param Fileobj: A file-like object to upload. At a minimum, it must
635 implement the `read` method, and must return bytes.
636
637 :type Bucket: str
638 :param Bucket: The name of the bucket to upload to.
639
640 :type Key: str
641 :param Key: The name of the key to upload to.
642
643 :type ExtraArgs: dict
644 :param ExtraArgs: Extra arguments that may be passed to the
645 client operation. For allowed upload arguments see
646 :py:attr:`boto3.s3.transfer.S3Transfer.ALLOWED_UPLOAD_ARGS`.
647
648 :type Callback: function
649 :param Callback: A method which takes a number of bytes transferred to
650 be periodically called during the upload.
651
652 :type Config: boto3.s3.transfer.TransferConfig
653 :param Config: The transfer configuration to be used when performing the
654 upload.
655 """
656 if not hasattr(Fileobj, 'read'):
657 raise ValueError('Fileobj must implement read')
658
659 subscribers = None
660 if Callback is not None:
661 subscribers = [ProgressCallbackInvoker(Callback)]
662
663 config = Config
664 if config is None:
665 config = TransferConfig()
666
667 with create_transfer_manager(self, config) as manager:
668 future = manager.upload(
669 fileobj=Fileobj,
670 bucket=Bucket,
671 key=Key,
672 extra_args=ExtraArgs,
673 subscribers=subscribers,
674 )
675 return future.result()
676
677
678 def bucket_upload_fileobj(
679 self, Fileobj, Key, ExtraArgs=None, Callback=None, Config=None
680 ):
681 """Upload a file-like object to this bucket.
682
683 The file-like object must be in binary mode.
684
685 This is a managed transfer which will perform a multipart upload in
686 multiple threads if necessary.
687
688 Usage::
689
690 import boto3
691 s3 = boto3.resource('s3')
692 bucket = s3.Bucket('amzn-s3-demo-bucket')
693
694 with open('filename', 'rb') as data:
695 bucket.upload_fileobj(data, 'mykey')
696
697 :type Fileobj: a file-like object
698 :param Fileobj: A file-like object to upload. At a minimum, it must
699 implement the `read` method, and must return bytes.
700
701 :type Key: str
702 :param Key: The name of the key to upload to.
703
704 :type ExtraArgs: dict
705 :param ExtraArgs: Extra arguments that may be passed to the
706 client operation. For allowed upload arguments see
707 :py:attr:`boto3.s3.transfer.S3Transfer.ALLOWED_UPLOAD_ARGS`.
708
709 :type Callback: function
710 :param Callback: A method which takes a number of bytes transferred to
711 be periodically called during the upload.
712
713 :type Config: boto3.s3.transfer.TransferConfig
714 :param Config: The transfer configuration to be used when performing the
715 upload.
716 """
717 return self.meta.client.upload_fileobj(
718 Fileobj=Fileobj,
719 Bucket=self.name,
720 Key=Key,
721 ExtraArgs=ExtraArgs,
722 Callback=Callback,
723 Config=Config,
724 )
725
726
727 def object_upload_fileobj(
728 self, Fileobj, ExtraArgs=None, Callback=None, Config=None
729 ):
730 """Upload a file-like object to this object.
731
732 The file-like object must be in binary mode.
733
734 This is a managed transfer which will perform a multipart upload in
735 multiple threads if necessary.
736
737 Usage::
738
739 import boto3
740 s3 = boto3.resource('s3')
741 bucket = s3.Bucket('amzn-s3-demo-bucket')
742 obj = bucket.Object('mykey')
743
744 with open('filename', 'rb') as data:
745 obj.upload_fileobj(data)
746
747 :type Fileobj: a file-like object
748 :param Fileobj: A file-like object to upload. At a minimum, it must
749 implement the `read` method, and must return bytes.
750
751 :type ExtraArgs: dict
752 :param ExtraArgs: Extra arguments that may be passed to the
753 client operation. For allowed upload arguments see
754 :py:attr:`boto3.s3.transfer.S3Transfer.ALLOWED_UPLOAD_ARGS`.
755
756 :type Callback: function
757 :param Callback: A method which takes a number of bytes transferred to
758 be periodically called during the upload.
759
760 :type Config: boto3.s3.transfer.TransferConfig
761 :param Config: The transfer configuration to be used when performing the
762 upload.
763 """
764 return self.meta.client.upload_fileobj(
765 Fileobj=Fileobj,
766 Bucket=self.bucket_name,
767 Key=self.key,
768 ExtraArgs=ExtraArgs,
769 Callback=Callback,
770 Config=Config,
771 )
772
773
774 def disable_threading_if_append_mode(config, fileobj):
775 """Set `TransferConfig.use_threads` to `False` if file-like
776 object is in append mode.
777
778 :type config: boto3.s3.transfer.TransferConfig
779 :param config: The transfer configuration to be used when performing the
780 download.
781
782 :type fileobj: A file-like object
783 :param fileobj: A file-like object to inspect for append mode.
784 """
785 if is_append_mode(fileobj):
786 config.use_threads = False
787 logger.warning(
788 'A single thread will be used because the provided file object '
789 'is in append mode. Writes may always be appended to the end of '
790 'the file regardless of seek position, so a single thread must be '
791 'used to ensure sequential writes.'
792 )
793
794
795 @with_current_context(partial(register_feature_id, 'S3_TRANSFER'))
796 def download_fileobj(
797 self, Bucket, Key, Fileobj, ExtraArgs=None, Callback=None, Config=None
798 ):
799 """Download an object from S3 to a file-like object.
800
801 The file-like object must be in binary mode.
802
803 This is a managed transfer which will perform a multipart download in
804 multiple threads if necessary.
805
806 Usage::
807
808 import boto3
809 s3 = boto3.client('s3')
810
811 with open('filename', 'wb') as data:
812 s3.download_fileobj('amzn-s3-demo-bucket', 'mykey', data)
813
814 :type Bucket: str
815 :param Bucket: The name of the bucket to download from.
816
817 :type Key: str
818 :param Key: The name of the key to download from.
819
820 :type Fileobj: a file-like object
821 :param Fileobj: A file-like object to download into. At a minimum, it must
822 implement the `write` method and must accept bytes.
823
824 :type ExtraArgs: dict
825 :param ExtraArgs: Extra arguments that may be passed to the
826 client operation. For allowed download arguments see
827 :py:attr:`boto3.s3.transfer.S3Transfer.ALLOWED_DOWNLOAD_ARGS`.
828
829 :type Callback: function
830 :param Callback: A method which takes a number of bytes transferred to
831 be periodically called during the download.
832
833 :type Config: boto3.s3.transfer.TransferConfig
834 :param Config: The transfer configuration to be used when performing the
835 download.
836 """
837 if not hasattr(Fileobj, 'write'):
838 raise ValueError('Fileobj must implement write')
839
840 subscribers = None
841 if Callback is not None:
842 subscribers = [ProgressCallbackInvoker(Callback)]
843
844 config = Config
845 if config is None:
846 config = TransferConfig()
847
848 new_config = python_copy.copy(config)
849 disable_threading_if_append_mode(new_config, Fileobj)
850
851 with create_transfer_manager(self, new_config) as manager:
852 future = manager.download(
853 bucket=Bucket,
854 key=Key,
855 fileobj=Fileobj,
856 extra_args=ExtraArgs,
857 subscribers=subscribers,
858 )
859 return future.result()
860
861
862 def bucket_download_fileobj(
863 self, Key, Fileobj, ExtraArgs=None, Callback=None, Config=None
864 ):
865 """Download an object from this bucket to a file-like-object.
866
867 The file-like object must be in binary mode.
868
869 This is a managed transfer which will perform a multipart download in
870 multiple threads if necessary.
871
872 Usage::
873
874 import boto3
875 s3 = boto3.resource('s3')
876 bucket = s3.Bucket('amzn-s3-demo-bucket')
877
878 with open('filename', 'wb') as data:
879 bucket.download_fileobj('mykey', data)
880
881 :type Fileobj: a file-like object
882 :param Fileobj: A file-like object to download into. At a minimum, it must
883 implement the `write` method and must accept bytes.
884
885 :type Key: str
886 :param Key: The name of the key to download from.
887
888 :type ExtraArgs: dict
889 :param ExtraArgs: Extra arguments that may be passed to the
890 client operation. For allowed download arguments see
891 :py:attr:`boto3.s3.transfer.S3Transfer.ALLOWED_DOWNLOAD_ARGS`.
892
893 :type Callback: function
894 :param Callback: A method which takes a number of bytes transferred to
895 be periodically called during the download.
896
897 :type Config: boto3.s3.transfer.TransferConfig
898 :param Config: The transfer configuration to be used when performing the
899 download.
900 """
901 return self.meta.client.download_fileobj(
902 Bucket=self.name,
903 Key=Key,
904 Fileobj=Fileobj,
905 ExtraArgs=ExtraArgs,
906 Callback=Callback,
907 Config=Config,
908 )
909
910
911 def object_download_fileobj(
912 self, Fileobj, ExtraArgs=None, Callback=None, Config=None
913 ):
914 """Download this object from S3 to a file-like object.
915
916 The file-like object must be in binary mode.
917
918 This is a managed transfer which will perform a multipart download in
919 multiple threads if necessary.
920
921 Usage::
922
923 import boto3
924 s3 = boto3.resource('s3')
925 bucket = s3.Bucket('amzn-s3-demo-bucket')
926 obj = bucket.Object('mykey')
927
928 with open('filename', 'wb') as data:
929 obj.download_fileobj(data)
930
931 :type Fileobj: a file-like object
932 :param Fileobj: A file-like object to download into. At a minimum, it must
933 implement the `write` method and must accept bytes.
934
935 :type ExtraArgs: dict
936 :param ExtraArgs: Extra arguments that may be passed to the
937 client operation. For allowed download arguments see
938 :py:attr:`boto3.s3.transfer.S3Transfer.ALLOWED_DOWNLOAD_ARGS`.
939
940 :type Callback: function
941 :param Callback: A method which takes a number of bytes transferred to
942 be periodically called during the download.
943
944 :type Config: boto3.s3.transfer.TransferConfig
945 :param Config: The transfer configuration to be used when performing the
946 download.
947 """
948 return self.meta.client.download_fileobj(
949 Bucket=self.bucket_name,
950 Key=self.key,
951 Fileobj=Fileobj,
952 ExtraArgs=ExtraArgs,
953 Callback=Callback,
954 Config=Config,
955 )