Add new top-level compression parameter

[dmcguire81]

Title

Feature to add compression parameter to override inference by file extension

Motivation

A previous PR was closed for being incompatible with the long-term API design for smart_open.open. Because the long-term goal, discussed in the linked issue is to add an enum-like compression parameter, and deprecate the ignore_ext parameter, which would be a breaking change, this is a backwards-compatible compromise that provides a clean upgrade path. Specifically, it preserves the existing ignore_ext parameter, instead adding a PendingDeprecationWarning, and makes its use mutually-exclusive with the new compression parameter, verified by comprehensive unit testing (the truth tables used to build the test suites are provided in comments for any discussion of refinement needed). On the next major version, the ignore_ext parameter can be removed and the default for compression changed to INFER_FROM_EXTENSION, since it won't be necessary to apply a MUTEX on the parameters, at that point (i.e.: lines 177-182 can just be removed).

Fixes #607.

Tests

Added test_smart_open.HandleS3CompressionTestCase. This is specific to S3 (where the mocking is the best), but could be easily extended to any other backend. However, it looked as though S3 is the go-to backend for verifying shared behavior.

Checklist

Before you create the PR, please make sure you have:

• Picked a concise, informative and complete title
• Clearly explained the motivation behind the PR
• Linked to any existing issues that your PR will be solving
• Included tests for any new functionality
• Checked that all unit tests pass

[dmcguire81]

@piskvorky please review based on design discussion

[mpenkov]

Thank you for this contribution. The changes to the library itself mostly look good. The unit tests need a bit of work. Please have a look at my comments and let me know when you're ready for another round of reviews.

[dmcguire81]

@mpenkov ready for another round of reviews

[dmcguire81]

@mpenkov @piskvorky ping

[mpenkov]

I'll take it from here. Thank you for your contribution.