[Twisted-Python] Endpoint composition syntax

[Glyph Lefkowitz]

> On Oct 13, 2016, at 12:47 PM, Tom Prince <tom.prince at ualberta.net> wrote:
> 
> > This applies more generally; no need for any weird hacks.  Any 'new' plugin could just opt in to a different syntax; we can just look up until the first ':'; we just need to define a new interface for a new syntax.
> 
> I don't think that this provides a good user experience.
> 
> 1) There are existing endpoints that want nestable endpoints, so either
>     a) They don't change, somewhat defeating the purpose of having a new syntax (or cluttering the endpoint namespace with less than useful endpoints).

We already have this problem, and we will need to do a doc cleanup / consolidation / deprecation pass soon.  (see: tcp, tcp6, host, ssl, tls...)

>     b) They change incompatibility, defeating the purpose of trying to maintain backwards compatability.

As you've noticed, we may have several potential "outs" to have practically-compatible parsing syntaxes; the real problem is the internal factoring of the parsing APIs rather than the syntax.

> 2) As user, I need to learn which endpoints support the new syntax, thus potentially needing to know both methods of quoting and switch between them as appropriate.

As a user you're going to need to read the parameter documentation anyway; learning about new syntax is not much different than learning about a new parameter.  And you may not realize there _is_ a syntax; most configuration of this type is just copying and pasting a reasonable-looking example.  Not to say that we should be spuriously incompatible for those who have learned the rules, but the only rule to learn at this point is ": separates arguments, \ escapes :".  We could add one more rule without unduly stressing the cognitive burden of the endpoint system.

> There are a couple of possible ways around this, without requiring a weird hack.
> - I wonder how many endpoints strings have ever been written whose value starts with any of `[` `(` or `{`? I suspect that the number might in fact be 0. In which case, although the change is technically incompatible, in practice it wouldn't be.
> - Alternatively, we could deprecate an unquoted [, (, { at the beginning of a value, and then after a suitable deprecation period (perhaps additionally a release where it is just an error), we could repurpose one of them to act as quoting (leaving the other two for future extensiblity).

I suspect that this would be overkill here; we also have other options, like '(: :)', which would be totally compatible (there are no _arguments_ anywhere presently named "(").

-g