Documentation of put_object is confusing

[debugger-zhang]

Describe the issue

See here: https://github.com/boto/botocore/blob/8b29f58b6f09935e5ec83f4adade36e81643d32f/botocore/data/s3/2006-03-01/examples-1.json#L1645
This renders:

response = client.put_object(
    Body='c:\HappyFace.jpg',
    Bucket='examplebucket',
    Key='HappyFace.jpg',
    Tagging='key1=value1&key2=value2',
)

print(response)

The description is "The following example uploads an object. The request specifies optional object tags. The bucket is versioned, therefore S3 returns version ID of the newly created object." However, the code does not update a file to S3. Instead, it create a file HappyFace.jpg with content is literally "c:\HappyFace.jpg".

Compare https://boto3.amazonaws.com/v1/documentation/api/latest/guide/s3-uploading-files.html where a Python file object is created before passed to boto3.

Links

https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3/client/put_object.html

[Tim Finnigan]

Thanks for highlighting this issue, since the example is in botocore I went ahead and created a PR there (boto/botocore#3177) to address this. It looks like just removing the c:\ will fix the example and make it consistent with other examples on that page.

[debugger-zhang]

Thanks for highlighting this issue, since the example is in botocore I went ahead and created a PR there (boto/botocore#3177) to address this. It looks like just removing the c:\ will fix the example and make it consistent with other examples on that page.

I do not believe this is enough. This is another example:

response = client.put_object(
    Body='HappyFace.jpg',
    Bucket='examplebucket',
    Key='HappyFace.jpg',
)

print(response)

It is also confusing since the code does not upload a file from local disk; instead it created a file in S3 with the text "HappyFace.jpg" as content.

[Tim Finnigan]

Ok although the PR addresses the inconsistency in that example, the issue remains where the examples may be misleading. Probably something like this is better:

import boto3

client = boto3.client('s3')

with open('HappyFace.jpg', 'rb') as file:
    response = client.put_object(
        Body=file.read(),
        Bucket='examplebucket',
        Key='HappyFace.jpg',
    )

print(response)