Comments (24)
@tomprince set owner to @wallrj |
---|
Taking this out of review, as there isn't really anything actionable in here to review.
from twisted.
@puzzlement set owner to edsuom |
---|
from twisted.
@glyph set owner to @khorn |
---|
Here's hoping that you can do something with this shortly after the Sphinx conversion...
from twisted.
Automation removed owner |
---|
from twisted.
@wallrj commented |
---|
In ticket:5596:names-examples-tests-5596.patch Download
- Added tests for consistent USAGE documentation and command line error reporting
- Added tests for standard python shebang line and that the script is executable.
I copied and modified the Nevow example testing mixin mentioned above.
Maybe the same tests can be re-used on other examples.
from twisted.
@wallrj commented |
---|
(In [37383]) Branching to 'testable-examples-84'
from twisted.
@wallrj commented |
---|
(In [37384]) some new twisted.names example tests for discussion. refs #11340
from twisted.
@tomprince commented |
---|
That is a very well thought out document. Thanks.
- "example code should be a complete working example suitable for copying and pasting and running by the reader"
- Should it also be cross platform? Or should there be platform specic examples? eg can an example refer to /etc/hosts
I think it will depend on the examples.systemd
examples will clearly be platform specific. Perhaps ideally, examples of cross-platform functionality will be cross-platform. But, clearly, that shouldn't be a reason for removing an example. And, I think it doesn't hurt to have some platform-specific examples of cross-platform functionality, in addition to cross-platform examples.
- "example code should be short"
- How short? In terms of lines? Or in terms of the number of top level fuctions and classes? Perhaps an example of a too long example.
I'm not sure if there is a good single measure. Those are both reasonable hints. Perhaps some measure of complexity, or extraneous complexity would be good.
- "example code should be commented very extensively"
- Does this include docstrings?
Yes- Does this include epytext style API docs in docstrings?
Maybe? I think this might depend on a case-by-case basis.
Can too many comments be distracting in a simple example?
Probably.
- "example code should exhibit 'best practice'"
- Should we identify
yes
remove examples which refer to old deprecated APIs?
no. As glyph has commented elsewhere, we don't want to remove documentation or tests for deprecated things until that functionality is actually removed. People may still encounter those APIs, and having examples to learn how they are to be used is useful for that purpose.
What is best practice? I guess most Twisted core devs will agree on most things, but are there any controversial practices eg inlineCallbacks?
I think currently this is largely an oral tradition (couting IRC as oral :)). What there is is encoded in the coding-standard and other policy documents. It would be good to capture more of it.
Can examples ever use, or suggest using external libraries? Eg treq, Nevow, ampoule, tx??? etc. If those external libraries are considered best practice? I think its quite common for people to be directed to better external alternatives eg treq vs Agent or wokel?? vs twisted.words??
<tomprince> dreid: Fetching webpages is the point of the client side of twisted web. Saying, "if you want to get webpages, go use treq", while currently the best answer and potentially a reasonable stance to take, isn't the stance twisted wants to take in the long run, in my opinion.
<glyph> tomprince: hi, yes. treq is license-compatible though, if you want to move things between them you can.
<tomprince On the other hand, I'm not sure if the requst like api that treq has, is the api that twisted wants to expose.
<tomprince> I think a similar argument could be made for parts of klein.
<tomprince> glyph: Sure. I don't want to step on someones toes, though.
<glyph> tomprince: right, so treq and klein have a more rapid release cycle and fewer compatibility guarantees so they can experiment and evolve
<glyph> tomprince: when it looks right it can happily move into twisted :)
<dreid> tomprince: I don't disagree that a higher level API for an HTTP client should be in Twisted. I just have no immediate plans to propose treq as that higher level API.
<glyph> tomprince: You've got basically the right idea but there's no need to rush.
<glyph> I mean, no need to lag either; if you think you have an appropriate high-level request API taking ideas and possibly code from treq, by all means submit it for review.
<glyph> But I don't think there's any need to worry if things continue as they are.
from twisted.
@exarkun commented |
---|
We also want to check code from the howtos (some of which might be incomplete snippets). Arguably, we probably want to turn a bunch of the examples into howtos at some point.
I'd like to emphasize this. I think we actually want to turn all the examples into howtos. An example with narration is vastly more educational than an example in a void.
from twisted.
@wallrj commented |
---|
Replying to exarkun:
We should resolve this ticket with a plan about how to write testable examples. Then, indeed, there can be many more tickets for replacing (which may not actually mean deleting and rewriting in all cases, existing examples that can be reformed should be) existing examples with tested equivalents.
I've started a new Wiki page with the outlines of a plan.
There is also a branch where I added some further tests for the twisted.names examples.
- log:branches/testable-examples-84
Before I go any further I'd appreciate a review of the plan.
Tell me which parts of the plan make sense, and I will create corresponding tickets where the discussion can continue.
Other parts of the plan I will refine or ditch, based on feedback.
from twisted.
@tomprince commented |
---|
Some other comments:
doc/historic/
should be append only, so we don't want to run linter's on it.find
isn't portable. It would be better to extendtwistedchcker
to run on arbitrary directories, or something.- We also want to check code from the howtos (some of which might be incomplete snippets). Arguably, we probably want to turn a bunch of the examples into howtos at some point.
from twisted.
@tomprince commented |
---|
Some comments on the code in the branch (which should eventually be attached to a separate ticket:
-
positionalArgCount
needs an@ivar
.- But, I'm not sure this can be made generic. Some commands may take an arbitrary number of options and some may do further checks on the options.
-
I like the unit tests. But, we should figure out some way to test that
fakeGetHostByName
behaves enough likegetHostByName
to serve as a fake. CallinggetHostByName
is the point of the example, so by patching it out, we avoid testing what is essentially the most important part of the example.Buildbot has [https://github.com/buildbot/buildbot/blob/master/master/buildbot/test/util/interfaces.py something].
from twisted.
@khorn commented |
---|
Replying to exarkun:
We also want to check code from the howtos (some of which might be incomplete snippets). Arguably, we probably want to turn a bunch of the examples into howtos at some point.
I'd like to emphasize this. I think we actually want to turn all the examples into howtos. An example with narration is vastly more educational than an example in a void.
One way of handling this would be to move all example code out of the howto documents into separate python files, for ease of testing. Then pull relevant parts of the code (functions, classes, line number ranges, etc) into the howto documents for rendering into HTML. This might make things a bit more difficult for HOWTO authors, however, as they would have to be looking at two different files when writing up their docs.
Lore can only do this by line number, though IIRC there is a ticket for other types of includes. (aha - #11558)
Sphinx can do this, but obviously we haven't switched over to Sphinx at this point in time.
In any case, I'm really only talking about long-term plans here. Nothing that should delay or derail this ticket.
from twisted.
@exarkun commented |
---|
Lots of existing howtos already do this. I don't think there's much (if any) deficiency in the current tool support.
from twisted.
@wallrj commented |
---|
Thanks for all the feedback. I've started creating some separate tickets and added links to the plan:
I'll do more later.
from twisted.
spiv commented |
---|
#!html
<pre>
Hmm, yeah, that could help -- but see also #86. Twisted
currently causes lots of spurious warnings from pychecker,
so it'd be hard to easily tell whether an example is broken,
or is just importing code that triggers false positives.
</pre>
from twisted.
@exarkun commented |
---|
#!html
<pre>
doctests would be the best way to deal with this problem, I think.
</pre>
from twisted.
spiv commented |
---|
#!html
<pre>
We occasionally break example code with new releases,
because we don't have any tests that verify that the example
code works. I'm not sure how to fix this, but it would be
nice to figure out a way to do it.
</pre>
from twisted.
@jml commented |
---|
#!html
<pre>
Perhaps just running pychecker over the examples would be a
good start?
</pre>
from twisted.
@glyph commented |
---|
This code might serve as a good example, or at least, an example: http://divmod.org/trac/browser/trunk/Nevow/nevow/test/test_howtolistings.py
from twisted.
@khorn commented |
---|
Even better than a plan would be a plan plus an actual example of a test harness for a particular example or set of examples.
from twisted.
binjured commented |
---|
Just to clarify, we are now looking to replace broken/stale code with tested-first examples. I don't think a ticket that addresses tests for all sample code is very useful (or likely to be maintained properly) in the first place, so it'd be nice if we could close this.
from twisted.
@exarkun commented |
---|
We should resolve this ticket with a plan about how to write testable examples. Then, indeed, there can be many more tickets for replacing (which may not actually mean deleting and rewriting in all cases, existing examples that can be reformed should be) existing examples with tested equivalents.
from twisted.
@exarkun commented |
---|
Well, let me update the link glyph posted, then:
from twisted.
Related Issues (20)
- Change documentation for optional dependency SOAPpy to SOAPpy-py3 HOT 6
- Remove the soap code
- `twisted.internet.test.test_tcp.AbortConnectionTests_*Tests.test_fullWriteBuffer` test timeout on macOS HOT 13
- TwistedWeb ReverseProxyResource example has string not bytes as third argument
- Setup benchmarks using Codspeed.io HOT 6
- Speed up twisted.web server, part 2 of N
- Deprecate t.w.h.HTTPClient HOT 4
- t.w.h.HTTPClient parses Content-Length laxly HOT 1
- disttrial / `trial -j` should support debug prints
- `twisted.python.test.test_sendmsg.SendmsgTests.test_sendSubProcessFD` is flaky HOT 2
- Deprecation docs should use NEXT placeholders
- Improve defer.inlineCallbacks tests
- twisted.web generates deprecation warnings internally HOT 4
- Expand benchmarks to run on PyPy as well HOT 2
- ``twisted.python.code`` package proposal HOT 7
- Performance benchmarks for Deferreds
- Instantiating multiprocessing.SimpleQueue() from an imported package fails unless SimpleQueue() is instantiated inside Twisted application first HOT 9
- http logger should respect the encoding of its log outputs HOT 2
- Update twisted.words.protocol.irc to use IRCv3 HOT 3
- IndexError due to empty args in OpenSSL.SSL.ZeroReturnError handling in Twisted HOT 3
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from twisted.