Structure of v2.0 public API

[bskinn]

For now, this assumes that stdio_mgr will remain a @contextmanager-decorated function, rather than a full StdioMgr class.

stdio_mgr must be public.

IIUC the main other consideration is whether to make RandomTextIO and TeeStdin themselves public; or, to make them private but provide a public means for users to identify whether they are in use, or whether a given stdio stream is (most likely) the real one from sys.

The latter could be achieved by, e.g., a public stub superclass.

@bskinn best stab at a summary of the options:

• Keep them public
  • Advantages
    • TeeStdin was implicitly public in v1.0.x
  • Disadvantages
    • A risk here is possibly making it harder to change the API/signature of RandomTextIO/TeeStdin if anything other than optional keyword arguments are needed.
    • There is also the additional thought that would have to go into making sure the classes are semantically configured well for public use... good names, useful & documented APIs & behaviors, etc. Advantage
• Make them private
  • Advantages
    • Behavior and API become implementation detail and can be freely changed
    • No external need to carefully document or name the classes
    • Users could isinstance check on a single public class, rather than having to remember both classes
  • Disadvantages
    • No external need to carefully document or name the classes
    • Pulls TeeStdin out of ~public API, a break from v1.0.x
    • Expands the inheritance structure of the package

[bskinn]

As usual, API will be reflected both in docs and in what __init__.py pulls in.

[bskinn]

@jayvdb The more I think about this, the more it seems like everything should be private/implementation-detail except stdio_mgr and StdioManager.

Do you think that users would frequently want to use RandomTextIO/TeeStdin and their SafeClose variants much? It seems to me that relatively few would.

Separately, if I read your intent correctly based on your ideas in #4, the logic/implementation of the content teeing may change appreciably in the future anyways.

To my mind, all this argues for an aggressive expansion of what's considered private.

[bskinn]

Hm. Though, if users may want to be checking types of the mocked streams, then it I guess it makes more sense for those types to be part of the public API, with the corresponding promise that they won't be renamed/etc. in a breaking way without some notice coming from a major version bump...

[bskinn]

(Continued from this discussion on #64.)

I'm still coming to grips with the scope and granularity of what you're working towards, @jayvdb, so I suspect my vision on things is pretty incomplete. But, hazily, it seems like it would be nice to have a 'dual-level' (or 'multi-level'?) API, where, e.g., for simple cases users would just tee one/both stdin and stderr over to stdout and do direct string comparisons on actual/expect; but for complex cases, things like #65 and all of the tuple/etc. functionality of #53, #62, #64, #65, et al. would be available.

[jayvdb]

Im also working it out as I go ;-), trying to incorporate the functionality needed by various existing similar implementations, especially those which are currently limited because of the lack of proper TextIOWrapper streams (which is usually the case, including pytest's capture).

I knew about coala-utils before starting this of course, but that hasnt been a driver as it is already stable. I am now using it only as a sample re-implementation, to see where the pain points are.

Beyond the simple case, I think we need an reasonably easy solution for selecting a mix of streams to be mocked as that will be a common case.

I suspect the advanced users need to be using composition rather than simply inheritance and instantiation arguments, so that people can use our bases but extend them and implement their own 'manager' classes which has the features they need. I expect like coala-utils and the pytest plugin, they will have already built fairly advanced testing features (even though the streams are very basic StringIO) and they dont want to loose them, and don't have a reason for trying to push their features into a future stdio-mgr v3 - their existing test rig is working -- why would they invest in someone elses test rigging. To bring them into the fold, we need multiple levels, so they find a way to add the features they already have.

I do want a release soon-ish, so we cant get all the features done, but my soonish needs are all really basic usage, like the bom-open testing.