1# This program is free software; you can redistribute it and/or modify it under
2# the terms of the (LGPL) GNU Lesser General Public License as published by the
3# Free Software Foundation; either version 3 of the License, or (at your
4# option) any later version.
5#
6# This program is distributed in the hope that it will be useful, but WITHOUT
7# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
8# FOR A PARTICULAR PURPOSE. See the GNU Library Lesser General Public License
9# for more details at ( http://www.gnu.org/licenses/lgpl.html ).
10#
11# You should have received a copy of the GNU Lesser General Public License
12# along with this program; if not, write to the Free Software Foundation, Inc.,
13# 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
14# written by: Jeff Ortel ( jortel@redhat.com )
15
16"""
17Contains transport interface (classes).
18
19"""
20
21from suds import UnicodeMixin
22
23
24class TransportError(Exception):
25    def __init__(self, reason, httpcode, fp=None):
26        Exception.__init__(self, reason)
27        self.httpcode = httpcode
28        self.fp = fp
29
30
31class Request(UnicodeMixin):
32    """
33    A transport request.
34
35    @ivar url: The URL for the request.
36    @type url: str
37    @ivar message: The message to be sent in a POST request.
38    @type message: str
39    @ivar headers: The HTTP headers to be used for the request.
40    @type headers: dict
41
42    """
43
44    def __init__(self, url, message=None):
45        """
46        @param url: The URL for the request.
47        @type url: str
48        @param message: The (optional) message to be sent in the request.
49        @type message: str
50
51        """
52        self.url = url
53        self.headers = {}
54        self.message = message
55
56    def __unicode__(self):
57        return u"""\
58URL: %s
59HEADERS: %s
60MESSAGE:
61%s""" % (self.url, self.headers, self.message)
62
63
64class Reply(UnicodeMixin):
65    """
66    A transport reply.
67
68    @ivar code: The HTTP code returned.
69    @type code: int
70    @ivar message: The message to be sent in a POST request.
71    @type message: str
72    @ivar headers: The HTTP headers to be used for the request.
73    @type headers: dict
74
75    """
76
77    def __init__(self, code, headers, message):
78        """
79        @param code: The HTTP code returned.
80        @type code: int
81        @param headers: The HTTP returned headers.
82        @type headers: dict
83        @param message: The (optional) reply message received.
84        @type message: str
85
86        """
87        self.code = code
88        self.headers = headers
89        self.message = message
90
91    def __unicode__(self):
92        return u"""\
93CODE: %s
94HEADERS: %s
95MESSAGE:
96%s""" % (self.code, self.headers, self.message)
97
98
99class Transport:
100    """The transport I{interface}."""
101
102    def __init__(self):
103        from suds.transport.options import Options
104        self.options = Options()
105
106    def open(self, request):
107        """
108        Open the URL in the specified request.
109
110        @param request: A transport request.
111        @type request: L{Request}
112        @return: An input stream.
113        @rtype: stream
114        @raise TransportError: On all transport errors.
115
116        """
117        raise Exception('not-implemented')
118
119    def send(self, request):
120        """
121        Send soap message. Implementations are expected to handle:
122            - proxies
123            - I{HTTP} headers
124            - cookies
125            - sending message
126            - brokering exceptions into L{TransportError}
127
128        @param request: A transport request.
129        @type request: L{Request}
130        @return: The reply
131        @rtype: L{Reply}
132        @raise TransportError: On all transport errors.
133
134        """
135        raise Exception('not-implemented')
136