Skip to content

Commit

Permalink
Documentation update
Browse files Browse the repository at this point in the history
  • Loading branch information
Yannick Schwartz committed Feb 22, 2011
1 parent 5ff9263 commit b5b145c
Show file tree
Hide file tree
Showing 9 changed files with 98 additions and 95 deletions.
Binary file modified doc/documentation.zip
View file
Binary file not shown.
1 change: 1 addition & 0 deletions doc/index.rst
View file
Original file line number Original file line Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ pyxnat: Xnat in Python
starters_tutorial.rst starters_tutorial.rst
advanced_tutorial.rst advanced_tutorial.rst
reference_documentation.rst reference_documentation.rst
CHANGES.rst


Introduction Introduction
------------ ------------
Expand Down
31 changes: 12 additions & 19 deletions pyxnat/core/help.py
View file
Original file line number Original file line Diff line number Diff line change
Expand Up @@ -38,10 +38,10 @@ def set_autolearn(self, auto=True, tick=30):
""" Once in a while queries will persist additional """ Once in a while queries will persist additional
information on the server. This information is available information on the server. This information is available
through the following methods of this class: through the following methods of this class:
- experiment_types - experiment_types
- assessor_types - assessor_types
- scan_types - scan_types
- reconstruction_types - reconstruction_types
It is also transparently used in insert operations. It is also transparently used in insert operations.
Expand All @@ -68,14 +68,13 @@ def datatypes(self, pattern='*', fields_pattern=None):
pattern: string pattern: string
Pattern for the datatype. May include wildcards. Pattern for the datatype. May include wildcards.
fields_pattern: string fields_pattern: string
Pattern for the datafields. May include wildcards. If - Pattern for the datafields -- may include wildcards.
specified, datafields will be returned instead of - If specified, datafields will be returned instead of
datatypes. datatypes.
Returns Returns
------- -------
List of datatypes or datafields depending on the argument list : datatypes or datafields depending on the argument usage.
usage.
""" """


search_els = self._get_json('/REST/search/elements?format=json') search_els = self._get_json('/REST/search/elements?format=json')
Expand Down Expand Up @@ -112,7 +111,7 @@ def experiment_types(self):
See Also See Also
-------- --------
Inspector.set_autolean() Inspector.set_autolearn()
""" """
return self._resource_types('experiment') return self._resource_types('experiment')


Expand All @@ -122,7 +121,7 @@ def assessor_types(self):
See Also See Also
-------- --------
Inspector.set_autolean() Inspector.set_autolearn()
""" """
return self._resource_types('assessor') return self._resource_types('assessor')


Expand All @@ -132,7 +131,7 @@ def reconstruction_types(self):
See Also See Also
-------- --------
Inspector.set_autolean() Inspector.set_autolearn()
""" """
return self._resource_types('reconstruction') return self._resource_types('reconstruction')


Expand All @@ -142,7 +141,7 @@ def scan_types(self):
See Also See Also
-------- --------
Inspector.set_autolean() Inspector.set_autolearn()
""" """
return self._resource_types('scan') return self._resource_types('scan')


Expand Down Expand Up @@ -224,8 +223,6 @@ def assessor_values(self, experiment_type, project=None):
An experiment type. An experiment type.
project: string project: string
Optional. Restrict operation to a project. Optional. Restrict operation to a project.
project: string
Optional. Restrict operation to a project.
""" """
return self._sub_experiment_values('assessor', return self._sub_experiment_values('assessor',
project, experiment_type) project, experiment_type)
Expand All @@ -248,8 +245,6 @@ def scan_values(self, experiment_type, project=None):
An experiment type. An experiment type.
project: string project: string
Optional. Restrict operation to a project. Optional. Restrict operation to a project.
project: string
Optional. Restrict operation to a project.
""" """
return self._sub_experiment_values('scan', project, experiment_type) return self._sub_experiment_values('scan', project, experiment_type)


Expand All @@ -271,8 +266,6 @@ def reconstruction_values(self, experiment_type, project=None):
An experiment type. An experiment type.
project: string project: string
Optional. Restrict operation to a project. Optional. Restrict operation to a project.
project: string
Optional. Restrict operation to a project.
""" """
return self._sub_experiment_values('reconstruction', return self._sub_experiment_values('reconstruction',
project, experiment_type) project, experiment_type)
Expand Down
2 changes: 1 addition & 1 deletion pyxnat/core/interfaces.py
View file
Original file line number Original file line Diff line number Diff line change
Expand Up @@ -279,7 +279,7 @@ def save_config(self, location):
.. warning:: .. warning::
Since the password is saved as well, make sure the file 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 Parameters
---------- ----------
Expand Down
109 changes: 55 additions & 54 deletions pyxnat/core/resources.py
View file
Original file line number Original file line Diff line number Diff line change
Expand Up @@ -222,33 +222,32 @@ def create(self, **params):
Any non-existing ancestor will be created as well. Any non-existing ancestor will be created as well.
.. warning:: .. warning::
An element resource both have an ID and a label that
An element resource both have an ID and a label that can can be used to access it. At the moment, XNAT REST API
be used to access it. At the moment, XNAT REST API defines defines the label when creating an element, but not
the label when creating an element, but not the ID, which the ID, which is generated. It means that the `name`
is generated. It means that the `name` given to a resource given to a resource may not appear when listing the
may not appear when listing the resources because the IDs resources because the IDs will appear, not the labels.
will appear, not the labels.
.. note:: .. 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 creation it is possible to use shortcuts defined in the
XNAT REST documentation or xpath in the schema:: XNAT REST documentation or xpath in the schema:
element.create(ID='theid') - element.create(ID='theid')
subject.create(**{'xnat:subjectData/ID':'theid'}) - subject.create(**{'xnat:subjectData/ID':'theid'})
Parameters Parameters
---------- ----------
params: keywords params: keywords
Specify the datatype of the element resource and of any - Specify the datatype of the element resource and of
ancestor that may need to be created. The keywords any ancestor that may need to be created. The
correspond to the levels in the REST hierarchy, keywords correspond to the levels in the REST
i.e. Interface.inspect.rest_hierarchy() hierarchy, see Interface.inspect.architecture()
- If an element is created with no specified type:
If an element is created with no specified type: - if its name matches a naming convention, this type
- if its name matches a naming convention, this type will be used
will be used - else a default type is defined in the schema module
- else a default type is defined in the schema module
Examples Examples
-------- --------
Expand Down Expand Up @@ -410,13 +409,14 @@ class CObject(object):
- a collection URI e.g. /REST/projects - a collection URI e.g. /REST/projects
- a list of element URIs - a list of element URIs
- a list of collections - 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 of element objects
- a list a collection objects - a list a collection objects
Collections objects built in different ways share the same behavior: Collections objects built in different ways share the same behavior:
- they behave as iterators, which enables a lazy access to - they behave as iterators, which enables a lazy access to
the data the data
- they always yield EObjects - they always yield EObjects
- they can be nested with any other collection - they can be nested with any other collection
Expand Down Expand Up @@ -735,11 +735,12 @@ def get(self, *args):
Parameters Parameters
---------- ----------
args: ID, label, obj args: strings
Specify to return the element ID, label or Object. - Specify the information to return for the elements
Any combination of ID, label and obj is valid, if more within ID, label and Object.
than one is given, a list of tuple is returned instead of - Any combination of ID, label and obj is valid, if
a list. more than one is given, a list of tuple is returned
instead of a list.
""" """
if args == (): if args == ():
return [urllib.unquote(uri_last(eobj._uri)) for eobj in self] return [urllib.unquote(uri_last(eobj._uri)) for eobj in self]
Expand Down Expand Up @@ -795,21 +796,18 @@ def where(self, constraints):
The ``where`` clause should be on the first select: The ``where`` clause should be on the first select:
>>> for experiment in interface.select('//experiments' >>> for experiment in interface.select('//experiments'
).where([('atest/FIELD', '=', 'value'), 'AND']): ).where([('atest/FIELD', '=', 'value'), 'AND']):
>>> print experiment
print experiment
Do NOT do this: Do **NOT** do this:
>>> for experiment in interface.select('//experiments'): >>> for experiment in interface.select('//experiments'):
for assessor in experiment.assessors( for assessor in experiment.assessors(
).where([('atest/FIELD', '=', 'value'), 'AND']): ).where([('atest/FIELD', '=', 'value'), 'AND']):
>>> print assessor
print assessor
Or this: Or this:
>>> for project in interface.select('//projects' >>> for project in interface.select('//projects'
).where([('atest/FIELD', '=', 'value'), 'AND']): ).where([('atest/FIELD', '=', 'value'), 'AND']):
>>> print project
print project
See Also See Also
-------- --------
Expand Down Expand Up @@ -922,18 +920,20 @@ def accessibility(self):
def set_accessibility(self, accessibility='protected'): def set_accessibility(self, accessibility='protected'):
""" Sets project accessibility. """ Sets project accessibility.
.. note::
Write access is given or not by the user level for a
specific project.
Parameters Parameters
---------- ----------
accessibility: public | protected | private accessibility: public | protected | private
Sets the project accessibility: Sets the project accessibility:
- public: the project is visible and provides read - public: the project is visible and provides read
access for anyone. access for anyone.
- protected: the project is visible by anyone but the - 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. - 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', return self._intf._exec(join_uri(self._uri, 'accessibility',
accessibility), 'PUT') accessibility), 'PUT')
Expand Down Expand Up @@ -975,7 +975,7 @@ def user_role(self, login):
Returns Returns
------- -------
owner | member | collaborator string : owner | member | collaborator
""" """
return JsonTable(self._intf._get_json(join_uri(self._uri, 'users')) return JsonTable(self._intf._get_json(join_uri(self._uri, 'users'))
Expand All @@ -984,7 +984,7 @@ def user_role(self, login):


def add_user(self, login, role='member'): def add_user(self, login, role='member'):
""" Adds a user to the project. The user must already exist on """ Adds a user to the project. The user must already exist on
the server. the server.
Parameters Parameters
---------- ----------
Expand All @@ -993,10 +993,10 @@ def add_user(self, login, role='member'):
role: owner | member | collaborator role: owner | member | collaborator
The user level for this project: The user level for this project:
- owner: read and write access, as well as - owner: read and write access, as well as
administrative privileges such as adding and removing administrative privileges such as adding and removing
users. users.
- member: read access and can create new resources but - member: read access and can create new resources but
not remove them. not remove them.
- collaborator: read access only. - collaborator: read access only.
""" """
self._intf._exec(join_uri(self._uri, 'users', self._intf._exec(join_uri(self._uri, 'users',
Expand Down Expand Up @@ -1355,7 +1355,7 @@ def attributes(self):
Returns Returns
------- -------
A dictionnary with the file attributes. dict : a dictionnary with the file attributes
""" """


return self._getcells(['URI', 'Name', 'Size', return self._getcells(['URI', 'Name', 'Size',
Expand All @@ -1365,19 +1365,19 @@ def get(self, dest=None):
""" Downloads the file to the cache directory. """ Downloads the file to the cache directory.
.. note:: .. note::
The path is computed like this: The default cache path is computed like this:
``path_to_cache/urichecksum_filename`` ``path_to_cache/md5(uri + query_string)_filename``
Parameters Parameters
---------- ----------
dest: None | string dest: string | None
If None a default path in the cache folder is automatically - If None a default path in the cache folder is
computed. Else the file is downloaded at the requested automatically computed.
location. - Else the file is downloaded at the requested location.
Returns Returns
------- -------
The location of the file in the cache directory . string : the file location.
""" """


start = time.time() start = time.time()
Expand All @@ -1402,12 +1402,13 @@ def get_copy(self, dest=None):
Parameters Parameters
---------- ----------
dest: string | None dest: string | None
Path for the copy. Defaults to None. - file path for the copy
If None a copy is created at a default location. - if None a copy is created at a default location based
on the file URI on the server
Returns Returns
------- -------
The location of the copy. string : the copy location.
""" """


if not dest: if not dest:
Expand Down
21 changes: 12 additions & 9 deletions pyxnat/core/search.py
View file
Original file line number Original file line Diff line number Diff line change
Expand Up @@ -226,13 +226,16 @@ class SearchManager(object):
Examples Examples
-------- --------
>>> interface.search.save(name='mysearch', >>> row = 'xnat:subjectData'
row='xnat:subjectData', >>> columns = ['xnat:subjectData/PROJECT',
columns=['xnat:subjectData/PROJECT','xnat:subjectData/SUBJECT_ID'], 'xnat:subjectData/SUBJECT_ID'
constraints=[('xnat:subjectData/SUBJECT_ID', 'LIKE', '*'), 'AND'], ]
sharing='public' >>> criteria = [('xnat:subjectData/SUBJECT_ID', 'LIKE', '*'),
) 'AND'
]
>>> interface.manage.search.save('mysearch', row, columns,
criteria, sharing='public'
)
""" """
def __init__(self, interface): def __init__(self, interface):
self._intf = interface self._intf = interface
Expand All @@ -243,8 +246,8 @@ def save(self, name, row, columns, constraints, sharing='private'):
Parameters Parameters
---------- ----------
name: string name: string
Name of the query displayed on the Web Interface and used Name of the query displayed on the Web Interface and
to get back the results. used to get back the results.
row: string row: string
Datatype from `Interface.inspect.datatypes()`. Datatype from `Interface.inspect.datatypes()`.
Usually ``xnat:subjectData`` Usually ``xnat:subjectData``
Expand Down
Loading

0 comments on commit b5b145c

Please sign in to comment.