Document that s3 upload_fileobj closes the file obj

[mdavis-xyz]

When I look at the documentation for functions like upload_fileobj, it's not clear that boto3 will close the file for me.

I have a use case where I have a zip file in a BytesIO, I want to upload it and unzip it.
I assumed boto wouldn't close the file for me, but it does.
That's fine, since the code unzipping this won't close it, so I can just swap the order.

But the documentation should clarify what the behavior is, right there where it explains that the argument is a file-like object.

e.g.

Fileobj (a file-like object) -- A file-like object to upload. At a minimum, it must implement the read method, and must return bytes. This function will have .close() called on it.

[tim-finnigan]

Hi @mdavis-xyz thanks for reaching out. This was reported awhile ago in another issue (#929) and an issue was created in the s3transfer repository to address it: boto/s3transfer#80. I’m going to close this as a duplicate and we can continue to track this in the s3transfer issue.

[github-actions]

⚠️COMMENT VISIBILITY WARNING⚠️

Comments on closed issues are hard for our team to see.
If you need more assistance, please either tag a team member or open a new issue that references this one.
If you wish to keep having a conversation with other community members under this issue feel free to do so.

[mdavis-xyz]

@tim-finnigan I don't think this ticket should be closed.

The issue is that the documentation for boto3 does not mention an unintuitive behavior of boto3. That's still an issue. Those other Github issues for other repositories won't fix that doc issue for this repository.

As an end user it has never been clear to me what the difference is between botocore, s3transfer and boto3. (Perhaps that's the doc change that's required?) I don't think it's reasonable to assume that users will think to look deep into the docs of 2 dependencies of boto3 to find this behavior. But if they did, they still wouldn't find it, because that's not what those other issues are for.

That 80 issue in botocore has remained open for half a decade. I don't think that's going to change any time soon. It's not even clear what that issue is about. (is it about changing the docs to describe the file closing behavior, or changing the behavior to not close the file?)

If I submit a PR to just add one sentence to the boto3 docs, will you accept it?

[tim-finnigan]

Hi @mdavis-xyz thanks for following up. I brought this up for discussion with the team and they agreed that a short reference to this behavior could be added to the documentation if you want to create a PR. There is still some debate over whether the s3transfer issue should be considered a bug. But someone did share a workaround here in the comments.