Revision f2d7b5ab

b/.gitignore
1 1
settings.py
2
doc/build
2 3
*.db
3 4
*.pyc
4 5
.DS_Store
b/README
1
Documentation
2
-------------
3

  
4
To build the documentation you need to have Sphinx installed:
5
http://sphinx.pocoo.org/
6

  
7
Run:
8
    python setup.py build_sphinx
9

  
10
The documentation will be built in the doc/build/html directory.
11

  
12
Also run:
13
    python setup.py build_sphinx -b text
14

  
15
Then find the plain text version of the docs in doc/build/text.
16

  
17
Running the server
18
------------------
19

  
20
Enter the pithos dir and run:
21
    python manage.py runserver
22

  
23
This server is useful during development, but should not be used for deployment.
b/doc/source/backends.rst
1
Backends
2
========
3

  
4
.. toctree::
5
   :maxdepth: 1
6
   
7
   base_backend
8
   simple_backend
b/doc/source/base_backend.rst
1
BaseBackend
2
===========
3

  
4
.. automodule:: pithos.backends.base
b/doc/source/conf.py
1
# -*- coding: utf-8 -*-
2
#
3
# Pithos documentation build configuration file, created by
4
# sphinx-quickstart on Wed May 18 12:42:48 2011.
5
#
6
# This file is execfile()d with the current directory set to its containing dir.
7
#
8
# Note that not all possible configuration values are present in this
9
# autogenerated file.
10
#
11
# All configuration values have a default; values that are commented out
12
# serve to show the default.
13

  
14
import sys, os
15

  
16
# If extensions (or modules to document with autodoc) are in another directory,
17
# add these directories to sys.path here. If the directory is relative to the
18
# documentation root, use os.path.abspath to make it absolute, like shown here.
19
sys.path.insert(0, os.path.abspath('..'))
20

  
21
from pithos import settings
22
from django.core.management import setup_environ
23
setup_environ(settings)
24

  
25
# -- General configuration -----------------------------------------------------
26

  
27
# If your documentation needs a minimal Sphinx version, state it here.
28
#needs_sphinx = '1.0'
29

  
30
# Add any Sphinx extension module names here, as strings. They can be extensions
31
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
32
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.viewcode']
33

  
34
# Add any paths that contain templates here, relative to this directory.
35
templates_path = ['_templates']
36

  
37
# The suffix of source filenames.
38
source_suffix = '.rst'
39

  
40
# The encoding of source files.
41
#source_encoding = 'utf-8-sig'
42

  
43
# The master toctree document.
44
master_doc = 'index'
45

  
46
# General information about the project.
47
project = u'Pithos'
48
copyright = u'2011, Pithos Storage Team'
49

  
50
# The version info for the project you're documenting, acts as replacement for
51
# |version| and |release|, also used in various other places throughout the
52
# built documents.
53
#
54
# The short X.Y version.
55
version = '2'
56
# The full version, including alpha/beta/rc tags.
57
release = '2'
58

  
59
# The language for content autogenerated by Sphinx. Refer to documentation
60
# for a list of supported languages.
61
#language = None
62

  
63
# There are two options for replacing |today|: either, you set today to some
64
# non-false value, then it is used:
65
#today = ''
66
# Else, today_fmt is used as the format for a strftime call.
67
#today_fmt = '%B %d, %Y'
68

  
69
# List of patterns, relative to source directory, that match files and
70
# directories to ignore when looking for source files.
71
exclude_patterns = ['_build']
72

  
73
# The reST default role (used for this markup: `text`) to use for all documents.
74
#default_role = None
75

  
76
# If true, '()' will be appended to :func: etc. cross-reference text.
77
#add_function_parentheses = True
78

  
79
# If true, the current module name will be prepended to all description
80
# unit titles (such as .. function::).
81
#add_module_names = True
82

  
83
# If true, sectionauthor and moduleauthor directives will be shown in the
84
# output. They are ignored by default.
85
#show_authors = False
86

  
87
# The name of the Pygments (syntax highlighting) style to use.
88
pygments_style = 'sphinx'
89

  
90
# A list of ignored prefixes for module index sorting.
91
#modindex_common_prefix = []
92

  
93

  
94
# -- Options for HTML output ---------------------------------------------------
95

  
96
# The theme to use for HTML and HTML Help pages.  See the documentation for
97
# a list of builtin themes.
98
html_theme = 'nature'
99

  
100
# Theme options are theme-specific and customize the look and feel of a theme
101
# further.  For a list of options available for each theme, see the
102
# documentation.
103
#html_theme_options = {}
104

  
105
# Add any paths that contain custom themes here, relative to this directory.
106
#html_theme_path = []
107

  
108
# The name for this set of Sphinx documents.  If None, it defaults to
109
# "<project> v<release> documentation".
110
#html_title = None
111

  
112
# A shorter title for the navigation bar.  Default is the same as html_title.
113
#html_short_title = None
114

  
115
# The name of an image file (relative to this directory) to place at the top
116
# of the sidebar.
117
#html_logo = None
118

  
119
# The name of an image file (within the static path) to use as favicon of the
120
# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
121
# pixels large.
122
#html_favicon = None
123

  
124
# Add any paths that contain custom static files (such as style sheets) here,
125
# relative to this directory. They are copied after the builtin static files,
126
# so a file named "default.css" will overwrite the builtin "default.css".
127
html_static_path = ['_static']
128

  
129
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
130
# using the given strftime format.
131
#html_last_updated_fmt = '%b %d, %Y'
132

  
133
# If true, SmartyPants will be used to convert quotes and dashes to
134
# typographically correct entities.
135
#html_use_smartypants = True
136

  
137
# Custom sidebar templates, maps document names to template names.
138
#html_sidebars = {}
139

  
140
# Additional templates that should be rendered to pages, maps page names to
141
# template names.
142
#html_additional_pages = {}
143

  
144
# If false, no module index is generated.
145
#html_domain_indices = True
146

  
147
# If false, no index is generated.
148
#html_use_index = True
149

  
150
# If true, the index is split into individual pages for each letter.
151
#html_split_index = False
152

  
153
# If true, links to the reST sources are added to the pages.
154
#html_show_sourcelink = True
155

  
156
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
157
#html_show_sphinx = True
158

  
159
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
160
#html_show_copyright = True
161

  
162
# If true, an OpenSearch description file will be output, and all pages will
163
# contain a <link> tag referring to it.  The value of this option must be the
164
# base URL from which the finished HTML is served.
165
#html_use_opensearch = ''
166

  
167
# This is the file name suffix for HTML files (e.g. ".xhtml").
168
#html_file_suffix = None
169

  
170
# Output file base name for HTML help builder.
171
htmlhelp_basename = 'Pithosdoc'
172

  
173

  
174
# -- Options for LaTeX output --------------------------------------------------
175

  
176
# The paper size ('letter' or 'a4').
177
#latex_paper_size = 'letter'
178

  
179
# The font size ('10pt', '11pt' or '12pt').
180
#latex_font_size = '10pt'
181

  
182
# Grouping the document tree into LaTeX files. List of tuples
183
# (source start file, target name, title, author, documentclass [howto/manual]).
184
latex_documents = [
185
  ('index', 'Pithos.tex', u'Pithos Documentation',
186
   u'Pithos Storage Team', 'manual'),
187
]
188

  
189
# The name of an image file (relative to this directory) to place at the top of
190
# the title page.
191
#latex_logo = None
192

  
193
# For "manual" documents, if this is true, then toplevel headings are parts,
194
# not chapters.
195
#latex_use_parts = False
196

  
197
# If true, show page references after internal links.
198
#latex_show_pagerefs = False
199

  
200
# If true, show URL addresses after external links.
201
#latex_show_urls = False
202

  
203
# Additional stuff for the LaTeX preamble.
204
#latex_preamble = ''
205

  
206
# Documents to append as an appendix to all manuals.
207
#latex_appendices = []
208

  
209
# If false, no module index is generated.
210
#latex_domain_indices = True
211

  
212

  
213
# -- Options for manual page output --------------------------------------------
214

  
215
# One entry per manual page. List of tuples
216
# (source start file, name, description, authors, manual section).
217
man_pages = [
218
    ('index', 'pithos', u'Pithos Documentation',
219
     [u'Pithos Storage Team'], 1)
220
]
221

  
222

  
223
autodoc_default_flags = ['members']
b/doc/source/devguide.rst
1
Pithos v2 Developer Guide
2
=========================
3

  
4
Introduction
5
------------
6

  
7
Pithos is a storage service implemented by GRNET (http://www.grnet.gr). Data is stored as objects, organized in containers, belonging to an account. This hierarchy of storage layers has been inspired by the OpenStack Object Storage (OOS) API and similar CloudFiles API by Rackspace. The Pithos API follows the OOS API as closely as possible. One of the design requirements has been to be able to use Pithos with clients built for the OOS, without changes.
8

  
9
This document's goals are:
10

  
11
* Define the Pithos ReST API that allows the storage and retrieval of data and metadata via HTTP calls
12
* Specify metadata semantics and user interface guidelines for a common experience across client software implementations
13

  
14
The present document is meant to be read alongside the OOS API documentation. Thus, it is suggested that the reader is familiar with associated technologies, the OOS API as well as the first version of the Pithos API. This document refers to the second version of Pithos. Information on the first version of the storage API can be found at http://code.google.com/p/gss.
15

  
16
Whatever marked as to be determined (**TBD**), should not be considered by implementors.
17

  
18
Document Revisions
19
^^^^^^^^^^^^^^^^^^
20

  
21
=========================  ================================
22
Revision                   Description
23
=========================  ================================
24
0.2 (May 25, 2011)         Add object meta listing and filtering in containers.
25
\                          Support for multi-range object GET requests.
26
0.1 (May 17, 2011)         Initial release. Based on OpenStack Object Storage Developer Guide API v1 (Apr. 15, 2011).
27
=========================  ================================
28

  
29
The Pithos API
30
--------------
31

  
32
The URI requests supported by Pithos follow one of the following forms:
33

  
34
* Top level: ``https://hostname/v1/``
35
* Account level: ``https://hostname/v1/<account>``
36
* Container level: ``https://hostname/v1/<account>/<container>``
37
* Object level: ``https://hostname/v1/<account>/<container>/<object>``
38

  
39
All requests must include an ``X-Auth-Token``, except from those that refer to publicly available files (**TBD**). The process of obtaining the token is still to be determined (**TBD**).
40

  
41
The allowable request operations and corresponding return codes per level are presented in the remainder of this chapter. Common to all requests are the following return codes.
42

  
43
=========================  ================================
44
Return Code                Description
45
=========================  ================================
46
400 (Bad Request)          The request is invalid
47
401 (Unauthorized)         Request not allowed
48
404 (Not Found)            The requested resource was not found
49
503 (Service Unavailable)  The request cannot be completed because of an internal error
50
=========================  ================================
51

  
52
Top Level
53
^^^^^^^^^
54

  
55
List of operations:
56

  
57
=========  ==================
58
Operation  Description
59
=========  ==================
60
GET        Authentication. This is kept for compatibility with the OOS API
61
=========  ==================
62

  
63
GET
64
"""
65

  
66
If the ``X-Auth-User`` and ``X-Auth-Key`` headers are given, a dummy ``X-Auth-Token`` and ``X-Storage-Url`` will be replied, which can be used as a guest token/namespace for testing Pithos.
67

  
68
================  =====================
69
Return Code       Description
70
================  =====================
71
204 (No Content)  The request succeeded
72
================  =====================
73

  
74

  
75
Account Level
76
^^^^^^^^^^^^^
77

  
78
List of operations:
79

  
80
=========  ==================
81
Operation  Description
82
=========  ==================
83
HEAD       Retrieve account metadata
84
GET        List containers
85
POST       Update account metadata
86
=========  ==================
87

  
88
HEAD
89
""""
90

  
91
No request parameters/headers.
92

  
93
==========================  =====================
94
Reply Header Name           Value
95
==========================  =====================
96
X-Account-Container-Count   The total number of containers
97
X-Account-Object-Count      The total number of objects (**TBD**)
98
X-Account-Bytes-Used        The total number of bytes stored
99
X-Account-Bytes-Remaining   The total number of bytes remaining (**TBD**)
100
X-Account-Last-Login        The last login (**TBD**)
101
X-Account-Meta-*            Optional user defined metadata
102
Last-Modified               The last object modification date
103
==========================  =====================
104

  
105
|
106

  
107
================  =====================
108
Return Code       Description
109
================  =====================
110
204 (No Content)  The request succeeded
111
================  =====================
112

  
113

  
114
GET
115
"""
116

  
117
====================  ===========================
118
Request Header Name   Value
119
====================  ===========================
120
If-Modified-Since     Retrieve if account has changed since provided timestamp
121
If-Unmodified-Since   Retrieve if account has not changed since provided timestamp
122
====================  ===========================
123

  
124
|
125

  
126
======================  =========================
127
Request Parameter Name  Value
128
======================  =========================
129
limit                   The amount of results requested (default is 10000)
130
marker                  Return containers with name lexicographically after marker
131
format                  Optional extended reply type (can be ``json`` or ``xml``)
132
======================  =========================
133

  
134
The reply is a list of container names. Account headers (as in a ``HEAD`` request) will also be included.
135
If a ``format=xml`` or ``format=json`` argument is given, extended information on the containers will be returned, serialized in the chosen format.
136
For each container, the information will include all container metadata (names will be in lower case and with hyphens replaced with underscores):
137

  
138
===================  ============================
139
Name                 Description
140
===================  ============================
141
name                 The name of the container
142
count                The number of objects inside the container
143
bytes                The total size of the objects inside the container
144
last_modified        The last object modification date
145
x_container_meta_*   Optional user defined metadata
146
===================  ============================
147

  
148
For examples of container details returned in JSON/XML formats refer to the OOS API documentation.
149

  
150
================  =====================
151
Return Code       Description
152
================  =====================
153
200 (OK)          The request succeeded
154
204 (No Content)  The account has no containers (only for non-extended replies)
155
================  =====================
156

  
157
Will use a ``200`` return code if the reply is of type json/xml.
158

  
159

  
160
POST
161
""""
162

  
163
====================  ===========================
164
Request Header Name   Value
165
====================  ===========================
166
X-Account-Meta-*      Optional user defined metadata
167
====================  ===========================
168

  
169
No reply content/headers.
170

  
171
The update operation will overwrite all user defined metadata.
172

  
173
================  ===============================
174
Return Code       Description
175
================  ===============================
176
202 (Accepted)    The request has been accepted
177
================  ===============================
178

  
179

  
180
Container Level
181
^^^^^^^^^^^^^^^
182

  
183
List of operations:
184

  
185
=========  ============================
186
Operation  Description
187
=========  ============================
188
HEAD       Retrieve container metadata
189
GET        List objects
190
PUT        Create/update container
191
POST       Update container metadata
192
DELETE     Delete container
193
=========  ============================
194

  
195

  
196
HEAD
197
""""
198

  
199
No request parameters/headers.
200

  
201
==========================  ===============================
202
Reply Header Name           Value
203
==========================  ===============================
204
X-Container-Object-Count    The total number of objects in the container
205
X-Container-Bytes-Used      The total number of bytes of all objects stored
206
X-Container-Meta-*          Optional user defined metadata
207
X-Container-Object-Meta     A list with all meta keys used by objects
208
Last-Modified               The last object modification date
209
==========================  ===============================
210

  
211
The keys returned in ``X-Container-Object-Meta`` are all the unique strings after the ``X-Object-Meta-`` prefix.
212

  
213
================  ===============================
214
Return Code       Description
215
================  ===============================
216
204 (No Content)  The request succeeded
217
================  ===============================
218

  
219

  
220
GET
221
"""
222

  
223
====================  ===========================
224
Request Header Name   Value
225
====================  ===========================
226
If-Modified-Since     Retrieve if container has changed since provided timestamp
227
If-Unmodified-Since   Retrieve if container has not changed since provided timestamp
228
====================  ===========================
229

  
230
|
231

  
232
======================  ===================================
233
Request Parameter Name  Value
234
======================  ===================================
235
limit                   The amount of results requested (default is 10000)
236
marker                  Return containers with name lexicographically after marker
237
prefix                  Return objects starting with prefix
238
delimiter               Return objects up to the delimiter (discussion follows)
239
path                    Assume ``prefix=path`` and ``delimiter=/``
240
format                  Optional extended reply type (can be ``json`` or ``xml``)
241
meta                    Return objects having the specified meta keys (can be a comma separated list)
242
======================  ===================================
243

  
244
The ``path`` parameter overrides ``prefix`` and ``delimiter``. When using ``path``, results will include objects ending in ``delimiter``.
245

  
246
The keys given with ``meta`` will be matched with the strings after the ``X-Object-Meta-`` prefix.
247

  
248
The reply is a list of object names. Container headers (as in a ``HEAD`` request) will also be included.
249
If a ``format=xml`` or ``format=json`` argument is given, extended information on the objects will be returned, serialized in the chosen format.
250
For each object, the information will include all object metadata (names will be in lower case and with hyphens replaced with underscores):
251

  
252
===================  ======================================
253
Name                 Description
254
===================  ======================================
255
name                 The name of the object
256
hash                 The MD5 hash of the object
257
bytes                The size of the object
258
content_type         The MIME content type of the object
259
content_encoding     The encoding of the object (optional)
260
last_modified        The last object modification date
261
x_object_manifest    Large object support
262
x_object_meta_*      Optional user defined metadata
263
===================  ======================================
264

  
265
Extended replies may also include virtual directory markers in separate sections of the ``json`` or ``xml`` results.
266
Virtual directory markers are only included when ``delimiter`` is explicitly set. They correspond to the substrings up to and including the first occurrence of the delimiter.
267
In JSON results they appear as dictionaries with only a ``"subdir"`` key. In XML results they appear interleaved with ``<object>`` tags as ``<subdir name="..." />``.
268
In case there is an object with the same name as a virtual directory marker, the object will be returned.
269
 
270
For examples of object details returned in JSON/XML formats refer to the OOS API documentation.
271

  
272
================  ===============================
273
Return Code       Description
274
================  ===============================
275
200 (OK)          The request succeeded
276
204 (No Content)  The account has no containers (only for non-extended replies)
277
================  ===============================
278

  
279
Will use a ``200`` return code if the reply is of type json/xml.
280

  
281

  
282
PUT
283
"""
284

  
285
====================  ================================
286
Request Header Name   Value
287
====================  ================================
288
X-Container-Meta-*    Optional user defined metadata
289
====================  ================================
290
 
291
No reply content/headers.
292
 
293
================  ===============================
294
Return Code       Description
295
================  ===============================
296
201 (Created)     The container has been created
297
202 (Accepted)    The request has been accepted
298
================  ===============================
299

  
300

  
301
POST
302
""""
303

  
304
====================  ================================
305
Request Header Name   Value
306
====================  ================================
307
X-Container-Meta-*    Optional user defined metadata
308
====================  ================================
309

  
310
No reply content/headers.
311

  
312
The update operation will overwrite all user defined metadata.
313

  
314
================  ===============================
315
Return Code       Description
316
================  ===============================
317
202 (Accepted)    The request has been accepted
318
================  ===============================
319

  
320

  
321
DELETE
322
""""""
323

  
324
No request parameters/headers.
325

  
326
No reply content/headers.
327

  
328
================  ===============================
329
Return Code       Description
330
================  ===============================
331
204 (No Content)  The request succeeded
332
409 (Conflict)    The container is not empty
333
================  ===============================
334

  
335

  
336
Object Level
337
^^^^^^^^^^^^
338

  
339
List of operations:
340

  
341
=========  =================================
342
Operation  Description
343
=========  =================================
344
HEAD       Retrieve object metadata
345
GET        Read object data
346
PUT        Write object data or copy/move object
347
COPY       Copy object
348
MOVE       Move object
349
POST       Update object metadata
350
DELETE     Delete object
351
=========  =================================
352

  
353

  
354
HEAD
355
""""
356

  
357
No request parameters/headers.
358

  
359
==========================  ===============================
360
Reply Header Name           Value
361
==========================  ===============================
362
ETag                        The MD5 hash of the object
363
Content-Length              The size of the object
364
Content-Type                The MIME content type of the object
365
Last-Modified               The last object modification date
366
Content-Encoding            The encoding of the object (optional)
367
Content-Disposition         The presentation style of the object (optional)
368
X-Object-Manifest           Large object support (optional)
369
X-Object-Meta-*             Optional user defined metadata
370
==========================  ===============================
371

  
372
|
373

  
374
================  ===============================
375
Return Code       Description
376
================  ===============================
377
204 (No Content)  The request succeeded
378
================  ===============================
379

  
380

  
381
GET
382
"""
383

  
384
====================  ================================
385
Request Header Name   Value
386
====================  ================================
387
Range                 Optional range of data to retrieve
388
If-Match              Retrieve if ETags match
389
If-None-Match         Retrieve if ETags don't match
390
If-Modified-Since     Retrieve if object has changed since provided timestamp
391
If-Unmodified-Since   Retrieve if object has not changed since provided timestamp
392
====================  ================================
393

  
394
The reply is the object's data (or part of it). Object headers (as in a ``HEAD`` request) will also be included.
395

  
396
The ``Range`` header may include multiple ranges, as outlined in RFC2616. Then the ``Content-Type`` of the reply will be ``multipart/byteranges`` and each part will include a ``Content-Range`` header.
397

  
398
==========================  ===============================
399
Reply Header Name           Value
400
==========================  ===============================
401
ETag                        The MD5 hash of the object
402
Content-Length              The size of the data returned
403
Content-Type                The MIME content type of the object
404
Content-Range               The range of data included (only on a single range request)
405
Last-Modified               The last object modification date
406
Content-Encoding            The encoding of the object (optional)
407
Content-Disposition         The presentation style of the object (optional)
408
X-Object-Manifest           Large object support (optional)
409
X-Object-Meta-*             Optional user defined metadata
410
==========================  ===============================
411

  
412
|
413

  
414
===========================  ==============================
415
Return Code                  Description
416
===========================  ==============================
417
200 (OK)                     The request succeeded
418
206 (Partial Content)        The range request succeeded
419
304 (Not Modified)           The object has not been modified
420
412 (Precondition Failed)    The condition set can not be satisfied
421
416 (Range Not Satisfiable)  The requested range is out of limits
422
===========================  ==============================
423

  
424

  
425
PUT
426
"""
427

  
428
====================  ================================
429
Request Header Name   Value
430
====================  ================================
431
ETag                  The MD5 hash of the object (optional to check written data)
432
Content-Length        The size of the data written
433
Content-Type          The MIME content type of the object
434
Transfer-Encoding     Set to ``chunked`` to specify incremental uploading (if used, ``Content-Length`` is ignored)
435
X-Copy-From           The source path in the form ``/<container>/<object>``
436
X-Move-From           The source path in the form ``/<container>/<object>``
437
Content-Encoding      The encoding of the object (optional)
438
Content-Disposition   The presentation style of the object (optional)
439
X-Object-Manifest     Large object support (optional)
440
X-Object-Meta-*       Optional user defined metadata
441
====================  ================================
442

  
443
|
444

  
445
==========================  ===============================
446
Reply Header Name           Value
447
==========================  ===============================
448
ETag                        The MD5 hash of the object (on create)
449
==========================  ===============================
450

  
451
|
452

  
453
===========================  ==============================
454
Return Code                  Description
455
===========================  ==============================
456
201 (Created)                The object has been created
457
411 (Length Required)        Missing ``Content-Length`` or ``Content-Type`` in the request
458
422 (Unprocessable Entity)   The MD5 checksum of the data written to the storage system does not match the (optionally) supplied ETag value
459
===========================  ==============================
460

  
461

  
462
COPY
463
""""
464

  
465
====================  ================================
466
Request Header Name   Value
467
====================  ================================
468
Destination           The destination path in the form ``/<container>/<object>``
469
Content-Type          The MIME content type of the object (optional)
470
Content-Encoding      The encoding of the object (optional)
471
Content-Disposition   The presentation style of the object (optional)
472
X-Object-Manifest     Large object support (optional)
473
X-Object-Meta-*       Optional user defined metadata
474
====================  ================================
475

  
476
No reply content/headers.
477

  
478
===========================  ==============================
479
Return Code                  Description
480
===========================  ==============================
481
201 (Created)                The object has been created
482
===========================  ==============================
483

  
484

  
485
MOVE
486
""""
487

  
488
Same as ``COPY``.
489

  
490

  
491
POST
492
""""
493

  
494
====================  ================================
495
Request Header Name   Value
496
====================  ================================
497
Content-Encoding      The encoding of the object (optional)
498
Content-Disposition   The presentation style of the object (optional)
499
X-Object-Manifest     Large object support (optional)
500
X-Object-Meta-*       Optional user defined metadata
501
====================  ================================
502

  
503
No reply content/headers.
504

  
505
The allowed headers are considered to be user defined metadata. The update operation will overwrite all previous values and remove any keys not supplied.
506

  
507
===========================  ==============================
508
Return Code                  Description
509
===========================  ==============================
510
202 (Accepted)               The request has been accepted
511
===========================  ==============================
512

  
513

  
514
DELETE
515
""""""
516

  
517
No request parameters/headers.
518

  
519
No reply content/headers.
520

  
521
===========================  ==============================
522
Return Code                  Description
523
===========================  ==============================
524
204 (No Content)             The request succeeded
525
===========================  ==============================
526

  
527

  
528
Summary
529
^^^^^^^
530

  
531
List of differences from the OOS API:
532

  
533
* Support for ``X-Account-Meta-*`` style headers at the account level. Use ``POST`` to update.
534
* Support for ``X-Container-Meta-*`` style headers at the account level. Can be set when creating via ``PUT``. Use ``POST`` to update.
535
* Header ``X-Container-Object-Meta`` at the container level and parameter ``meta`` in container listings.
536
* All metadata replies, at all levels, include latest modification information.
537
* At all levels, a ``GET`` request may use ``If-Modified-Since`` and ``If-Unmodified-Since`` headers.
538
* Container/object lists include all associated metadata if the reply is of type json/xml. Some names are kept to their OOS API equivalents for compatibility. 
539
* Object metadata allowed, in addition to ``X-Object-Meta-*``: ``Content-Encoding``, ``Content-Disposition``, ``X-Object-Manifest``. These are all replaced with every update operation.
540
* Multi-range object GET support as outlined in RFC2616.
541
* Object ``MOVE`` support.
542

  
543
Clarifications/suggestions:
544

  
545
* Authentication is done by another system. The token is used in the same way, but it is obtained differently. The top level ``GET`` request is kept compatible with the OOS API and allows for guest/testing operations.
546
* Some processing is done in the variable part of all ``X-*-Meta-*`` headers. If it includes underscores, they will be converted to dashes and the first letter of all intra-dash strings will be capitalized.
547
* A ``GET`` reply for a level will include all headers of the corresponding ``HEAD`` request.
548
* To avoid conflicts between objects and virtual directory markers in container listings, it is recommended that object names do not end with the delimiter used.
549
* The ``Accept`` header may be used in requests instead of the ``format`` parameter to specify the desired reply format. The parameter overrides the header.
550
* Container/object lists use a ``200`` return code if the reply is of type json/xml. The reply will include an empty json/xml.
551
* In headers, dates are formatted according to RFC 1123. In extended information listings, dates are formatted according to ISO 8601.
552
* While ``X-Object-Manifest`` can be set and unset, large object support is not yet implemented (**TBD**).
553

  
554
The Pithos Client
555
-----------------
556

  
557
User Experience
558
^^^^^^^^^^^^^^^
559

  
560
Hopefully this API will allow for a multitude of client implementations, each supporting a different device or operating system. All clients will be able to manipulate containers and objects - even software only designed for OOS API compatibility. But a Pithos interface should not be only about showing containers and folders. There are some extra user interface elements and functionalities that should be common to all implementations.
561

  
562
Upon entrance to the service, a user is presented with the following elements - which can be represented as folders or with other related icons:
563

  
564
* The ``home`` element, which is used as the default entry point to the user's "files". Objects under ``home`` are represented in the usual hierarchical organization of folders and files.
565
* The ``trash`` element, which contains files that have been marked for deletion, but can still be recovered.
566
* The ``shared`` element, which contains all objects shared by the user to other users of the system.
567
* The ``others`` element, which contains all objects that other users share with the user.
568
* The ``tags`` element, which lists the names of tags the user has defined. This can be an entry point to list all files that have been assigned a specific tag or manage tags in general (remove a tag completely, rename a tag etc.).
569
* The ``groups`` element, which contains the names of groups the user has defined. Each group consists of a user list. Group creation, deletion, and manipulation is carried out by actions originating here.
570

  
571
Objects in Pithos can be:
572

  
573
* Assigned custom tags.
574
* Moved to trash and then deleted.
575
* Shared with specific permissions.
576
* Made public (shared with non-Pithos users).
577
* Set to monitor changes via version tracking.
578

  
579
Some of these functions are performed by the client software and some by the Pithos server. Client-driven functionality is based on specific metadata that should be handled equally across implementations. These metadata names are discussed in the next chapter. 
580

  
581
Conventions and Metadata Specification
582
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
583

  
584
Pithos clients should use the ``pithos`` container for all Pithos objects. Object names use the ``/`` delimiter to impose a hierarchy of folders and files.
585

  
586
At the object level, tags are implemented by managing metadata keys. The client software should allow the user to use any string as a tag (except ``trash``) and then set the corresponding ``X-Object-Meta-<tag>`` key at the server. The API extensions provided, allow for listing all tags in a container and filtering object listings based on one or more tags. The tag list is sufficient for implementing the ``tags`` element, either as a special, virtual folder (as done in the first version of Pithos), or as an application menu.
587

  
588
To manage the deletion of files use the same API and the ``X-Object-Meta-Trash`` key. The string ``trash`` can not be used as a tag. The ``trash`` element should be presented as a folder, although with no hierarchy.
589

  
590
The metadata specification is summarized in the following table.
591

  
592
===========================  ==============================
593
Metadata Name                Value
594
===========================  ==============================
595
X-Object-Meta-Trash          Set to ``true`` if the object has been moved to the trash
596
X-Object-Meta-*              Use for other tags that apply to the object
597
===========================  ==============================
b/doc/source/index.rst
1
Pithos Documentation
2
====================
3

  
4
Contents:
5

  
6
.. toctree::
7
   :maxdepth: 2
8
   
9
   devguide
10
   backends
11

  
12

  
13
Indices and tables
14
==================
15

  
16
* :ref:`genindex`
17
* :ref:`modindex`
18
* :ref:`search`
19

  
b/doc/source/simple_backend.rst
1
SimpleBackend
2
=============
3

  
4
.. automodule:: pithos.backends.simple
b/pithos/__init__.py
1
__version__ = '0.2'
b/setup.cfg
1
[build_sphinx]
2
all_files = 1
3
build-dir = doc/build
4
source-dir = doc/source
5

  
b/setup.py
1
#!/usr/bin/env python
2

  
3
#from distutils.core import setup
4
from setuptools import setup
5

  
6
from pithos import __version__ as version
7

  
8
setup(
9
    name='Pithos',
10
    version=version,
11
    description='Pithos file storage service',
12
    author='GRNET',
13
    author_email='pithos@grnet.gr',
14
    url='http://code.grnet.gr/projects/pithos',
15
    packages=['pithos'],
16
)

Also available in: Unified diff