hio.core.uxd.uxding =================== .. py:module:: hio.core.uxd.uxding .. autoapi-nested-parse:: hio.core.uxd.uxding Module Module Contents --------------- .. py:class:: Peer(*, umask=None, bc=None, bs=None, wl=None, reopen=False, clear=True, filed=False, extensioned=True, **kwa) Bases: :py:obj:`hio.base.filing.Filer` Class to manage non-blocking io on UXD (unix domain) socket. Use instance method .close() to close socket Because Unix Domain Sockets are reliable no need for retry tymer. Inherited Class Attributes: HeadDirPath (str): default abs dir path head such as "/usr/local/var" TailDirPath (str): default rel dir path tail when using head CleanTailDirPath (str): default rel dir path tail when creating clean AltHeadDirPath (str): default alt dir path head such as "~" as fallback when desired head not permitted. AltTailDirPath (str): default alt rel dir path tail as fallback when using alt head. AltCleanTailDirPath (str): default alt rel path tail when creating clean TempHeadDir (str): default temp abs dir path head such as "/tmp" TempPrefix (str): default rel dir path prefix when using temp head TempSuffix (str): default rel dir path suffix when using temp head and tail Perm (int): explicit default octal perms such as 0o1700 Mode (str): open mode such as "r+" Fext (str): default file extension such as "text" for "fname.text" Class Attributes: Umask (int): octal default umask permissions such as 0o022 MaxUxdPathSize (int:) max characters in uxd file path BufSize (int): used to set default buffer size for transport datagram buffers MaxGramSize (int): max bytes in in datagram for this transport Inherited Attributes: name (str): unique path component used in directory or file path name base (str): another unique path component inserted before name temp (bool): True means use TempHeadDir in /tmp directory headDirPath (str): head directory path path (str or None): full directory or file path once created else None perm (int): numeric os permissions for directory and/or file(s) filed (bool): True means .path ends in file; False means .path ends in directory mode (str): file open mode if filed fext (str): file extension if filed file (File or None): File instance when filed and created. opened (bool): True means directory path, uxd file, and socket are created and opened. False otherwise .. attribute:: umask permission mask for uxd file, usually octal 0o022; .umask is applied after .perm is set if any :type: int .. attribute:: bc count of transport buffers of MaxGramSize :type: int or None .. attribute:: bs buffer size of transport buffers. When .bc then .bs is calculated by multiplying, .bs = .bc * .MaxGramSize. When .bc is None then .bs is provided value or default .BufSize :type: int .. attribute:: wl instance ref for debug logging of over the wire tx and rx :type: WireLog .. attribute:: ls local socket of this Peer :type: socket.socket .. py:method:: actualBufSizes() Return actual socket send and receive buffer size. :returns: (tx, rx) actual socket send and receive buffer sizes. :rtype: tuple .. py:method:: open() Opens socket in non blocking mode. :returns: True if opened successfully. False otherwise :rtype: result (bool) .. rubric:: Notes If socket is not closed properly, binding may raise OSError: (48, 'Address already in use'). .. py:method:: reopen(clear=True, **kwa) Idempotently open socket by closing first if need be :returns: True if opened successfully. False otherwise :rtype: result (bool) Inherited Parameters: clear (bool): True means remove directory and uxd file upon close False means do not remove directory and uxd file upon close .. seealso:: filing.Filer: other inherited parameters. .. py:method:: close(clear=True) Closes socket and unlinks UXD file. Inherited Parameters: clear (bool): True means remove directory/uxd file upon close False means do not remove directory/uxd file upon close .. seealso:: filing.Filer: other inherited parameters. .. py:method:: receive(**kwa) Perform non blocking receive on socket. :returns: of form (bytes, str | None) labeled (data, src) where data is bytes of data received src is str uxd source path or None If data empty then returns (b'', None) but always returns duple :rtype: result (tuple) .. py:method:: send(data, dst, **kwa) Perform non blocking send on socket. :returns: number of bytes actually sent, may be less than len(data). :rtype: cnt (int) :param data: payload to send :type data: bytes :param dst: uxd destination path :type dst: str .. py:function:: openPeer(cls=None, name='test', temp=True, reopen=True, clear=True, filed=False, extensioned=True, **kwa) Wrapper to create and open UXD Peer instances When used in with statement block, calls .close() on exit of with block :param cls: instance of subclass instance :type cls: Class :param name: unique identifier of peer. Unique path part so can have many Peers each at different paths that each use different dirs or files :type name: str :param temp: True means open in temporary directory, clear on close Otherwise open in persistent directory, do not clear on close :type temp: bool :param reopen: True (re)open with this init False not (re)open with this init but later (default) :type reopen: bool :param clear: True means remove directory upon close when reopening False means do not remove directory upon close when reopening :type clear: bool :param filed: True means .path is file path not directory path False means .path is directory path not file path :type filed: bool :param extensioned: When not filed: True means ensure .path ends with fext False means do not ensure .path ends with fext :type extensioned: bool See filing.Filer and uxding.Peer for other keyword parameter passthroughs Usage:: with openPeer() as peer0: peer0.receive() with openPeer(cls=PeerBig) as peer0: peer0.receive() .. py:class:: PeerDoer(peer, **kwa) Bases: :py:obj:`hio.base.doing.Doer` Basic UXD Peer Doer Stub override in sub class Because Unix Domain Sockets are reliable no need for retry tymer. To test in WingIde must configure Debug I/O to use external console See Doer for inherited attributes, properties, and methods. See Doer for inherited attributes, properties, and methods. .. attribute:: .peer is UXD Peer instance .. py:method:: enter(*, temp=None) Do 'enter' context actions. Override in subclass. Not a generator method. Set up resources. Comparable to context manager enter. :param temp: True means use temporary file resources if any None means ignore parameter value. Use self.temp :type temp: bool | None Inject temp or self.temp into file resources here if any Doist or DoDoer winds its doers on enter .. py:method:: recur(tyme) Do 'recur' context actions. Override in subclass. Regular method that perform repetitive actions once per invocation. Assumes resource setup in .enter() and resource takedown in .exit() (see ReDoer below for example of .recur that is a generator method) Returns completion state of recurrence actions: True means done, False means continue. Doist provides the time value. .recur maybe implemented by a subclass either as a non-generator method or a generator method. This stub here is as a non-generator method. The base class .do detects which type:: If non-generator .do method runs .recur method once per iteration until .recur returns (True) If generator .do method runs .recur with (yield from) until .recur returns (see ReDoer for example of generator .recur) .. py:method:: exit() Do 'exit' context actions. Override in subclass. Not a generator method. Clean up resources. Comparable to context manager exit. Called by finally after normal return, close, or abort. After .exit() do returns resulting in StopIteration.