Permalink
Browse files

Documentation update

  • Loading branch information...
1 parent 5ff9263 commit b5b145c212d9cfdd1113a944e5da735b9c9c4fc0 @schwarty schwarty committed Feb 22, 2011
View
Binary file not shown.
View
@@ -15,6 +15,7 @@ pyxnat: Xnat in Python
starters_tutorial.rst
advanced_tutorial.rst
reference_documentation.rst
+ CHANGES.rst
Introduction
------------
View
@@ -38,10 +38,10 @@ def set_autolearn(self, auto=True, tick=30):
""" Once in a while queries will persist additional
information on the server. This information is available
through the following methods of this class:
- - experiment_types
- - assessor_types
- - scan_types
- - reconstruction_types
+ - experiment_types
+ - assessor_types
+ - scan_types
+ - reconstruction_types
It is also transparently used in insert operations.
@@ -68,14 +68,13 @@ def datatypes(self, pattern='*', fields_pattern=None):
pattern: string
Pattern for the datatype. May include wildcards.
fields_pattern: string
- Pattern for the datafields. May include wildcards. If
- specified, datafields will be returned instead of
- datatypes.
+ - Pattern for the datafields -- may include wildcards.
+ - If specified, datafields will be returned instead of
+ datatypes.
Returns
-------
- List of datatypes or datafields depending on the argument
- usage.
+ list : datatypes or datafields depending on the argument usage.
"""
search_els = self._get_json('/REST/search/elements?format=json')
@@ -112,7 +111,7 @@ def experiment_types(self):
See Also
--------
- Inspector.set_autolean()
+ Inspector.set_autolearn()
"""
return self._resource_types('experiment')
@@ -122,7 +121,7 @@ def assessor_types(self):
See Also
--------
- Inspector.set_autolean()
+ Inspector.set_autolearn()
"""
return self._resource_types('assessor')
@@ -132,7 +131,7 @@ def reconstruction_types(self):
See Also
--------
- Inspector.set_autolean()
+ Inspector.set_autolearn()
"""
return self._resource_types('reconstruction')
@@ -142,7 +141,7 @@ def scan_types(self):
See Also
--------
- Inspector.set_autolean()
+ Inspector.set_autolearn()
"""
return self._resource_types('scan')
@@ -224,8 +223,6 @@ def assessor_values(self, experiment_type, project=None):
An experiment type.
project: string
Optional. Restrict operation to a project.
- project: string
- Optional. Restrict operation to a project.
"""
return self._sub_experiment_values('assessor',
project, experiment_type)
@@ -248,8 +245,6 @@ def scan_values(self, experiment_type, project=None):
An experiment type.
project: string
Optional. Restrict operation to a project.
- project: string
- Optional. Restrict operation to a project.
"""
return self._sub_experiment_values('scan', project, experiment_type)
@@ -271,8 +266,6 @@ def reconstruction_values(self, experiment_type, project=None):
An experiment type.
project: string
Optional. Restrict operation to a project.
- project: string
- Optional. Restrict operation to a project.
"""
return self._sub_experiment_values('reconstruction',
project, experiment_type)
@@ -279,7 +279,7 @@ def save_config(self, location):
.. warning::
Since the password is saved as well, make sure the file
- is saved at a safe location with correct permissions.
+ is saved at a safe location with appropriate permissions.
Parameters
----------
View
@@ -222,33 +222,32 @@ def create(self, **params):
Any non-existing ancestor will be created as well.
.. warning::
-
- An element resource both have an ID and a label that can
- be used to access it. At the moment, XNAT REST API defines
- the label when creating an element, but not the ID, which
- is generated. It means that the `name` given to a resource
- may not appear when listing the resources because the IDs
- will appear, not the labels.
+ An element resource both have an ID and a label that
+ can be used to access it. At the moment, XNAT REST API
+ defines the label when creating an element, but not
+ the ID, which is generated. It means that the `name`
+ given to a resource may not appear when listing the
+ resources because the IDs will appear, not the labels.
.. note::
- To set up additional variables for the element at its
+ To set up additional variables for the element at its
creation it is possible to use shortcuts defined in the
- XNAT REST documentation or xpath in the schema::
- element.create(ID='theid')
- subject.create(**{'xnat:subjectData/ID':'theid'})
+ XNAT REST documentation or xpath in the schema:
+ - element.create(ID='theid')
+ - subject.create(**{'xnat:subjectData/ID':'theid'})
+
Parameters
----------
params: keywords
- Specify the datatype of the element resource and of any
- ancestor that may need to be created. The keywords
- correspond to the levels in the REST hierarchy,
- i.e. Interface.inspect.rest_hierarchy()
-
- If an element is created with no specified type:
- - if its name matches a naming convention, this type
- will be used
- - else a default type is defined in the schema module
+ - Specify the datatype of the element resource and of
+ any ancestor that may need to be created. The
+ keywords correspond to the levels in the REST
+ hierarchy, see Interface.inspect.architecture()
+ - If an element is created with no specified type:
+ - if its name matches a naming convention, this type
+ will be used
+ - else a default type is defined in the schema module
Examples
--------
@@ -410,13 +409,14 @@ class CObject(object):
- a collection URI e.g. /REST/projects
- a list of element URIs
- a list of collections
- e.g. /REST/projects/ONE/subjects and /REST/projects/TWO/subjects
+ e.g. /REST/projects/ONE/subjects **AND**
+ /REST/projects/TWO/subjects
- a list of element objects
- a list a collection objects
Collections objects built in different ways share the same behavior:
- they behave as iterators, which enables a lazy access to
- the data
+ the data
- they always yield EObjects
- they can be nested with any other collection
@@ -735,11 +735,12 @@ def get(self, *args):
Parameters
----------
- args: ID, label, obj
- Specify to return the element ID, label or Object.
- Any combination of ID, label and obj is valid, if more
- than one is given, a list of tuple is returned instead of
- a list.
+ args: strings
+ - Specify the information to return for the elements
+ within ID, label and Object.
+ - Any combination of ID, label and obj is valid, if
+ more than one is given, a list of tuple is returned
+ instead of a list.
"""
if args == ():
return [urllib.unquote(uri_last(eobj._uri)) for eobj in self]
@@ -795,21 +796,18 @@ def where(self, constraints):
The ``where`` clause should be on the first select:
>>> for experiment in interface.select('//experiments'
).where([('atest/FIELD', '=', 'value'), 'AND']):
-
- print experiment
+ >>> print experiment
- Do NOT do this:
+ Do **NOT** do this:
>>> for experiment in interface.select('//experiments'):
for assessor in experiment.assessors(
).where([('atest/FIELD', '=', 'value'), 'AND']):
-
- print assessor
+ >>> print assessor
Or this:
>>> for project in interface.select('//projects'
).where([('atest/FIELD', '=', 'value'), 'AND']):
-
- print project
+ >>> print project
See Also
--------
@@ -922,18 +920,20 @@ def accessibility(self):
def set_accessibility(self, accessibility='protected'):
""" Sets project accessibility.
+ .. note::
+ Write access is given or not by the user level for a
+ specific project.
+
Parameters
----------
accessibility: public | protected | private
Sets the project accessibility:
- public: the project is visible and provides read
- access for anyone.
+ access for anyone.
- protected: the project is visible by anyone but the
- data is accessible for allowed users only.
+ data is accessible for allowed users only.
- private: the project is visible by allowed users only.
- Write access is given or not by the user level for a
- specic project.
"""
return self._intf._exec(join_uri(self._uri, 'accessibility',
accessibility), 'PUT')
@@ -975,7 +975,7 @@ def user_role(self, login):
Returns
-------
- owner | member | collaborator
+ string : owner | member | collaborator
"""
return JsonTable(self._intf._get_json(join_uri(self._uri, 'users'))
@@ -984,7 +984,7 @@ def user_role(self, login):
def add_user(self, login, role='member'):
""" Adds a user to the project. The user must already exist on
- the server.
+ the server.
Parameters
----------
@@ -993,10 +993,10 @@ def add_user(self, login, role='member'):
role: owner | member | collaborator
The user level for this project:
- owner: read and write access, as well as
- administrative privileges such as adding and removing
- users.
+ administrative privileges such as adding and removing
+ users.
- member: read access and can create new resources but
- not remove them.
+ not remove them.
- collaborator: read access only.
"""
self._intf._exec(join_uri(self._uri, 'users',
@@ -1355,7 +1355,7 @@ def attributes(self):
Returns
-------
- A dictionnary with the file attributes.
+ dict : a dictionnary with the file attributes
"""
return self._getcells(['URI', 'Name', 'Size',
@@ -1365,19 +1365,19 @@ def get(self, dest=None):
""" Downloads the file to the cache directory.
.. note::
- The path is computed like this:
- ``path_to_cache/urichecksum_filename``
+ The default cache path is computed like this:
+ ``path_to_cache/md5(uri + query_string)_filename``
Parameters
----------
- dest: None | string
- If None a default path in the cache folder is automatically
- computed. Else the file is downloaded at the requested
- location.
+ dest: string | None
+ - If None a default path in the cache folder is
+ automatically computed.
+ - Else the file is downloaded at the requested location.
Returns
-------
- The location of the file in the cache directory .
+ string : the file location.
"""
start = time.time()
@@ -1402,12 +1402,13 @@ def get_copy(self, dest=None):
Parameters
----------
dest: string | None
- Path for the copy. Defaults to None.
- If None a copy is created at a default location.
+ - file path for the copy
+ - if None a copy is created at a default location based
+ on the file URI on the server
Returns
-------
- The location of the copy.
+ string : the copy location.
"""
if not dest:
View
@@ -226,13 +226,16 @@ class SearchManager(object):
Examples
--------
- >>> interface.search.save(name='mysearch',
- row='xnat:subjectData',
- columns=['xnat:subjectData/PROJECT','xnat:subjectData/SUBJECT_ID'],
- constraints=[('xnat:subjectData/SUBJECT_ID', 'LIKE', '*'), 'AND'],
- sharing='public'
- )
-
+ >>> row = 'xnat:subjectData'
+ >>> columns = ['xnat:subjectData/PROJECT',
+ 'xnat:subjectData/SUBJECT_ID'
+ ]
+ >>> criteria = [('xnat:subjectData/SUBJECT_ID', 'LIKE', '*'),
+ 'AND'
+ ]
+ >>> interface.manage.search.save('mysearch', row, columns,
+ criteria, sharing='public'
+ )
"""
def __init__(self, interface):
self._intf = interface
@@ -243,8 +246,8 @@ def save(self, name, row, columns, constraints, sharing='private'):
Parameters
----------
name: string
- Name of the query displayed on the Web Interface and used
- to get back the results.
+ Name of the query displayed on the Web Interface and
+ used to get back the results.
row: string
Datatype from `Interface.inspect.datatypes()`.
Usually ``xnat:subjectData``
Oops, something went wrong.

0 comments on commit b5b145c

Please sign in to comment.