Opened 5 years ago

Closed 4 years ago

Last modified 4 years ago

#4478 task closed fixed (fixed)

Write a howto documenting endpoints

Reported by: itamar Owned by:
Priority: high Milestone:
Component: core Keywords: documentation
Cc: Branch: branches/endpoints-docs-4478-2
(diff, github, buildbot, log)
Author: exarkun, glyph Launchpad Bug:

Description

Now that we have the new feature in place, endpoints could do with some documentation for users.

Change History (13)

comment:1 Changed 5 years ago by exarkun

  • Priority changed from normal to high

comment:2 Changed 5 years ago by glyph

  • Milestone set to Twisted-10.1

For the reasons discussed on #4320 this should probably be a priority for the release.

comment:3 Changed 5 years ago by exarkun

  • Owner changed from glyph to exarkun

comment:4 Changed 5 years ago by exarkun

  • Author set to exarkun
  • Branch set to branches/endpoints-docs-4478

(In [29279]) Branching to 'endpoints-docs-4478'

comment:5 Changed 5 years ago by glyph

(In [29287]) Well, it's something. As with much Twisted documentation it's hard to come up with a sufficient amount of context. Also, there isn't really a lot you can do with an endpoint by itself...

I've documented the strports stuff under the names currently used in the #4473 branch, but this will obviously have to change if they do.

refs #4473

refs #4478

comment:6 Changed 4 years ago by jml

  • Milestone Twisted-10.1 deleted

Twisted 10.1.0 has been released. Removing this ticket from the 10.1 milestone. If you think it's severe enough to demand a follow-up release, please say so and add this ticket back to the 10.1 milestone.

comment:7 Changed 4 years ago by glyph

  • Author changed from exarkun to exarkun, glyph
  • Branch changed from branches/endpoints-docs-4478 to branches/endpoints-docs-4478-2

(In [30157]) Branching to 'endpoints-docs-4478-2'

comment:8 Changed 4 years ago by glyph

  • Keywords review added
  • Owner exarkun deleted

comment:9 follow-up: Changed 4 years ago by exarkun

  • Keywords review removed
  • Owner set to glyph
  1. clients.xhtml
    1. The sentence "An important advantage of the endpoint API ..." doesn't entirely make sense in contenxt. Nothing else has been introduced to have advantages over. One might suppose that this is an advantage over using sockets directly, but I don't think that's actually the intent here. I would suggest changing the word "advantage" to "feature".
    2. "For more information on different ways you can listen for incoming connections, see the documentation for the endpoints API." should be talking about connecting instead of listening.
  2. endpoints.xhtml
    1. "For example, a very simple 30-second timeout could be

implemented like this:" - does it really get to be this simple? What about canceling the delayed call?

  1. The conclusion is a bit weak. But don't let that stop you from merging the branch. We can always beef it up later.

Please merge when these are addressed to your satisfaction.

comment:10 Changed 4 years ago by exarkun

Also, news fragment.

comment:11 Changed 4 years ago by glyph

  • Resolution set to fixed
  • Status changed from new to closed

(In [30269])
Add documentation for endpoints API.

Author: glyph

Reviewer: exarkun

Fixes: #4478

This adds narrative documentation for twisted.internet.endpoints, as well as updating the existing documentation for writing clients and servers to point to the shiny new APIs.

comment:12 in reply to: ↑ 9 Changed 4 years ago by glyph

Replying to exarkun:

The sentence "An important advantage of the endpoint API ..." doesn't entirely make sense in contenxt. Nothing else has been introduced to have advantages over. One might suppose that this is an advantage over using sockets directly, but I don't think that's actually the intent here. I would suggest changing the word "advantage" to "feature".

I tried to re-work the paragraph to actually describe the feature, rather than how you use the feature, and without reference to the 'old' API. I also updated some other mentions of the 'old' API to refer to the 'low-level' API instead.

"For more information on different ways you can listen for incoming connections, see the documentation for the endpoints API." should be talking about connecting instead of listening.

Fixed, good catch.

"For example, a very simple 30-second timeout could be implemented like this:" - does it really get to be this simple? What about canceling the delayed call?

I thought about this a bit, and yeah, I think it does actually get to be that simple. If you're writing a trial unit test, you care because of the dirty reactor error, but that's not what this documentation is about. If you cancel a Deferred which has been called back already, you don't get an exception. Consider:

>>> from twisted.internet.defer import Deferred
>>> d = Deferred()
>>> d.callback(1)
>>> d.cancel()
>>> del d

The conclusion is a bit weak. But don't let that stop you from merging the branch. We can always beef it up later.

I agree, but I think that nailing down what about it is weak and trying to come up with a better narrative is potentially a big change, maybe even leading into a separate document. Maybe that document is about endpoint type plugins. Let's talk about it more and file a follow-up ticket when we have a good idea of what a strong finish for this might be :).

Also, news fragment.

Done.

Please merge when these are addressed to your satisfaction.

Done.

comment:13 Changed 4 years ago by <automation>

  • Owner glyph deleted
Note: See TracTickets for help on using tickets.