twisted/application/strports.py

   1 # -*- test-case-name: twisted.test.test_strports -*-
   2 # Copyright (c) Twisted Matrix Laboratories.
   3 # See LICENSE for details.
   4
   5 """
   6 Construct listening port services from a simple string description.
   7
   8 @see: L{twisted.internet.endpoints.serverFromString}
   9 @see: L{twisted.internet.endpoints.clientFromString}
  10 """
  11
  12 import warnings
  13
  14 from twisted.internet import endpoints
  15 from twisted.python.deprecate import deprecatedModuleAttribute
  16 from twisted.python.versions import Version
  17 from twisted.application.internet import StreamServerEndpointService
  18
  19
  20
  21 def parse(description, factory, default='tcp'):
  22     """
  23     This function is deprecated as of Twisted 10.2.
  24
  25     @see: L{twisted.internet.endpoints.server}
  26     """
  27     return endpoints._parseServer(description, factory, default)
  28
  29 deprecatedModuleAttribute(
  30     Version("Twisted", 10, 2, 0),
  31     "in favor of twisted.internet.endpoints.serverFromString",
  32     __name__, "parse")
  33
  34
  35
  36 _DEFAULT = object()
  37
  38 def service(description, factory, default=_DEFAULT, reactor=None):
  39     """
  40     Return the service corresponding to a description.
  41
  42     @param description: The description of the listening port, in the syntax
  43         described by L{twisted.internet.endpoints.server}.
  44
  45     @type description: C{str}
  46
  47     @param factory: The protocol factory which will build protocols for
  48         connections to this service.
  49
  50     @type factory: L{twisted.internet.interfaces.IProtocolFactory}
  51
  52     @type default: C{str} or C{None}
  53
  54     @param default: Do not use this parameter. It has been deprecated since
  55         Twisted 10.2.0.
  56
  57     @rtype: C{twisted.application.service.IService}
  58
  59     @return: the service corresponding to a description of a reliable
  60         stream server.
  61
  62     @see: L{twisted.internet.endpoints.serverFromString}
  63     """
  64     if reactor is None:
  65         from twisted.internet import reactor
  66     if default is _DEFAULT:
  67         default = None
  68     else:
  69         message = "The 'default' parameter was deprecated in Twisted 10.2.0."
  70         if default is not None:
  71             message += (
  72                 "  Use qualified endpoint descriptions; for example, "
  73                 "'tcp:%s'." % (description,))
  74         warnings.warn(
  75             message=message, category=DeprecationWarning, stacklevel=2)
  76     svc = StreamServerEndpointService(
  77         endpoints._serverFromStringLegacy(reactor, description, default),
  78         factory)
  79     svc._raiseSynchronously = True
  80     return svc
  81
  82
  83
  84 def listen(description, factory, default=None):
  85     """Listen on a port corresponding to a description
  86
  87     @type description: C{str}
  88     @type factory: L{twisted.internet.interfaces.IProtocolFactory}
  89     @type default: C{str} or C{None}
  90     @rtype: C{twisted.internet.interfaces.IListeningPort}
  91     @return: the port corresponding to a description of a reliable
  92     virtual circuit server.
  93
  94     See the documentation of the C{parse} function for description
  95     of the semantics of the arguments.
  96     """
  97     from twisted.internet import reactor
  98     name, args, kw = parse(description, factory, default)
  99     return getattr(reactor, 'listen'+name)(*args, **kw)
 100
 101
 102
 103 __all__ = ['parse', 'service', 'listen']