Document that s3 upload_fileobj closes the file obj

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.

[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?

[matt-telstra]

Where should I put the comments?

Because Boto3 is programmatically generated from the service definition files, I find it incredibly hard to navigate the codebase and find out where anything is, or how it works.