Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation of put_object is confusing #4126

Open
debugger-zhang opened this issue May 14, 2024 · 3 comments · May be fixed by boto/botocore#3177
Open

Documentation of put_object is confusing #4126

debugger-zhang opened this issue May 14, 2024 · 3 comments · May be fixed by boto/botocore#3177
Labels
documentation This is a problem with documentation. needs-review p3 This is a minor priority issue s3

Comments

@debugger-zhang
Copy link

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

@debugger-zhang debugger-zhang added documentation This is a problem with documentation. needs-triage This issue or PR still needs to be triaged. labels May 14, 2024
@tim-finnigan tim-finnigan self-assigned this May 14, 2024
@tim-finnigan tim-finnigan added the investigating This issue is being investigated and/or work is in progress to resolve the issue. label May 14, 2024
@tim-finnigan tim-finnigan linked a pull request May 14, 2024 that will close this issue
@tim-finnigan
Copy link
Contributor

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.

@tim-finnigan tim-finnigan added p3 This is a minor priority issue closing-soon This issue will automatically close in 4 days unless further comments are made. s3 and removed investigating This issue is being investigated and/or work is in progress to resolve the issue. needs-triage This issue or PR still needs to be triaged. labels May 14, 2024
@debugger-zhang
Copy link
Author

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 tim-finnigan added investigating This issue is being investigated and/or work is in progress to resolve the issue. and removed closing-soon This issue will automatically close in 4 days unless further comments are made. labels May 15, 2024
@tim-finnigan
Copy link
Contributor

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)

@tim-finnigan tim-finnigan added needs-review and removed investigating This issue is being investigated and/or work is in progress to resolve the issue. labels May 15, 2024
@tim-finnigan tim-finnigan removed their assignment May 22, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation This is a problem with documentation. needs-review p3 This is a minor priority issue s3
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants