From ccf48ac4938cb2817050fa71dbeb8d28d218e6f7 Mon Sep 17 00:00:00 2001 From: cliechti Date: Sun, 3 Aug 2014 21:57:45 +0000 Subject: doc update git-svn-id: http://svn.code.sf.net/p/pyserial/code/trunk/pyserial@504 f19166aa-fa4f-0410-85c2-fa1106f25c8a --- serial/rfc2217.py | 38 +++++++++++--------- serial/serialjava.py | 26 +++++++++----- serial/serialposix.py | 51 ++++++++++++++++++--------- serial/serialutil.py | 67 +++++++++++++++++++++++------------- serial/serialwin32.py | 31 +++++++++++------ serial/tools/list_ports_linux.py | 5 ++- serial/tools/miniterm.py | 2 +- serial/urlhandler/protocol_loop.py | 42 ++++++++++++++-------- serial/urlhandler/protocol_socket.py | 36 ++++++++++++------- 9 files changed, 193 insertions(+), 105 deletions(-) diff --git a/serial/rfc2217.py b/serial/rfc2217.py index 3781ac6..4fe1a72 100644 --- a/serial/rfc2217.py +++ b/serial/rfc2217.py @@ -253,8 +253,10 @@ class TelnetOption(object): return "%s:%s(%s)" % (self.name, self.active, self.state) def process_incoming(self, command): - """A DO/DONT/WILL/WONT was received for this option, update state and - answer when needed.""" + """\ + A DO/DONT/WILL/WONT was received for this option, update state and + answer when needed. + """ if command == self.ack_yes: if self.state is REQUESTED: self.state = ACTIVE @@ -310,7 +312,7 @@ class TelnetSubnegotiation(object): def set(self, value): """\ - request a change of the value. a request is sent to the server. if + Request a change of the value. a request is sent to the server. if the client needs to know if the change is performed he has to check the state of this object. """ @@ -322,7 +324,7 @@ class TelnetSubnegotiation(object): def isReady(self): """\ - check if answer from server has been received. when server rejects + Check if answer from server has been received. when server rejects the change, raise a ValueError. """ if self.state == REALLY_INACTIVE: @@ -333,7 +335,7 @@ class TelnetSubnegotiation(object): def wait(self, timeout=3): """\ - wait until the subnegotiation has been acknowledged or timeout. It + Wait until the subnegotiation has been acknowledged or timeout. It can also throw a value error when the answer from the server does not match the value sent. """ @@ -347,7 +349,7 @@ class TelnetSubnegotiation(object): def checkAnswer(self, suboption): """\ - check an incoming subnegotiation block. the parameter already has + Check an incoming subnegotiation block. The parameter already has cut off the header like sub option number and com port option value. """ if self.value == suboption[:len(self.value)]: @@ -616,8 +618,10 @@ class RFC2217Serial(SerialBase): self.rfc2217SendPurge(PURGE_TRANSMIT_BUFFER) def sendBreak(self, duration=0.25): - """Send break condition. Timed, returns to idle state after given - duration.""" + """\ + Send break condition. Timed, returns to idle state after given + duration. + """ if not self._isOpen: raise portNotOpenError self.setBreak(True) time.sleep(duration) @@ -682,7 +686,7 @@ class RFC2217Serial(SerialBase): # - - - RFC2217 specific - - - def _telnetReadLoop(self): - """read loop for the socket.""" + """Read loop for the socket.""" mode = M_NORMAL suboption = None try: @@ -848,9 +852,9 @@ class RFC2217Serial(SerialBase): def getModemState(self): """\ - get last modem state (cached value. if value is "old", request a new - one. this cache helps that we don't issue to many requests when e.g. all - status lines, one after the other is queried by te user (getCTS, getDSR + get last modem state (cached value. If value is "old", request a new + one. This cache helps that we don't issue to many requests when e.g. all + status lines, one after the other is queried by the user (getCTS, getDSR etc.) """ # active modem state polling enabled? is the value fresh enough? @@ -943,10 +947,10 @@ class PortManager(object): def _client_ok(self): """\ - callback of telnet option. it gets called when option is activated. - this one here is used to detect when the client agrees on RFC 2217. a + callback of telnet option. It gets called when option is activated. + This one here is used to detect when the client agrees on RFC 2217. A flag is set so that other functions like check_modem_lines know if the - client is ok. + client is OK. """ # The callback is used for we and they so if one party agrees, we're # already happy. it seems not all servers do the negotiation correctly @@ -1009,7 +1013,7 @@ class PortManager(object): def escape(self, data): """\ - this generator function is for the user. all outgoing data has to be + This generator function is for the user. All outgoing data has to be properly escaped, so that no IAC character in the data stream messes up the Telnet state machine in the server. @@ -1026,7 +1030,7 @@ class PortManager(object): def filter(self, data): """\ - handle a bunch of incoming bytes. this is a generator. it will yield + Handle a bunch of incoming bytes. This is a generator. It will yield all characters not of interest for Telnet/RFC 2217. The idea is that the reader thread pushes data from the socket through diff --git a/serial/serialjava.py b/serial/serialjava.py index ac538e3..cc25a7b 100644 --- a/serial/serialjava.py +++ b/serial/serialjava.py @@ -50,12 +50,16 @@ def device(portnumber): class JavaSerial(SerialBase): - """Serial port class, implemented with Java Communications API and - thus usable with jython and the appropriate java extension.""" + """\ + Serial port class, implemented with Java Communications API and + thus usable with jython and the appropriate java extension. + """ def open(self): - """Open port with current settings. This may throw a SerialException - if the port cannot be opened.""" + """\ + Open port with current settings. This may throw a SerialException + if the port cannot be opened. + """ if self._port is None: raise SerialException("Port must be configured before it can be used.") if self._isOpen: @@ -150,9 +154,11 @@ class JavaSerial(SerialBase): return self._instream.available() def read(self, size=1): - """Read size bytes from the serial port. If a timeout is set it may - return less characters as requested. With no timeout it will block - until the requested number of bytes is read.""" + """\ + Read size bytes from the serial port. If a timeout is set it may + return less characters as requested. With no timeout it will block + until the requested number of bytes is read. + """ if not self.sPort: raise portNotOpenError read = bytearray() if size > 0: @@ -179,8 +185,10 @@ class JavaSerial(SerialBase): self._instream.skip(self._instream.available()) def flushOutput(self): - """Clear output buffer, aborting the current output and - discarding all that is in the buffer.""" + """\ + Clear output buffer, aborting the current output and + discarding all that is in the buffer. + """ if not self.sPort: raise portNotOpenError self._outstream.flush() diff --git a/serial/serialposix.py b/serial/serialposix.py index 5c3eb5f..43004b3 100644 --- a/serial/serialposix.py +++ b/serial/serialposix.py @@ -274,13 +274,15 @@ CMSPAR = 010000000000 # Use "stick" (mark/space) parity class PosixSerial(SerialBase): - """Serial port class POSIX implementation. Serial port configuration is + """\ + Serial port class POSIX implementation. Serial port configuration is done with termios and fcntl. Runs on Linux and many other Un*x like systems.""" def open(self): - """Open port with current settings. This may throw a SerialException - if the port cannot be opened.""" + """\ + Open port with current settings. This may throw a SerialException + if the port cannot be opened.""" if self._port is None: raise SerialException("Port must be configured before it can be used.") if self._isOpen: @@ -458,9 +460,11 @@ class PosixSerial(SerialBase): # select based implementation, proved to work on many systems def read(self, size=1): - """Read size bytes from the serial port. If a timeout is set it may - return less characters as requested. With no timeout it will block - until the requested number of bytes is read.""" + """\ + Read size bytes from the serial port. If a timeout is set it may + return less characters as requested. With no timeout it will block + until the requested number of bytes is read. + """ if not self._isOpen: raise portNotOpenError read = bytearray() while len(read) < size: @@ -528,8 +532,10 @@ class PosixSerial(SerialBase): return len(data) def flush(self): - """Flush of file like objects. In this case, wait until all data - is written.""" + """\ + Flush of file like objects. In this case, wait until all data + is written. + """ self.drainOutput() def flushInput(self): @@ -538,18 +544,25 @@ class PosixSerial(SerialBase): termios.tcflush(self.fd, TERMIOS.TCIFLUSH) def flushOutput(self): - """Clear output buffer, aborting the current output and - discarding all that is in the buffer.""" + """\ + Clear output buffer, aborting the current output and discarding all + that is in the buffer. + """ if not self._isOpen: raise portNotOpenError termios.tcflush(self.fd, TERMIOS.TCOFLUSH) def sendBreak(self, duration=0.25): - """Send break condition. Timed, returns to idle state after given duration.""" + """\ + Send break condition. Timed, returns to idle state after given + duration. + """ if not self._isOpen: raise portNotOpenError termios.tcsendbreak(self.fd, int(duration/0.25)) def setBreak(self, level=1): - """Set break: Controls TXD. When active, no transmitting is possible.""" + """\ + Set break: Controls TXD. When active, no transmitting is possible. + """ if self.fd is None: raise portNotOpenError if level: fcntl.ioctl(self.fd, TIOCSBRK) @@ -662,14 +675,18 @@ else: pass class PosixPollSerial(Serial): - """poll based read implementation. not all systems support poll properly. + """\ + Poll based read implementation. not all systems support poll properly. however this one has better handling of errors, such as a device - disconnecting while it's in use (e.g. USB-serial unplugged)""" + disconnecting while it's in use (e.g. USB-serial unplugged). + """ def read(self, size=1): - """Read size bytes from the serial port. If a timeout is set it may - return less characters as requested. With no timeout it will block - until the requested number of bytes is read.""" + """\ + Read size bytes from the serial port. If a timeout is set it may + return less characters as requested. With no timeout it will block + until the requested number of bytes is read. + """ if self.fd is None: raise portNotOpenError read = bytearray() poll = select.poll() diff --git a/serial/serialutil.py b/serial/serialutil.py index f28ece4..af0d2f6 100644 --- a/serial/serialutil.py +++ b/serial/serialutil.py @@ -110,7 +110,8 @@ portNotOpenError = SerialException('Attempting to use a port that is not open') class FileLike(object): - """An abstract file like class. + """\ + An abstract file like class. This class implements readline and readlines based on read and writelines based on write. @@ -160,8 +161,10 @@ class FileLike(object): return self def readline(self, size=None, eol=LF): - """read a line which is terminated with end-of-line (eol) character - ('\n' by default) or until timeout.""" + """\ + Read a line which is terminated with end-of-line (eol) character + ('\n' by default) or until timeout. + """ leneol = len(eol) line = bytearray() while True: @@ -177,8 +180,10 @@ class FileLike(object): return bytes(line) def readlines(self, sizehint=None, eol=LF): - """read a list of lines, until timeout. - sizehint is ignored.""" + """\ + Read a list of lines, until timeout. + sizehint is ignored. + """ if self.timeout is None: raise ValueError("Serial port MUST have enabled timeout for this function!") leneol = len(eol) @@ -194,8 +199,10 @@ class FileLike(object): return lines def xreadlines(self, sizehint=None): - """Read lines, implemented as generator. It will raise StopIteration on - timeout (empty read). sizehint is ignored.""" + """\ + Read lines, implemented as generator. It will raise StopIteration on + timeout (empty read). sizehint is ignored. + """ while True: line = self.readline() if not line: break @@ -219,8 +226,10 @@ class FileLike(object): class SerialBase(object): - """Serial port base class. Provides __init__ function and properties to - get/set port settings.""" + """\ + Serial port base class. Provides __init__ function and properties to + get/set port settings. + """ # default values, may be overridden in subclasses that do not support all values BAUDRATES = (50, 75, 110, 134, 150, 200, 300, 600, 1200, 1800, 2400, 4800, @@ -248,9 +257,11 @@ class SerialBase(object): dsrdtr=False, # None: use rtscts setting, dsrdtr override if True or False interCharTimeout=None # Inter-character timeout, None to disable ): - """Initialize comm port object. If a port is given, then the port will be - opened immediately. Otherwise a Serial port object in closed state - is returned.""" + """\ + Initialize comm port object. If a port is given, then the port will be + opened immediately. Otherwise a Serial port object in closed state + is returned. + """ self._isOpen = False self._port = None # correct value is assigned below through properties @@ -305,8 +316,10 @@ class SerialBase(object): # - - - - - - - - - - - - - - - - - - - - - - - - def setPort(self, port): - """Change the port. The attribute portstr is set to a string that - contains the name of the port.""" + """\ + Change the port. The attribute portstr is set to a string that + contains the name of the port. + """ was_open = self._isOpen if was_open: self.close() @@ -322,18 +335,22 @@ class SerialBase(object): if was_open: self.open() def getPort(self): - """Get the current port setting. The value that was passed on init or using - setPort() is passed back. See also the attribute portstr which contains - the name of the port as a string.""" + """\ + Get the current port setting. The value that was passed on init or using + setPort() is passed back. See also the attribute portstr which contains + the name of the port as a string. + """ return self._port port = property(getPort, setPort, doc="Port setting") def setBaudrate(self, baudrate): - """Change baud rate. It raises a ValueError if the port is open and the + """\ + Change baud rate. It raises a ValueError if the port is open and the baud rate is not possible. If the port is closed, then the value is - accepted and the exception is raised when the port is opened.""" + accepted and the exception is raised when the port is opened. + """ try: b = int(baudrate) except TypeError: @@ -489,14 +506,18 @@ class SerialBase(object): 'dsrdtr', 'rtscts', 'timeout', 'writeTimeout', 'interCharTimeout') def getSettingsDict(self): - """Get current port settings as a dictionary. For use with - applySettingsDict""" + """\ + Get current port settings as a dictionary. For use with + applySettingsDict. + """ return dict([(key, getattr(self, '_'+key)) for key in self._SETTINGS]) def applySettingsDict(self, d): - """apply stored settings from a dictionary returned from + """\ + apply stored settings from a dictionary returned from getSettingsDict. it's allowed to delete keys from the dictionary. these - values will simply left unchanged.""" + values will simply left unchanged. + """ for key in self._SETTINGS: if d[key] != getattr(self, '_'+key): # check against internal "_" value setattr(self, key, d[key]) # set non "_" value to use properties write function diff --git a/serial/serialwin32.py b/serial/serialwin32.py index dfdd953..a640fa4 100644 --- a/serial/serialwin32.py +++ b/serial/serialwin32.py @@ -38,8 +38,10 @@ class Win32Serial(SerialBase): SerialBase.__init__(self, *args, **kwargs) def open(self): - """Open port with current settings. This may throw a SerialException - if the port cannot be opened.""" + """\ + Open port with current settings. This may throw a SerialException + if the port cannot be opened. + """ if self._port is None: raise SerialException("Port must be configured before it can be used.") if self._isOpen: @@ -240,9 +242,10 @@ class Win32Serial(SerialBase): return comstat.cbInQue def read(self, size=1): - """Read size bytes from the serial port. If a timeout is set it may - return less characters as requested. With no timeout it will block - until the requested number of bytes is read.""" + """\ + Read size bytes from the serial port. If a timeout is set it may + return less characters as requested. With no timeout it will block + until the requested number of bytes is read.""" if not self.hComPort: raise portNotOpenError if size > 0: win32.ResetEvent(self._overlappedRead.hEvent) @@ -298,8 +301,10 @@ class Win32Serial(SerialBase): return 0 def flush(self): - """Flush of file like objects. In this case, wait until all data - is written.""" + """\ + Flush of file like objects. In this case, wait until all data + is written. + """ while self.outWaiting(): time.sleep(0.05) # XXX could also use WaitCommEvent with mask EV_TXEMPTY, but it would @@ -312,13 +317,17 @@ class Win32Serial(SerialBase): win32.PurgeComm(self.hComPort, win32.PURGE_RXCLEAR | win32.PURGE_RXABORT) def flushOutput(self): - """Clear output buffer, aborting the current output and - discarding all that is in the buffer.""" + """\ + Clear output buffer, aborting the current output and discarding all + that is in the buffer. + """ if not self.hComPort: raise portNotOpenError win32.PurgeComm(self.hComPort, win32.PURGE_TXCLEAR | win32.PURGE_TXABORT) def sendBreak(self, duration=0.25): - """Send break condition. Timed, returns to idle state after given duration.""" + """\ + Send break condition. Timed, returns to idle state after given duration. + """ if not self.hComPort: raise portNotOpenError import time win32.SetCommBreak(self.hComPort) @@ -409,7 +418,7 @@ class Win32Serial(SerialBase): win32.EscapeCommFunction(self.hComPort, win32.SETXOFF) def outWaiting(self): - """return how many characters the in the outgoing buffer""" + """Return how many characters the in the outgoing buffer""" flags = win32.DWORD() comstat = win32.COMSTAT() if not win32.ClearCommError(self.hComPort, ctypes.byref(flags), ctypes.byref(comstat)): diff --git a/serial/tools/list_ports_linux.py b/serial/tools/list_ports_linux.py index d3fa0e4..955761e 100644 --- a/serial/tools/list_ports_linux.py +++ b/serial/tools/list_ports_linux.py @@ -40,7 +40,10 @@ else: plat = sys.platform.lower() def read_line(filename): - """help function to read a single line from a file. returns none""" + """\ + Helper function to read a single line from a file. + Returns None on errors.. + """ try: f = open(filename) line = f.readline().strip() diff --git a/serial/tools/miniterm.py b/serial/tools/miniterm.py index 274c7fb..635ce56 100644 --- a/serial/tools/miniterm.py +++ b/serial/tools/miniterm.py @@ -626,7 +626,7 @@ def main(): if args: parser.error("too many arguments") else: - # noport given on command line -> ask user now + # no port given on command line -> ask user now if port is None: dump_port_list() port = raw_input('Enter port name:') diff --git a/serial/urlhandler/protocol_loop.py b/serial/urlhandler/protocol_loop.py index 7da94ad..a414839 100644 --- a/serial/urlhandler/protocol_loop.py +++ b/serial/urlhandler/protocol_loop.py @@ -36,8 +36,10 @@ class LoopbackSerial(SerialBase): 9600, 19200, 38400, 57600, 115200) def open(self): - """Open port with current settings. This may throw a SerialException - if the port cannot be opened.""" + """\ + Open port with current settings. This may throw a SerialException + if the port cannot be opened. + """ if self._isOpen: raise SerialException("Port is already open.") self.logger = None @@ -63,8 +65,10 @@ class LoopbackSerial(SerialBase): self.flushOutput() def _reconfigurePort(self): - """Set communication parameters on opened port. for the loop:// - protocol all settings are ignored!""" + """\ + Set communication parameters on opened port. For the loop:// + protocol all settings are ignored! + """ # not that's it of any real use, but it helps in the unit tests if not isinstance(self._baudrate, (int, long)) or not 0 < self._baudrate < 2**32: raise ValueError("invalid baudrate: %r" % (self._baudrate)) @@ -115,9 +119,11 @@ class LoopbackSerial(SerialBase): return len(self.loop_buffer) def read(self, size=1): - """Read size bytes from the serial port. If a timeout is set it may + """\ + Read size bytes from the serial port. If a timeout is set it may return less characters as requested. With no timeout it will block - until the requested number of bytes is read.""" + until the requested number of bytes is read. + """ if not self._isOpen: raise portNotOpenError if self._timeout is not None: timeout = time.time() + self._timeout @@ -140,9 +146,11 @@ class LoopbackSerial(SerialBase): return bytes(data) def write(self, data): - """Output the given string over the serial port. Can block if the + """\ + Output the given string over the serial port. Can block if the connection is blocked. May raise SerialException if the connection is - closed.""" + closed. + """ if not self._isOpen: raise portNotOpenError # ensure we're working with bytes data = to_bytes(data) @@ -172,20 +180,26 @@ class LoopbackSerial(SerialBase): self.buffer_lock.release() def flushOutput(self): - """Clear output buffer, aborting the current output and - discarding all that is in the buffer.""" + """\ + Clear output buffer, aborting the current output and + discarding all that is in the buffer. + """ if not self._isOpen: raise portNotOpenError if self.logger: self.logger.info('flushOutput()') def sendBreak(self, duration=0.25): - """Send break condition. Timed, returns to idle state after given - duration.""" + """\ + Send break condition. Timed, returns to idle state after given + duration. + """ if not self._isOpen: raise portNotOpenError def setBreak(self, level=True): - """Set break: Controls TXD. When active, to transmitting is - possible.""" + """\ + Set break: Controls TXD. When active, to transmitting is + possible. + """ if not self._isOpen: raise portNotOpenError if self.logger: self.logger.info('setBreak(%r)' % (level,)) diff --git a/serial/urlhandler/protocol_socket.py b/serial/urlhandler/protocol_socket.py index 09a23d0..41e59b1 100644 --- a/serial/urlhandler/protocol_socket.py +++ b/serial/urlhandler/protocol_socket.py @@ -39,8 +39,10 @@ class SocketSerial(SerialBase): 9600, 19200, 38400, 57600, 115200) def open(self): - """Open port with current settings. This may throw a SerialException - if the port cannot be opened.""" + """\ + Open port with current settings. This may throw a SerialException + if the port cannot be opened. + """ self.logger = None if self._port is None: raise SerialException("Port must be configured before it can be used.") @@ -67,8 +69,10 @@ class SocketSerial(SerialBase): self.flushOutput() def _reconfigurePort(self): - """Set communication parameters on opened port. for the socket:// - protocol all settings are ignored!""" + """\ + Set communication parameters on opened port. For the socket:// + protocol all settings are ignored! + """ if self._socket is None: raise SerialException("Can only operate on open ports") if self.logger: @@ -132,9 +136,11 @@ class SocketSerial(SerialBase): return 0 # hmmm, see comment in read() def read(self, size=1): - """Read size bytes from the serial port. If a timeout is set it may + """\ + Read size bytes from the serial port. If a timeout is set it may return less characters as requested. With no timeout it will block - until the requested number of bytes is read.""" + until the requested number of bytes is read. + """ if not self._isOpen: raise portNotOpenError data = bytearray() if self._timeout is not None: @@ -163,9 +169,11 @@ class SocketSerial(SerialBase): return bytes(data) def write(self, data): - """Output the given string over the serial port. Can block if the + """\ + Output the given string over the serial port. Can block if the connection is blocked. May raise SerialException if the connection is - closed.""" + closed. + """ if not self._isOpen: raise portNotOpenError try: self._socket.sendall(to_bytes(data)) @@ -181,15 +189,19 @@ class SocketSerial(SerialBase): self.logger.info('ignored flushInput') def flushOutput(self): - """Clear output buffer, aborting the current output and - discarding all that is in the buffer.""" + """\ + Clear output buffer, aborting the current output and + discarding all that is in the buffer. + """ if not self._isOpen: raise portNotOpenError if self.logger: self.logger.info('ignored flushOutput') def sendBreak(self, duration=0.25): - """Send break condition. Timed, returns to idle state after given - duration.""" + """\ + Send break condition. Timed, returns to idle state after given + duration. + """ if not self._isOpen: raise portNotOpenError if self.logger: self.logger.info('ignored sendBreak(%r)' % (duration,)) -- cgit v1.2.1