Re: [Twisted-Python] doc bloat
As a Twisted API users, I don't find a big problem the fact that __repr__ docstring is presented by pydoctor together with the other method, As a Twisted contributor, I don't like when I have to copy/paste docstring from an interface or from an inherited class ... or too explicity state that the type of None is NoneType... and then to add a link to it :) As a first approximation, I think we could ask twistedchecker to stop enforcing docstring requirements for objects directly matching a private naming pattern. Is there a ticket/issue for that? What does `stop enforcing docstring requirements` mean? I think that docstring are important, and testing code or private methods is still code which should be maintained and it should have docstrings, but it would be nice not to ask for strict @param @type @return @rtype. --- +1 for getting serious about twistedcker ... I would be happy to help with twistedchecker, as well as with the other automated tools. What do you say if we put all problems/issues/comments here https://github.com/twisted/twistedchecker/issues and have 2 or 3 people who can decide if an issues is accepted, or help define the right behaviour or reject it and then also review the pull requests. Right now there are many undecided or not tagged tickets, and I don't know which one is a real problem or not. One important requirement to move things forward is to provide quick feedback, both for the initial issue report and the review. Waiting months to get feedback from a patch is not fun and is a sign that core developers don't care about the newly proposed changes. -- +1 for getting serious about the other code checkers: pyflakes and pydoctor. Right now, is a PITA to run all these tools on your local computer ... Cheers -- Adi Roiban ___ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
Re: [Twisted-Python] doc bloat
On 10:02 am, a...@roiban.ro wrote: As a Twisted API users, I don't find a big problem the fact that __repr__ docstring is presented by pydoctor together with the other method, As a Twisted contributor, I don't like when I have to copy/paste docstring from an interface or from an inherited class ... I hate it when people do this, too. I never want anyone to do this. When I review changes in which this appears, I ask the author to change the submission to include useful, non-redundant documentation instead. The coding standard doesn't explicitly say that you should not copy the docstring from an implementation to an interface - but this is a good example of the kind of thing our documentation can't be expected to cover. Copying an interface docstring to an implementation is just one of the many possible bad practices a developer could engage in; a list of all possible bad practices would make the developer documentation infinitely long. To the larger issue, I think the most productive thing to do would be to actually look at our code base and see if there are glaring examples of useless documentation. If we can generalize from these examples to a rule, we can add that rule to the project policy (preferably encoded in a tool, not as prose in the developer documentation). I'm a little bit tempted to agree with the `__repr__` case. People who are reading the API documentation might not be put off by documentation for these methods but are they helped in any way? I think that most of the time they probably aren't. I'm basing this on times I can recall having written a `__repr__` docstring and how I had to struggle to put useful words into that docstring instead of pointless boilerplate. I still think it would be good to collect a bunch of actual `__repr__` docstrings from Twisted and see if such evidence supports this conclusion. or too explicity state that the type of None is NoneType... and then to add a link to it :) It sounds like there's agreement on this point, at least. For what it's worth, this seems uncontroversial to me: the type of `None` is `NoneType` and the only instance of `NoneType` is `None`. Documenting one or the other conveys all possible information there is to convey so documenting one should be enough. Even if we wanted the rendered version of the documentation for this case to be redundant, pydoctor can synthesize that redundancy - it doesn't need the source material to be redundant. As a first approximation, I think we could ask twistedchecker to stop enforcing docstring requirements for objects directly matching a private naming pattern. Is there a ticket/issue for that? What does `stop enforcing docstring requirements` mean? I think that docstring are important, and testing code or private methods is still code which should be maintained and it should have docstrings, but it would be nice not to ask for strict @param @type @return @rtype. Eh. Test code has to be maintained just like anything else. As the de facto specification for most features, it's perhaps (but only perhaps) more important to have everything clearly documented in a test suite. I think that requiring parameter and return type documentation in the test suite is a very good thing. However, requiring the same degree of documentation for *all* code may not be necessary. If a test method defines a simple nested function, perhaps that doesn't need a docstring. This is another thing we could inspect the current Twisted codebase for. Are there lots of useless docstrings on nested function definitions purely for the sake of twistedchecker? Or are there undocumented nested functions that are actually a little bit difficult to understand on their own? Jean-Paul --- +1 for getting serious about twistedcker ... I would be happy to help with twistedchecker, as well as with the other automated tools. What do you say if we put all problems/issues/comments here https://github.com/twisted/twistedchecker/issues and have 2 or 3 people who can decide if an issues is accepted, or help define the right behaviour or reject it and then also review the pull requests. Right now there are many undecided or not tagged tickets, and I don't know which one is a real problem or not. One important requirement to move things forward is to provide quick feedback, both for the initial issue report and the review. Waiting months to get feedback from a patch is not fun and is a sign that core developers don't care about the newly proposed changes. -- +1 for getting serious about the other code checkers: pyflakes and pydoctor. Right now, is a PITA to run all these tools on your local computer ... Cheers -- Adi Roiban ___ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
Re: [Twisted-Python] doc bloat
On Dec 2, 2014, at 20:05, exar...@twistedmatrix.com wrote: Are there lots of useless docstrings on nested function definitions purely for the sake of twistedchecker? Or are there undocumented nested functions that are actually a little bit difficult to understand on their own? twistedchecker does not presently require nested function definitions to have docstrings. I recently merged a fix to an incongruity where it was requiring this of classes defined within functions: https://github.com/twisted/twistedchecker/commit/4af4e97f99d6e5f683b65272a8dbe7bce2087aa7. So this one, at least, we can cross off for the future :). -glyph ___ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
Re: [Twisted-Python] Python Twisted Questions
On Dec 2, 2014, at 23:30, Adam a...@dormchatapp.com wrote: I assume you're using this tutorial? http://www.raywenderlich.com/3932/networking-tutorial-for-ios-how-to-create-a-socket-based-iphone-app-and-server http://www.raywenderlich.com/3932/networking-tutorial-for-ios-how-to-create-a-socket-based-iphone-app-and-server It is unfortunate that this has not been updated with better information, it seems to confuse a lot of people making iOS applications ;). 1. Please find attached Python script. We have integrated the Twisted framework with iOS for chat module. Attached is our Python demo code in which we have implemented this. The issue is when we try to connect with the server through the terminal, we are getting the complete correct response without any error. But when it was integrated on the iOS app, data is getting received in chunks (i.e. if data exceeds 1366 bytes or above in json size it comes in pieces which creates a problem when sending and receiving chats) This is a frequently asked question: https://twistedmatrix.com/trac/wiki/FrequentlyAskedQuestions#Whyisprotocol.dataReceivedcalledwithonlypartofthedataIcalledtransport.writewith https://twistedmatrix.com/trac/wiki/FrequentlyAskedQuestions#Whyisprotocol.dataReceivedcalledwithonlypartofthedataIcalledtransport.writewith In other words, if you want a message-oriented protocol, you can't just use dataReceived. For sending short JSON structures back and forth, line-delimited data structures are a reasonable choice. On the Twisted side, you can use twisted.protocols.basic.LineReceiver, and override lineReceived instead of dataReceived. On the iOS side, you need a radically different structure for buffering your input; you can't just stuff it into a buffer on the stack. One quick hacky way to do this would be to give your object a NSString bufferString instance variable, and do bufferString = [bufferString stringByAppendingString: [[NSString alloc] initWithBytes:buffer length:len encoding:NSASCIIStringEncoding]]; NSArray* lines = [bufferString componentsSeparatedByString: @\r\n];, bufferString = [lines lastObject];, then loop over the other items in lines. Keep in mind you also need to do this for output; as you send output to the server, you may not be able to send all of it at once, so you need to keep a buffer, and keep track of how much you've written, etc. Or you could just build Python into your app on iOS and run Twisted in there. If you manage to get that working be sure to let us know how it goes :-). I am lead to believe that http://omz-software.com/pythonista/ contains a template for at least getting the Python runtime going... -glyph___ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
