[Twisted-Python] Using SerialPort with t.a.s.Application
Hi! In our project, we accumulate data from various sources. Some of them are connected via serial line (e.g. a GPS receiver and a weather station). I'd like to run the application with twistd. But it looks as if SerialPort does not really fit into this framework. It does not implement IService, so `my_serial_port.setServiceParent(collection)` does not work. Is there any technical reason that SerialPort does not implement IService? Could you suggest a workaround for this problem (other than dumping t.a.s.Application ;-))? Best regards, Albert -- Albert Brandl Weiermayer Solutions GmbH | Abteistraße 12, A-4813 Altmünster phone: +43 (0) 720 70 30 14 | fax: +43 (0) 7612 20 3 56 web: http://www.weiermayer.com
On Fri, 2011-01-28 at 09:29 +0100, Albert Brandl wrote:
Hi!
In our project, we accumulate data from various sources. Some of them are connected via serial line (e.g. a GPS receiver and a weather station).
I'd like to run the application with twistd. But it looks as if SerialPort does not really fit into this framework. It does not implement IService, so `my_serial_port.setServiceParent(collection)` does not work.
Is there any technical reason that SerialPort does not implement IService? Could you suggest a workaround for this problem (other than dumping t.a.s.Application ;-))?
One way to do this, is using t.a.i.GenericClient to hook up the device to the protocol. This is also a Service that can be hooked up to an Application. Unfortunately, it uses the now deprecated connectWith method on a reactor, and therefore GenericClient has been deprecated as well. exarkun suggested a new FileDescriptorClient that might use the reactor's addReader and addWriter methods. -- ralphm
On Fri, 2011-01-28 at 09:29 +0100, Albert Brandl wrote:
I'd like to run the application with twistd. But it looks as if SerialPort does not really fit into this framework. It does not implement IService, so `my_serial_port.setServiceParent(collection)` does not work.
Just implement your own service - subclass t.a.s.Service, write your own startService and stopService methods that start and stop the serial port.
Is there any technical reason that SerialPort does not implement IService?
The TCP port doesn't implement IService either... A service is supposed to be something you can start and stop, and encapsulates a self-contained piece of business logic. The purpose is both deployment and ease of regression testing. So maybe your service starts both a webserver and a serialport, because it requires both -- which is why mostly you should just implement your own service classes. -Itamar
On Fri, Jan 28, 2011 at 7:25 AM, Itamar Turner-Trauring <itamar@itamarst.org
wrote:
A service is supposed to be something you can start and stop, and encapsulates a self-contained piece of business logic.
-Itamar
This or something very much like it should be in the Twisted Glossary. Kevin Horn
On Fri, Jan 28, 2011 at 10:38 AM, Kevin Horn <kevin.horn@gmail.com> wrote:
On Fri, Jan 28, 2011 at 7:25 AM, Itamar Turner-Trauring < itamar@itamarst.org> wrote:
A service is supposed to be something you can start and stop, and encapsulates a self-contained piece of business logic.
-Itamar
This or something very much like it should be in the Twisted Glossary.
I'd love to see concise, human-readable explanations for all of Twisted's concepts! It's on the list, anyway...
Kevin Horn
_______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
On Jan 28, 2011, at 10:38 AM, Kevin Horn wrote:
On Fri, Jan 28, 2011 at 7:25 AM, Itamar Turner-Trauring <itamar@itamarst.org> wrote:
A service is supposed to be something you can start and stop, and encapsulates a self-contained piece of business logic.
-Itamar
This or something very much like it should be in the Twisted Glossary.
Kevin Horn
The whole idea of a glossary concerns me a little bit. One way I frequently see it done is vague little snippets of text like this, and I don't like that. Not to say that Itamar's answer to this particular question was incorrect or inappropriate, I just wouldn't want to see this enshrined as the official, central definition. However, Twisted does have its own jargon and a dictionary to help the novice parse it would be a good thing. What I'd really like to see in this regard is to make sure that every "jargon term" is linked straight to API documentation, since we've gone to some trouble to make our jargon match the names used in code as closely as possible*. In this case, <http://twistedmatrix.com/documents/10.2.0/api/twisted.application.service.IS...>. If the API documentation is not sufficient (which in this case it may well not be), let's make the API documentation sufficient. Don't fortify it with a redundant official glossary listing that has to be maintained in parallel and updated in synch with the API docs. Thoughts? *: The one exception being talk of Deferreds which have 'fired' or 'failed', when the methods are called 'callback' and 'errback'. I think this points to a weakness in the API naming though, and we should eventually change those names to match the jargon.
On Fri, Jan 28, 2011 at 1:33 PM, Glyph Lefkowitz <glyph@twistedmatrix.com>wrote:
On Jan 28, 2011, at 10:38 AM, Kevin Horn wrote:
On Fri, Jan 28, 2011 at 7:25 AM, Itamar Turner-Trauring < itamar@itamarst.org> wrote:
A service is supposed to be something you can start and stop, and encapsulates a self-contained piece of business logic.
-Itamar
This or something very much like it should be in the Twisted Glossary.
Kevin Horn
The whole idea of a glossary concerns me a little bit.
You're just saying that because you don't want anyone else to understand what you're saying ;) Seriously though. When I first started thinking about ways to improve the documentation. The _first_ thing I thought was missing was decent explanations of some of these things. Whether it's in a glossary or someplace else, clear definitions need to exist for all the major Twisted concepts (people may disagree on what is or is not major, and that's fine). Putting these definitions (or links to them) in a glossary keeps them all together and easy to find and refer to. One of the first thing I look for in any software documentation is a glossary or some set of definitions that I can refer to while I'm _reading_ the API docs or whatever. Solving problems through software requires finding the right abstractions, which IMO depends a great deal on finding the right vocabulary for those abstractions. I know the Twisted devs spend a lot of time and energy trying to find exactly the right word for a class, or a method, or whatever. Let's communicate that to new people! If you don't want a "glossary", then we'll do something else, but I think it's important to have all of the really critical concepts described in one place somewhere. Also consider the problem of reverse human lookup: "Oh man, what was that thing called that stops and starts Twisted code at the appropriate times?" If you stick that into a search engine, you probably won't find it for a loooong time. But if there's a glossary, you just look there, and you find it pretty easily.
One way I frequently see it done is vague little snippets of text like this, and I don't like that.
Well, I consider it much more meaningful than what is currently there. Not saying it's really sufficient, but it is succinct. I think what I'd like to see is a "glossary" entry with: - an API link (e.g. "An object which implements the IService Interface" -- and yes, it should be a proper English sentence.) - A succinct definition (like Itamar's quip above) - a paragraph or two of discussion (not too long though!) - "see also" links to HOWTO's etc. I want to say that I do NOT think we should be trying to include every single idea/concept/interface/class/whatever in whatever glossary comes up. Just the main concepts. Not to say that Itamar's answer to this particular question was incorrect or
inappropriate, I just wouldn't want to see this enshrined as the official, central definition.
However, Twisted does have its own jargon and a dictionary to help the novice parse it would be a good thing.
What I'd really like to see in this regard is to make sure that every "jargon term" is linked straight to API documentation, since we've gone to some trouble to make our jargon match the names used in code as closely as possible*. In this case, < http://twistedmatrix.com/documents/10.2.0/api/twisted.application.service.IS...>. If the API documentation is not sufficient (which in this case it may well not be), let's make the API documentation sufficient*.* Don't fortify it with a redundant official glossary listing that has to be maintained in parallel and updated in synch with the API docs.
I'm not sure how much of a problem maintaining it would be, especially as I agree that linking to the API docs is probably a good idea (though I think a lot of the docstrings in there could be greatly improved). For one thing, how often has the _intent_ of the IProtocol interface (which has no docstring, btw) changed? And how often does someone show up on IRC who doesn't understand what a Protocol object is show up?
Thoughts?
I think we've totally hijacked this thread :) Kevin Horn
On Jan 28, 2011, at 5:47 PM, Kevin Horn wrote:
On Fri, Jan 28, 2011 at 1:33 PM, Glyph Lefkowitz <glyph@twistedmatrix.com> wrote:
On Jan 28, 2011, at 10:38 AM, Kevin Horn wrote:
On Fri, Jan 28, 2011 at 7:25 AM, Itamar Turner-Trauring <itamar@itamarst.org> wrote:
A service is supposed to be something you can start and stop, and encapsulates a self-contained piece of business logic.
-Itamar
This or something very much like it should be in the Twisted Glossary.
Kevin Horn
The whole idea of a glossary concerns me a little bit.
You're just saying that because you don't want anyone else to understand what you're saying ;)
I am aggrieved that you would insinuate any premeditated obfuscatory animus appertaining to my person or those of my associates. I maintain an amaranthine focus on limpid exposition and efficacious intercommunication.
Seriously though. When I first started thinking about ways to improve the documentation. The _first_ thing I thought was missing was decent explanations of some of these things. Whether it's in a glossary or someplace else, clear definitions need to exist for all the major Twisted concepts (people may disagree on what is or is not major, and that's fine). Putting these definitions (or links to them) in a glossary keeps them all together and easy to find and refer to. One of the first thing I look for in any software documentation is a glossary or some set of definitions that I can refer to while I'm _reading_ the API docs or whatever.
If you need a glossary open while you're reading the API docs, that means that the docs you're reading are insufficiently marked up. The word 'service' (in this context) should _always_ itself be a hyperlink to the IService interface. We do this pretty consistently in all new documentation. Similarly 'deferred' should always be a link to twisted.internet.defer.Deferred. <http://epydoc.sourceforge.net/epytext.html> has more detail on how to format these if you want to do clever stuff like have a lower-case word like 'service' link to the IService docs. I'm totally on board with making a list of these common abstractions outside the API docs, but 99% of what that list should do is provide a definitive index of links into the API docs to call out the top important interfaces you need to read about. Also, the existing API docs for many of the core concepts are terrible, or even (cringe) non-existent in places, so they could certainly stand to be improved. I'm not saying our existing docs are great, just that we should have one great index of terms and not five mediocre ones.
Solving problems through software requires finding the right abstractions, which IMO depends a great deal on finding the right vocabulary for those abstractions. I know the Twisted devs spend a lot of time and energy trying to find exactly the right word for a class, or a method, or whatever. Let's communicate that to new people! If you don't want a "glossary", then we'll do something else, but I think it's important to have all of the really critical concepts described in one place somewhere.
I should have qualified my discomfort with the term 'glossary' a bit more. We do need the thing you're talking about. My only concern is redundancy. Even if we had awesome API documentation for all of these things, there's still a bootstrapping phase where people are not sure which classes are one-off utilities and which things are core abstractions they'll be using every day.
Also consider the problem of reverse human lookup: "Oh man, what was that thing called that stops and starts Twisted code at the appropriate times?"
If you stick that into a search engine, you probably won't find it for a loooong time. But if there's a glossary, you just look there, and you find it pretty easily.
Well, that exact phrase, no; but "start and stop twisted application", and "start and stop twisted service" both point at the right API doc. We should probably work a bit harder to make 'start stop twisted' find that page first :).
One way I frequently see it done is vague little snippets of text like this, and I don't like that.
Well, I consider it much more meaningful than what is currently there. Not saying it's really sufficient, but it is succinct. I think what I'd like to see is a "glossary" entry with:
- an API link (e.g. "An object which implements the IService Interface" -- and yes, it should be a proper English sentence.)
This I certainly agree with.
- A succinct definition (like Itamar's quip above) - a paragraph or two of discussion (not too long though!)
Why can't this just be in the API doc?
- "see also" links to HOWTO's etc.
Again - why not in the API doc? If someone were to find the concept via some other documentation that described the term in question as a return type or argument rather than a generic word, presumably that person might also want to read the narrative documentation.
I'm not sure how much of a problem maintaining it would be, especially as I agree that linking to the API docs is probably a good idea (though I think a lot of the docstrings in there could be greatly improved). For one thing, how often has the _intent_ of the IProtocol interface(which has no docstring, btw) changed?
So, first: aaaaaauuugh. Is there a doc bug for that? That is an interface which really, really needs a docstring. Can you submit a patch, like, right now? :) Second: the intent hasn't changed often. But clearly we need to update the documentation to document that intent better, and I hope that happens more often than it does. Narrative vs. reference documentation is already a split, albeit a necessary one in my opinion. Narrative vs. code-reference vs. language-reference seems like we're just splitting hairs.
And how often does someone show up on IRC who doesn't understand what a Protocol object is show up?
Actually... I don't remember IProtocol being a big problem. Which is slightly surprising, given that it has no docstring. Maybe everyone who has run into a confusion at this basic stage has just given up, or maybe the method docstrings are good enough, or maybe the learn about it from a tutorial.
Thoughts?
I think we've totally hijacked this thread :)
Yes, retitled appropriately.
On Fri, Jan 28, 2011 at 7:50 PM, Glyph Lefkowitz <glyph@twistedmatrix.com>wrote:
On Jan 28, 2011, at 5:47 PM, Kevin Horn wrote:
On Fri, Jan 28, 2011 at 1:33 PM, Glyph Lefkowitz <glyph@twistedmatrix.com>wrote:
On Jan 28, 2011, at 10:38 AM, Kevin Horn wrote:
On Fri, Jan 28, 2011 at 7:25 AM, Itamar Turner-Trauring < itamar@itamarst.org> wrote:
A service is supposed to be something you can start and stop, and encapsulates a self-contained piece of business logic.
-Itamar
This or something very much like it should be in the Twisted Glossary.
Kevin Horn
The whole idea of a glossary concerns me a little bit.
You're just saying that because you don't want anyone else to understand what you're saying ;)
I am aggrieved that you would insinuate any premeditated obfuscatory animus appertaining to my person or those of my associates. I maintain an amaranthine focus on limpid exposition and efficacious intercommunication.
Hee! Told you so :)
Seriously though. When I first started thinking about ways to improve the documentation. The _first_ thing I thought was missing was decent explanations of some of these things. Whether it's in a glossary or someplace else, clear definitions need to exist for all the major Twisted concepts (people may disagree on what is or is not major, and that's fine). Putting these definitions (or links to them) in a glossary keeps them all together and easy to find and refer to. One of the first thing I look for in any software documentation is a glossary or some set of definitions that I can refer to while I'm _reading_ the API docs or whatever.
If you need a glossary open while you're reading the API docs, that means that the docs you're reading are insufficiently marked up. The word 'service' (in this context) should _always_ itself be a hyperlink to the IService interface. We do this pretty consistently in all new documentation. Similarly 'deferred' should always be a link to twisted.internet.defer.Deferred. < http://epydoc.sourceforge.net/epytext.html> has more detail on how to format these if you want to do clever stuff like have a lower-case word like 'service' link to the IService docs.
You don't need the glossary open while reading the API docs, you need it open while reading the other stuff. Hopefully the need for this will fade as the organization of the existing long-form docs improve. Plus, you don't necessarily need it "open". You can mark up a glossary term in Sphinx and it'll automatically create cross-refs, so you say "What the heck does that mean?", click the link, and it takes you to the term on the glossary page. From there you can get to the API docs, sure. There should absolutely be a link there. But there should also be something that tells you whether you need to dive into the API docs.
I'm totally on board with making a *list* of these common abstractions outside the API docs, but 99% of what that list should do is provide a definitive index of links into the API docs to call out the top important interfaces you need to read about.
See. Right there. You assumed the reader would be looking for what interfaces they need to read about. If I'm new to Twisted, and I see some example code on the web someplace, I'm not going to _see_ the interface it implements. I'm going to see probably the class. So I Google it. Assuming I know anything about interfaces (which might be assuming a bit, but might not), I'll basically know what that is, but right now the API docs aren't a lot of help for older code, and most of the core things are older code. And that assumes there is an interface for whatever abstraction I'm looking for. I spent several hours once upon a time sifting through the API docs and source trying to figure out what (Cred) Avatars came with Twisted. Some abstractions don't come with source code. Now these assumptions are certainly valid in many, if not most, cases. But keep in mind we want to make things easy for the new people too. That's how we get more new people.
Also, the existing API docs for many of the core concepts are terrible, or even (cringe) non-existent in places, so they could certainly stand to be improved. I'm not saying our existing docs are great, just that we should have one great index of terms and not five mediocre ones.
Yep. I have a list of docs tickets to go through, but there's millions more missing (OK, hopefully not millions, but...). One of them (at least) is to fix the current glossary, since it's current state is DISMAL (It has links to the API docs everywhere though).
Solving problems through software requires finding the right abstractions, which IMO depends a great deal on finding the right vocabulary for those abstractions. I know the Twisted devs spend a lot of time and energy trying to find exactly the right word for a class, or a method, or whatever. Let's communicate that to new people! If you don't want a "glossary", then we'll do something else, but I think it's important to have all of the really critical concepts described in one place somewhere.
I should have qualified my discomfort with the term 'glossary' a bit more. We do need the thing you're talking about. My only concern is redundancy. Even if we had awesome API documentation for all of these things, there's still a bootstrapping phase where people are not sure which classes are one-off utilities and which things are core abstractions they'll be using every day.
Yes, exactly.
Also consider the problem of reverse human lookup: "Oh man, what was that thing called that stops and starts Twisted code at the appropriate times?"
If you stick that into a search engine, you probably won't find it for a loooong time. But if there's a glossary, you just look there, and you find it pretty easily.
Well, that exact phrase, no; but "start and stop twisted application", and "start and stop twisted service" both point at the right API doc. We should probably work a bit harder to make 'start stop twisted' find that page first :).
OK, well when I ran it through Google the API page didn't even show up on the first page. The application framework page did. Google farm oddness maybe.
One way I frequently see it done is vague little snippets of text like
this, and I don't like that.
Well, I consider it much more meaningful than what is currently there. Not saying it's really sufficient, but it is succinct. I think what I'd like to see is a "glossary" entry with:
- an API link (e.g. "An object which implements the IService Interface" -- and yes, it should be a proper English sentence.)
This I certainly agree with.
- A succinct definition (like Itamar's quip above) - a paragraph or two of discussion (not too long though!)
Why can't this just be in the API doc?
Well, it can and should, but: - not every abstraction and/or thing we want to define has source code. - some people are intimidated by having to go to API docs just to find a little information about a library. The way I see it, people go to the API docs when they want to _use_ a library. They go to the long-form docs when they want to find out if library X is the one they want to use. Perhaps we disagree here. - I foresee circumstances where the API docs might not be available. (e.g. If you have no net access and you don't have PyDoctor installed...which I doubt many people do.) But you might have Sphinx installed. Or have the handy-dandy Windows compiled HTML help file for Twisted (which doesn't exist yet, but should someday...maybe even soon). Sure you can look in the source code, but it's kind of a pain if all you want is a definition. After the Sphinx conversion it _might_ be possible to pull in docstrings from the API docs into the Sphinx docs. It certainly would be if the API docs were marked up according to Sphinx conventions, but even I'm not crazy enough (yet) to try to change over all of that stuff. I might be crazy enough to try to write a piece that converts the epydoc markup into Sphinx on the fly and then processes it into html or whatever, but I might also come down with a sudden severe case of sanity.
- "see also" links to HOWTO's etc.
Again - why not in the API doc? If someone were to find the concept via some other documentation that described the term in question as a return type or argument rather than a generic word, presumably that person might also want to read the narrative documentation.
It is currently not possible (AFAIK) to link to things in the long-form docs from the API docs in any kind of maintainable way. There's a ticket for this (#2801). I have some ideas for how it might be fixed after the Sphinx conversion is done. I have zero idea how it might be done before that. You could put in static hyperlinks in the API markup, but that would be highly subject to breakage.
I'm not sure how much of a problem maintaining it would be, especially as I agree that linking to the API docs is probably a good idea (though I think a lot of the docstrings in there could be greatly improved). For one thing, how often has the _intent_ of the IProtocol interface(which has no docstring, btw) changed?
So, first: aaaaaauuugh. Is there a doc bug for that? That is an interface which really, really needs a docstring. Can you submit a patch, like, right now? :)
Second: the intent hasn't changed often. But clearly we need to update the documentation to document that intent better, and I hope that happens more often than it does. Narrative vs. reference documentation is already a split, albeit a necessary one in my opinion. Narrative vs. code-reference vs. language-reference seems like we're just splitting hairs.
But the "language-reference" is an adjunct to the narrative documentation, IMO. Like an index, or the table of contents. And when I go to it, I don't expect/want there to _only_ be an API link there
And how often does someone show up on IRC who doesn't understand what a Protocol object is show up?
Actually... I don't remember IProtocol being a big problem. Which is slightly surprising, given that it has no docstring. Maybe everyone who has run into a confusion at this basic stage has just given up, or maybe the method docstrings are good enough, or maybe the learn about it from a tutorial.
It seems to me like there's at least one person a week on IRC who needs the old talk about what Protocols do vs. what Factories do. Or how they get their Protocol to make multiple connections. [Aside: docstring for t.i.p.Factory: "This is a factory which produces protocols. By default, buildProtocol will create a protocol of the class given in self.protocol.". docstring for t.i.i.ProtocolFactory: "Interface for protocol factories." Aaaaaaaugh! Some of the old docstrings need a lot of work. It's a separate issue though.] Thoughts?
I think we've totally hijacked this thread :)
Yes, retitled appropriately.
Well done. In the words of Inigo Montoya, "Lemme sum up": - I don't think we're too far away from each other in our opinions, but I think you're more worried about redundancy than I am. I think once the docs are more navigable, the glossary will be much more useful, and problems will be noticed much more quickly than they are now. - If you want a great example of how I think a glossary should be used with Sphinx, check out the Pyramid docs ( http://docs.pylonsproject.org/projects/pyramid/dev/index.html). Like that but with more API links. :) - In addition, I also think there should be a "Twisted Concepts" document/section in or near the hopefully-soon-to-be-written intro stuff that Tom is working on. - it's going to be an incremental process. I'm sure we'll have plenty of time for discussion. :) Kevin Horn
On Jan 28, 2011, at 10:51 PM, Kevin Horn wrote:
right now the API docs aren't a lot of help for older code, and most of the core things are older code.
And that's exactly the problem - I don't want to paper that over with a shiny new project to explain everything in some new location. I want to fix the API docs.
And that assumes there is an interface for whatever abstraction I'm looking for.
If there aren't, that's a failure of the implementation, so let's fix that :). But, okay,
I spent several hours once upon a time sifting through the API docs and source trying to figure out what (Cred) Avatars came with Twisted. Some abstractions don't come with source code.
Yeah uh, okay. The cred docs are bad and at this point I don't think that anyone except me (and maaaaaybe exarkun) understands them. This is a bit of an unrelated problem. The abstractions do have source code, and could be better explained. And it needs narrative documentation,
One of them (at least) is to fix the current glossary, since it's current state is DISMAL (It has links to the API docs everywhere though).
Man, there's a current glossary? (*opens glossary.xhtml*). Oh my goodness. Yes, that's not great. And yes, please, fix it up. So again, as the person actually doing the work, you can obviously put your effort wherever you think it's most valuable, but really everything boils down to this: rather than have "a paragraph of discussion" in the glossary, save the discussion for the narrative documentation or the API documentation, as appropriate. Feel free to edit the API docs or the narrative docs to have good things to link to.
It is currently not possible (AFAIK) to link to things in the long-form docs from the API docs in any kind of maintainable way. There's a ticket for this (#2801). I have some ideas for how it might be fixed after the Sphinx conversion is done. I have zero idea how it might be done before that. You could put in static hyperlinks in the API markup, but that would be highly subject to breakage.
Well, let's get that migration done then! hut, hut!
I'm not sure how much of a problem maintaining it would be, especially as I agree that linking to the API docs is probably a good idea (though I think a lot of the docstrings in there could be greatly improved). For one thing, how often has the _intent_ of the IProtocol interface(which has no docstring, btw) changed?
So, first: aaaaaauuugh. Is there a doc bug for that? That is an interface which really, really needs a docstring. Can you submit a patch, like, right now? :)
I don't see one. Nor for the over-terse Factory/IFactory docstrings. I'll create one though. Kevin Horn
Glyph Lefkowitz wrote: [...]
The whole idea of a glossary concerns me a little bit. … However, Twisted does have its own jargon and a dictionary to help the novice parse it would be a good thing. What I'd really like to see in this regard is to make sure that every "jargon term" is linked straight to API documentation
We already have a glossary: <http://twistedmatrix.com/documents/current/core/howto/glossary.html> And for what it's worth, it's entry for Service is: A twisted.application.service.Service [link to API doc]. See Application howto [link] for a description of how they relate to Applications [glossary link]. Superficially, this would appear to satisfy both you and Kevin: there is a glossary, and it is very explicit (at least in this entry) that the API doc is the canonical reference. So whatever it is you're both asking for you perhaps both need to be clearer about what it is :) -Andrew.
On Jan 29, 2011, at 10:47 PM, Andrew Bennetts <andrew@bemusement.org> wrote:
Glyph Lefkowitz wrote: [...]
The whole idea of a glossary concerns me a little bit. … However, Twisted does have its own jargon and a dictionary to help the novice parse it would be a good thing. What I'd really like to see in this regard is to make sure that every "jargon term" is linked straight to API documentation
We already have a glossary:
<http://twistedmatrix.com/documents/current/core/howto/glossary.html>
Yeah, that came up a bit later in the thread :). And kevin did mention that maintaining that doc is the first order of business.
And for what it's worth, it's entry for Service is:
A twisted.application.service.Service [link to API doc]. See Application howto [link] for a description of how they relate to Applications [glossary link].
Superficially, this would appear to satisfy both you and Kevin: there is a glossary, and it is very explicit (at least in this entry) that the API doc is the canonical reference.
So whatever it is you're both asking for you perhaps both need to be clearer about what it is :)
I think that the fact such a discussion was able to go on for so long before we discovered it really just emphasizes another thing that comes up very frequently in these discussions: discoverability of the documentation. We need more and better links to such things.
On Sun, Jan 30, 2011 at 2:22 AM, Glyph Lefkowitz <glyph@twistedmatrix.com>wrote:
On Jan 29, 2011, at 10:47 PM, Andrew Bennetts <andrew@bemusement.org> wrote:
Glyph Lefkowitz wrote: [...]
The whole idea of a glossary concerns me a little bit. … However, Twisted does have its own jargon and a dictionary to help the novice parse it would be a good thing. What I'd really like to see in this regard is to make sure that every "jargon term" is linked straight to API documentation
We already have a glossary:
<http://twistedmatrix.com/documents/current/core/howto/glossary.html>
Yeah, that came up a bit later in the thread :). And kevin did mention that maintaining that doc is the first order of business.
And for what it's worth, it's entry for Service is:
A twisted.application.service.Service [link to API doc]. See Application howto [link] for a description of how they relate to Applications [glossary link].
Superficially, this would appear to satisfy both you and Kevin: there is a glossary, and it is very explicit (at least in this entry) that the API doc is the canonical reference.
So whatever it is you're both asking for you perhaps both need to be clearer about what it is :)
I think that the fact such a discussion was able to go on for so long before we discovered it really just emphasizes another thing that comes up very frequently in these discussions: discoverability of the documentation. We need more and better links to such things.
Well, first off, I did know about the glossary. It's dismal state is one of the things that motivated me to start working on Twisted Documentation. As I mentioned in the other thread, a glossary is one of the first things I look for in a documentation set. Secondly, Twisted actually has 2 glossaries. One general one (referenced above) and one specific to Twisted Web (here: http://twistedmatrix.com/documents/current/web/howto/glossary.html). It has, however, only one entry. I intend in future to combine the two, unless someone else does it first. Thirdly, as far as discoverability/navigability of the documentation, I think Sphinx (*) will help a lot here. It has all kinds of tools to make cross-linking as easy as possible, like the toc segments in the sidebar, prev/next links, glossary links, indexing, etc. Should help quite a bit, I think. Kevin Horn (*) I know, I _know_! I'm working on it! :)
Hi! I'm quite happy that my question (or really: Itamar's answer) triggered the interesting discussion about glossaries. But there are some aspects about SerialPort that are not yet clear to me. So I'm trying to reclaim this thread ;-). On Fri, Jan 28, 2011 at 08:25:52AM -0500, Itamar Turner-Trauring wrote:
The TCP port doesn't implement IService either...
This is correct. But TCPServer does implement IService, and I was looking for an analog I could use for the serial port. I'd like to write something along the following lines: def setupSerialCommunication(multiService): lrFactory = MyLineReceiverFactory() serialComm = internet.SerialServer(lrFactory, '/dev/ttyS0') serialComm.setServiceParent(multiService) (BTW: I'm not quite sure if SerialServer would belong to the internet package...) In my understanding, the communication over the serial line should be handled in a similar way to communicating via TCP/IP. So my questions should have been: Why isn't there an analog to TCPServer for SerialPort? Would it make sense to add it?
A service is supposed to be something you can start and stop, and encapsulates a self-contained piece of business logic. The purpose is both deployment and ease of regression testing.
Thanks for the explanation. It is certainly a good idea to think about the partitioning of the services and reflect it in the code.
So maybe your service starts both a webserver and a serialport, because it requires both -- which is why mostly you should just implement your own service classes.
There is the class t.a.s.MultiService for encapsulating other services. In my current implementation I just instantiate it and add the other services; afterwards I set its service Parent to the application. What would be the advantage of subclassing Service and redefining its startService and stopService methods? Thanks & best regards, Albert -- Albert Brandl Weiermayer Solutions GmbH | Abteistraße 12, A-4813 Altmünster phone: +43 (0) 720 70 30 14 | fax: +43 (0) 7612 20 3 56 web: http://www.weiermayer.com
On 03:50 pm, albert.brandl@weiermayer.com wrote:
Hi!
I'm quite happy that my question (or really: Itamar's answer) triggered the interesting discussion about glossaries. But there are some aspects about SerialPort that are not yet clear to me. So I'm trying to reclaim this thread ;-).
On Fri, Jan 28, 2011 at 08:25:52AM -0500, Itamar Turner-Trauring wrote:
The TCP port doesn't implement IService either...
This is correct. But TCPServer does implement IService, and I was looking for an analog I could use for the serial port. I'd like to write something along the following lines:
def setupSerialCommunication(multiService): lrFactory = MyLineReceiverFactory() serialComm = internet.SerialServer(lrFactory, '/dev/ttyS0') serialComm.setServiceParent(multiService)
(BTW: I'm not quite sure if SerialServer would belong to the internet package...)
In my understanding, the communication over the serial line should be handled in a similar way to communicating via TCP/IP. So my questions should have been: Why isn't there an analog to TCPServer for SerialPort? Would it make sense to add it?
I think that now the way it would make sense to add this is to add a serialport endpoint. This would be usable with twisted.internet.endpoints.serverFromEndpoint (or clientFromEndpoint, I can never remember which one a serial port is more like). Then, this endpoint could be combined with a general-purpose endpoint- into-service adapter.
A service is supposed to be something you can start and stop, and encapsulates a self-contained piece of business logic. The purpose is both deployment and ease of regression testing.
Thanks for the explanation. It is certainly a good idea to think about the partitioning of the services and reflect it in the code.
So maybe your service starts both a webserver and a serialport, because it requires both -- which is why mostly you should just implement your own service classes.
There is the class t.a.s.MultiService for encapsulating other services. In my current implementation I just instantiate it and add the other services; afterwards I set its service Parent to the application. What would be the advantage of subclassing Service and redefining its startService and stopService methods?
If you can accomplish your goals without making a new kind of IService implementation, then great! If it is awkward (for example, if you want the web server to have a reference to the protocol currently connected to the serial port), then it might be easier if you have your own IService implementation that knows about both your web server and your serial port. Jean-Paul
Hi! On Mon, Jan 31, 2011 at 10:18:00PM -0000, exarkun@twistedmatrix.com wrote:
I think that now the way it would make sense to add this is to add a serialport endpoint. This would be usable with twisted.internet.endpoints.serverFromEndpoint (or clientFromEndpoint, I can never remember which one a serial port is more like).
Cool. I think you talked about serverFromString, but this was enough to get me started. I've added the necessary functions and classes so that I can create a server listening to the serial line with something like: serial_server = strports.service("SERIAL:/dev/ttyS0:baudrate=38400") But injecting the necessary functions and classes into t.i.endpoints is rather ugly. Would it be ok to create a ticket to properly enhance the module with an endpoint encapsulating SerialPort?
If you can accomplish your goals without making a new kind of IService implementation, then great!
Right now, this is sufficient for my purposes. Thanks and best regards, Albert -- Albert Brandl Weiermayer Solutions GmbH | Abteistraße 12, A-4813 Altmünster phone: +43 (0) 720 70 30 14 | fax: +43 (0) 7612 20 3 56 web: http://www.weiermayer.com
On 10:18 am, albert.brandl@weiermayer.com wrote:
Hi!
On Mon, Jan 31, 2011 at 10:18:00PM -0000, exarkun@twistedmatrix.com wrote:
I think that now the way it would make sense to add this is to add a serialport endpoint. This would be usable with twisted.internet.endpoints.serverFromEndpoint (or clientFromEndpoint, I can never remember which one a serial port is more like).
Cool. I think you talked about serverFromString, but this was enough to get me started. I've added the necessary functions and classes so that I can create a server listening to the serial line with something like:
serial_server = strports.service("SERIAL:/dev/ttyS0:baudrate=38400")
But injecting the necessary functions and classes into t.i.endpoints is rather ugly. Would it be ok to create a ticket to properly enhance the module with an endpoint encapsulating SerialPort?
That probably makes sense, but first, does the endpoints string description plugin API help? You can provide IStreamServerEndpointStringParser (defined in twisted.internet.interfaces) plugins to extend the parser for those strings. This might clean things up your serial port endpoint is actually included in a release of Twisted. There are some tickets filed already for adding some other kinds of endpoints (eg an IPv6 endpoint - http://twistedmatrix.com/trac/ticket/4470), but it doesn't look like there's one for serial port, so yea - it would be great if you could file that one. Jean-Paul
On Thu, Feb 03, 2011 at 07:00:39PM -0000, exarkun@twistedmatrix.com wrote:
That probably makes sense, but first, does the endpoints string description plugin API help? You can provide IStreamServerEndpointStringParser (defined in twisted.internet.interfaces) plugins to extend the parser for those strings.
Actually, that's the way I implemented this. But I didn't find any hooks for extending the parser, so I manually inserted new items into endpoints._endpointServerFactories and endpoints._serverParsers and added the StringParser to endpoints. Is there a better way? Could you provide me with a link to any documentation? I've already read the tutorial about creating plugins.
There are some tickets filed already for adding some other kinds of endpoints (eg an IPv6 endpoint - http://twistedmatrix.com/trac/ticket/4470), but it doesn't look like there's one for serial port, so yea - it would be great if you could file that one.
Fine. Any suggestions for the name of the new endpoint? Best regards, Albert -- Albert Brandl Weiermayer Solutions GmbH | Abteistraße 12, A-4813 Altmünster phone: +43 (0) 720 70 30 14 | fax: +43 (0) 7612 20 3 56 web: http://www.weiermayer.com
On 08:20 am, albert.brandl@weiermayer.com wrote:
On Thu, Feb 03, 2011 at 07:00:39PM -0000, exarkun@twistedmatrix.com wrote:
That probably makes sense, but first, does the endpoints string description plugin API help? You can provide IStreamServerEndpointStringParser (defined in twisted.internet.interfaces) plugins to extend the parser for those strings.
Actually, that's the way I implemented this. But I didn't find any hooks for extending the parser, so I manually inserted new items into endpoints._endpointServerFactories and endpoints._serverParsers and added the StringParser to endpoints.
Is there a better way? Could you provide me with a link to any documentation? I've already read the tutorial about creating plugins.
IStreamServerEndpointStringParser is the hook. I don't know of any documentation on its use, though. Perhaps twisted/internet/test/fakeendpoint.py will give you an idea of what to do, though (then, feel like writing the missing docs?). Jean-Paul
On Thu, Feb 03, 2011 at 07:00:39PM -0000, exarkun@twistedmatrix.com wrote:
There are some tickets filed already for adding some other kinds of endpoints (eg an IPv6 endpoint - http://twistedmatrix.com/trac/ticket/4470), but it doesn't look like there's one for serial port, so yea - it would be great if you could file that one.
Here's the ticket: http://twistedmatrix.com/trac/ticket/4847 I don't know either if `serverFromString` or `clientFromString` is "better" for a serial port. Not sure if this can even be determined without knowing more about the purpose of the communication. Any opinions? I've added a corresponding remark to the ticket. Regards, Albert -- Albert Brandl Weiermayer Solutions GmbH | Abteistraße 12, A-4813 Altmünster phone: +43 (0) 720 70 30 14 | fax: +43 (0) 7612 20 3 56 web: http://www.weiermayer.com
participants (8)
-
Albert Brandl -
Andrew Bennetts -
exarkun＠twistedmatrix.com -
Glyph Lefkowitz -
Itamar Turner-Trauring -
Kevin Horn -
Ralph Meijer -
Tom Davis