Merge pull request #38 from pyvirtobs/master

merge latest from master (python3, users manual) for beta2

.travis.yml

@@ -0,0 +1,52 @@
+language: python
+
+python:
+    - 2.6
+    - 2.7
+    - 3.2
+    - 3.3
+
+env:
+    # try all python versions with the latest stable numpy and astropy
+    - ASTROPY_VERSION=stable NUMPY_VERSION=1.7.1 SETUP_CMD='test'
+
+matrix:
+    include:
+        #- python: 2.7
+        #  # opdeps needed because the matplotlib sphinx extension requires them
+        #  env: ASTROPY_VERSION=development NUMPY_VERSION=1.7.1 SETUP_CMD='build_sphinx -w -n'
+
+        ## try alternate numpy versions with the latest stable astropy
+        #- python: 2.7
+        #  env: ASTROPY_VERSION=stable NUMPY_VERSION=1.6.2 SETUP_CMD='test'
+        #- python: 2.7
+        #  env: ASTROPY_VERSION=stable NUMPY_VERSION=1.5.1 SETUP_CMD='test'
+        #- python: 3.2
+        #  env: ASTROPY_VERSION=stable NUMPY_VERSION=1.6.2 SETUP_CMD='test'
+        # numpy < 1.6 does not work on py 3.x
+
+        # try latest developer version of astropy
+        - python: 2.7
+          env: ASTROPY_VERSION=development NUMPY_VERSION=1.7.1 SETUP_CMD='test'
+        #- python: 3.3
+        #  env: ASTROPY_VERSION=development NUMPY_VERSION=1.7.1 SETUP_CMD='test'
+
+before_install:
+   # We do this to make sure we get the dependencies so pip works below
+   - sudo apt-get update -qq
+   - sudo apt-get install -qq python-numpy python-sphinx cython libatlas-dev liblapack-dev gfortran
+   - if [[ $SETUP_CMD == build_sphinx* ]]; then sudo apt-get install -qq python-sphinx graphviz texlive-latex-extra dvipng python-matplotlib; fi
+
+install:
+   - export PYTHONIOENCODING=UTF8 # just in case
+   - pip -q install --upgrade "numpy==$NUMPY_VERSION" --use-mirrors
+   - pip -q install --upgrade Cython --use-mirrors
+   - if [[ $SETUP_CMD == build_sphinx* ]]; then pip -q install sphinx==1.1.3 --use-mirrors; fi
+   - if [[ $SETUP_CMD == build_sphinx* ]]; then pip -q install matplotlib --use-mirrors; fi
+
+   - if [[ $ASTROPY_VERSION == stable ]]; then pip -q install astropy --use-mirrors; fi
+   - if [[ $ASTROPY_VERSION == development ]]; then pip -q install git+http://github.com/astropy/astropy.git#egg=astropy --use-mirrors; fi
+
+script:
+   - python setup.py test
+

docs/conf.py

@@ -38,6 +38,11 @@
 # directories to ignore when looking for source files.
 exclude_patterns.append('_templates')
 
