file_upload docs inaccurate?

[aiqc]

Describe the issue

The docs state:

:param object_name: S3 object name. If not specified then file_name is used

However, if I don't provide an object_name, it errors with:

TypeError: upload_file() missing 1 required positional argument: 'Key'

So it seems like both the name and required state are wrong.

It should also be explained that key includes bucket folders

---

Links

https://boto3.amazonaws.com/v1/documentation/api/latest/guide/s3-uploading-files.html

[aiqc]

On one hand, the quickstart uses boto3.resource('s3')
https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html#using-boto3

On the other hand, the actual s3 docs use boto3.client('s3')
https://boto3.amazonaws.com/v1/documentation/api/latest/guide/s3-uploading-files.html

As a new/returning user, I don't know which method I should be using.

[RyanFitzSimmonsAK]

Hi @aiqc, thanks for reaching out. There's a few different things here, so I'll address them one at a time.

The docs state:

:param object_name: S3 object name. If not specified then file_name is used

However, if I don't provide an object_name, it errors with:

TypeError: upload_file() missing 1 required positional argument: 'Key'

The documentation you're referencing is referring to the function shown in the user guide. If S3 object_name was not specified, use file_name is a documentation comment for the line immediately following it. The actual operations provided by Boto3 are upload_file and upload_fileobj. The pages I've linked are for individual operations, and contain more detail about syntax and other nuances.

As a new/returning user, I don't know which method I should be using.

Resources are an object-oriented abstraction of AWS operations. I'd recommend you read this page of the user guide for more information. In this case, using resources is equivalent to using the client. However, I will mention that resources are feature-frozen, and won't be receiving new service features.

The actual choice you have here is using upload_file or put_object. Both of these upload a file to an S3 bucket. put_object has a high level of configurability. upload_file is a more straightforward operation, and utilizes TransferConfig.

Hope that helps, and let me know if you have any other questions. This turned into more of a guidance issue, so I'm going to turn this into a discussion.

[RyanFitzSimmonsAK]

@github-actions proposed answer