Debian Codegraph @

src/lazr/restfulclient/docs/hosted-files.rst

raw
1 ************
2 Hosted files
3 ************
4
5 Some resources published by lazr.restful are externally hosted files
6 that can have binary representations. lazr.restfulclient gives you
7 access to these resources.
8
9 >>> from lazr.restfulclient.tests.example import CookbookWebServiceClient
10 >>> service = CookbookWebServiceClient()
11
12 An example of a hosted binary file is the cover of a
13 cookbook. "Everyday Greens" starts off with no cover.
14
15 >>> greens = service.cookbooks['Everyday Greens']
16 >>> cover = greens.cover
17 >>> sorted(dir(cover))
18 [..., 'open']
19
20 >>> cover.open()
21 Traceback (most recent call last):
22 ...
23 NotFound: HTTP Error 404: Not Found
24 ...
25
26 You can open a hosted file for write access and write to it as though
27 it were a file on disk.
28
29 >>> image = "Pretend this is an image."
30 >>> len(image)
31 25
32
33 >>> file_handle = cover.open("w", "image/png", "a-cover.png")
34 >>> file_handle.content_type
35 'image/png'
36 >>> file_handle.filename
37 'a-cover.png'
38 >>> print file_handle.last_modified
39 None
40 >>> file_handle.write(image)
41 >>> file_handle.close()
42
43 Once it exists on the server, you can open a hosted file for read
44 access and read it.
45
46 >>> file_handle = cover.open()
47 >>> file_handle.content_type
48 'image/png'
49 >>> file_handle.filename
50 '0'
51 >>> last_modified = file_handle.last_modified
52 >>> last_modified is None
53 False
54 >>> len(file_handle.read())
55 25
56
57 Note that the filename is '0', not 'a-cover.png'. The filename from
58 the server is implementation-dependent and may not have anything to do
59 with the filename the client sent. If the server implementation uses
60 lazr.librarian, it will serve files with the originally uploaded
61 filename, but the example web service uses its own, simpler
62 implementation which serves the file's ID as the filename.
63
64 Modifying a file will change its 'last_modified' attribute.
65
66 >>> file_handle = cover.open("w", "image/png", "another-cover.png")
67 >>> file_handle.write(image)
68 >>> file_handle.close()
69
70 >>> file_handle = cover.open()
71 >>> file_handle.filename
72 '1'
73 >>> last_modified_2 = file_handle.last_modified
74 >>> last_modified == last_modified_2
75 False
76
77 Once a file exists, it can be deleted.
78
79 >>> cover.delete()
80 >>> cover.open()
81 Traceback (most recent call last):
82 ...
83 NotFound: HTTP Error 404: Not Found
84 ...
85
86 Comparing hosted files
87 ----------------------
88
89 Two hosted file objects are the same if they point to the same
90 server-side resource.
91
92 >>> cover = service.cookbooks['Everyday Greens'].cover
93 >>> cover_2 = service.cookbooks['Everyday Greens'].cover
94 >>> cover == cover_2
95 True
96
97 >>> other_cover = service.cookbooks['The Joy of Cooking'].cover
98 >>> cover == other_cover
99 False
100
101 A hosted file can be compared to None, but the comparison never succeeds.
102
103 >>> cover == None
104 False
105
106 Error handling
107 --------------
108
109 The only access modes supported are 'r' and 'w'.
110
111 >>> cover.open("r+")
112 Traceback (most recent call last):
113 ...
114 ValueError: Invalid mode. Supported modes are: r, w
115
116 When opening a file for write access, you must specify the
117 content_type argument.
118
119 >>> cover.open("w")
120 Traceback (most recent call last):
121 ...
122 ValueError: Files opened for write access must specify content_type.
123
124 >>> cover.open("w", "image/png")
125 Traceback (most recent call last):
126 ...
127 ValueError: Files opened for write access must specify filename.
128
129 When opening a file for read access, you must *not* specify the
130 content_type or filename arguments--they come from the server.
131
132 >>> cover.open("r", "image/png")
133 Traceback (most recent call last):
134 ...
135 ValueError: Files opened for read access can't specify content_type.
136
137 >>> cover.open("r", filename="foo.png")
138 Traceback (most recent call last):
139 ...
140 ValueError: Files opened for read access can't specify filename.
141
142
143 Caching
144 -------
145
146 Hosted file resources implement the normal server-side caching
147 mechanism.
148
149 >>> file_handle = cover.open("w", "image/png", "image.png")
150 >>> file_handle.write(image)
151 >>> file_handle.close()
152
153 >>> import httplib2
154 >>> httplib2.debuglevel = 1
155 >>> service = CookbookWebServiceClient()
156 send: ...
157 >>> cover = service.cookbooks['Everyday Greens'].cover
158 send: ...
159
160 The first request for a file retrieves the file from the server.
161
162 >>> len(cover.open().read())
163 send: ...
164 reply: '...303 See Other...
165 reply: '...200 Ok...
166 25
167
168 The second request retrieves the file from the cache.
169
170 >>> len(cover.open().read())
171 send: ...
172 reply: '...303 See Other...
173 reply: '...304 Not Modified...
174 25
175
176
177 Finally, some cleanup code that deletes the cover.
178
179 >>> cover.delete()
180 send: 'DELETE...
181 reply: '...200...
182
183 >>> httplib2.debuglevel = 0