+# Add any paths that contain templates here, relative to this directory.
+if 'templates_path' not in locals():  # in case parent conf.py defines it
+    templates_path = []
+templates_path.append('_templates')
+
 # This is added to the end of RST files - a good place to put substitutions to
 # be used globally.
 rst_epilog += """

docs/pyvo/dal.rst

@@ -1,7 +1,9 @@
 
-*******************
-The pyvo.dal Module
-*******************
+.. py:module:: pyvo.dal
+
+********************
+The pyvo.dal Package
+********************
 
 The ``pyvo.dal`` module encapsulates the implementation of the DAL
 services.  The :py:mod:`~pyvo.dal.query` sub-module provides DAL
@@ -10,17 +12,11 @@ The implementations for the specific types of services are handle the
 sub-modules :py:mod:`~pyvo.dal.scs`, :py:mod:`~pyvo.dal.sia`, 
 :py:mod:`~pyvo.dal.ssa`, :py:mod:`~pyvo.dal.sla`
 
-
-
-**Contents**
-
-.. toctree::
-  :maxdepth: 1
-
-  query
-  scs
-  sia
-  ssa
-  sla
+.. automodapi:: pyvo.dal.query
+.. include:: scs.rst
+.. include:: sia.rst
+.. include:: ssa.rst
+.. include:: sla.rst
 
 
+

docs/pyvo/getting_started.rst

@@ -175,7 +175,7 @@ You might notice:
 25. We can download each image to a directory via the
     ``cachedataset()`` function.  
 
-.. _getting-started-pyvo
+.. _getting-started-pyvo:
 
 ===================================
 What's available in the pyvo Module
@@ -203,13 +203,19 @@ functions.  Four of the functions represent what's referred to as the
 * :py:func:`~pyvo.linesearch` -- search a remote spectral line database
   for data about emission lines.  
 
+We'll show you how to use these in the next chapter,
+:ref:`data-access`.  
+
 All the DAL search functions require a URL that represents the
 location of the service as its first argument.  If you don't the URL,
 you can look it up through a search of the VO Registry:
 
 * :py:func:`~pyvo.regsearch` -- search the VO Registry to find
   services and archives.  
 
+The Registry is discussed more in a subsequent chapter,
+:ref:`registry-access`. 
+
 The module also has functions that look up information about named
 objects in the sky, their positions being the most important.  There
 are three functions available:
@@ -223,27 +229,35 @@ are three functions available:
 * :py:func:`~pyvo.nameresolver.sesame.resolve` -- returns a container
   full of data about a source with a gien name.  
 
-Finally, the :py:mod:`pyvo` module makes available a set of exceptions
+For more information on name resolution, consult the chapter,
+:ref:`resolve-names`.  
+
+The :py:mod:`pyvo` module also makes available a set of exceptions
 that are thrown by the above functions when things go wrong.  These
-are described in the Data Access Queries section: 
+are described in the :ref:`data-access` chapter under the section,
+:ref:`data-access-exceptions`: 
 
-============================================  ==================================
+============================================  ===================================================================================
 :py:class:`~pyvo.dal.query.DALAccessError`    a base class for all failures while accessing a DAL service
 :py:class:`~pyvo.dal.query.DALProtocolError`  a base exception indicating that a DAL service responded in an erroneous way.  
 :py:class:`~pyvo.dal.query.DALFormatError`    an exception indicating that a DAL response contains fatal format errors.
 :py:class:`~pyvo.dal.query.DALServiceError`   an exception indicating a failure communicating with a DAL service.
 :py:class:`~pyvo.dal.query.DALQueryError`     an exception indicating an error by a working DAL service while processing a query.  
-============================================  ==================================
+============================================  ===================================================================================
+
+.. raw:: html
+
+   <br>
 
 Finally, we will see in the next chapter that additional features are
 available in sub-modules, each associated with a different type of
 services.  This includes:
 
-================================  =========================================
-:py:mod:`~pyvo.dal.sia`           Classes for accessing image services
-:py:mod:`~pyvo.dal.ssa`           Classes for accessing spectrum services
-:py:mod:`~pyvo.dal.scs`           Classes for accessing catalog services
-:py:mod:`~pyvo.dal.sla`           Classes for accessing spectral line catalog services
-:py:mod:`~pyvo.dal.registry`      Classes for accessing the registry
-:py:mod:`~pyvo.dal.nameresolver`  Classes for accessing the nameresolver servicees
-================================  =========================================
+===========================  ====================================================
+:py:mod:`pyvo.dal.sia`       Classes for accessing image services
+:py:mod:`pyvo.dal.ssa`       Classes for accessing spectrum services
+:py:mod:`pyvo.dal.scs`       Classes for accessing catalog services
+:py:mod:`pyvo.dal.sla`       Classes for accessing spectral line catalog services
+:py:mod:`pyvo.registry`      Classes for accessing the registry
+:py:mod:`pyvo.nameresolver`  Classes for accessing the nameresolver servicees
+===========================  ====================================================

docs/pyvo/mod.rst

@@ -1,7 +1,7 @@
 
-===============
-The pyvo Module
-===============
+================
+The pyvo Package
+================
 
 .. py:module:: pyvo
 

docs/pyvo/nameresolver.rst

@@ -1,7 +1,28 @@
 
-=================================
-The pyvo.namesolver.sesame Module
-=================================
+.. py:module:: pyvo.nameresolver
+
+==================================
+The pyvo.namesolver Package
+==================================
+
+.. note:: the Astropy package provides object-to-position resolution
+          (see :ref:`resolve-names` for an example),
+          so future versions of PyVO will migrate to use the Astropy
+          implementation.  Thus, *the* :py:mod:`pyvo.nameresolver`
+          *module will be deprecated*.  
+
+          Direct support for Astropy coordinate types by the data
+          access services is also planned for future versions of
+          PyVO.  
+
+          The support for the CDS Sesame Service within the 
+          :py:mod:`pyvo.nameresolver.sesame` will be evolved
+          appropriately for accessing other source information
+          available from the service.  
+
+The current default implementation available in the
+**pyvo.nameresolver** module is that provided by the
+:py:mod:`~pyvo.nameresolver.sesame` sub-module.  
 
 .. automodapi:: pyvo.nameresolver.sesame
 

docs/pyvo/pyvo.dal.scs.SCSQuery.rst

@@ -0,0 +1,98 @@
+
+
+SCSQuery
+=====================
+
+.. currentmodule:: pyvo.dal.scs
+
+.. autoclass:: SCSQuery
+   :show-inheritance:
+
+   .. rubric:: Attributes Summary
+
+   Search Constraint Attributes:
+
+   .. autosummary::
+
+      ~SCSQuery.dec
+      ~SCSQuery.pos
+      ~SCSQuery.ra
+      ~SCSQuery.radius
+      ~SCSQuery.sr
+      ~SCSQuery.verbosity
+
+   Other Attributes:
+
+   ====================================================  ==========================================================
+   :py:attr:`~pyvo.dal.query.DALQuery.baseurl`           the base URL of the service where the query will be 
+                                                         submitted
+   ----------------------------------------------------  ----------------------------------------------------------
+   :py:attr:`~pyvo.dal.scs.SCSQuery.std_parameters`      the list of predefined parameters supported by the SCS 
+                                                         standard (read-only)
+   ----------------------------------------------------  ----------------------------------------------------------
+   :py:attr:`~pyvo.dal.query.DALQuery.protocol`          the type of protocol supported by this query instance
+                                                         (read-only; set to 'scs').  
+   ----------------------------------------------------  ----------------------------------------------------------
+   :py:attr:`~pyvo.dal.query.DALQuery.version`           the version of the protocol standard supported by this 
+                                                         query instance (read-only)
+   ====================================================  ==========================================================
+
+   .. rubric:: Methods Summary
+
+   .. autosummary::
+
+      ~SCSQuery.execute
+      ~SCSQuery.execute_votable
+      ~SCSQuery.getqueryurl
+
+   .. rubric:: Methods Inherited from DALQuery
+
+   .. autosummary::
+
+      ~pyvo.dal.query.DALQuery.execute_stream
+      ~pyvo.dal.query.DALQuery.execute_raw
+      ~pyvo.dal.query.DALQuery.getqueryurl
+      ~pyvo.dal.query.DALQuery.getparam
+      ~pyvo.dal.query.DALQuery.paramnames
+      ~pyvo.dal.query.DALQuery.setparam
+      ~pyvo.dal.query.DALQuery.unsetparam
+
+   .. rubric:: Attributes Documentation
+
+   .. autoattribute:: dec
+   .. autoattribute:: pos
+   .. autoattribute:: ra
+   .. autoattribute:: radius
+   .. autoattribute:: sr
+   .. autoattribute:: verbosity
+   .. py:attribute:: std_parameters
+
+      the list of predefined parameters supported by the Cone Search 
+      (SCS) standard (read-only).   These names can be used to set 
+      constraints generically via the 
+      :py:meth:`~pyvo.dal.query.DALQuery.setparam` 
+      method.  
+
+      This is set to the following names with the given types and meanings:
+
+      ==============  ==================  ========================================
+      Parameter Name  Value Type          Meaning
+      ==============  ==================  ========================================
+      RA              float               Same as :py:attr:`ra`
+      --------------  ------------------  ----------------------------------------
+      DEC             float               Same as :py:attr:`dec`
+      --------------  ------------------  ----------------------------------------
+      SR              float               Same as :py:attr:`radius`
+      ==============  ==================  ========================================
+
+   .. rubric:: Methods Documentation
+
+   .. note:: See also the parent class, :py:class:`~pyvo.dal.query.DALQuery`, for
+             descriptions of the inherited methods.  
+
+   .. automethod:: execute
+   .. automethod:: execute_votable
+   .. automethod:: getqueryurl
+
+
+

docs/pyvo/pyvo.dal.scs.SCSRecord.rst

@@ -0,0 +1,48 @@
+
+
+SCSRecord
+======================
+
+.. currentmodule:: pyvo.dal.scs
+
+.. autoclass:: SCSRecord
+   :show-inheritance:
+
+   .. rubric:: Attributes Summary
+
+   .. autosummary::
+
+      ~SCSRecord.dec
+      ~SCSRecord.id
+      ~SCSRecord.ra
+
+   .. rubric:: Methods Summary
+
+   .. autosummary::
+
+      ~pyvo.dal.query.Record.fielddesc
+      ~pyvo.dal.query.Record.get
+
+   In addition, ``SCSRecord`` supports the usual functions associated
+   with dictionaries:  ``get(key[, default])``, ``has_key(key)``,
+   ``items()``, ``iteritems()``, ``iterkeys()``, ``itervalues()``,
+   ``keys()``, ``values()``. 
+
+   .. rubric:: Attributes Documentation
+
+   .. autoattribute:: dec
+   .. autoattribute:: id
+   .. autoattribute:: ra
+
+   .. rubric:: Methods Documentation
+
+   .. note:: See the parent class, :py:class:`~pyvo.dal.query.Record`, for
+             descriptions of the inherited methods.  
+
+
+
+
+
+
+
+