Merge pull request #492 from cds-astro/update-describe

Add source_value to the describe function in regtap

CHANGES.rst

@@ -1,6 +1,12 @@
 1.5 (unreleased)
 ================
 
+- Added ``alt_identifier``, ``created``, ``updated`` and ``rights`` to the
+  attributes of ``pyvo.registry.regtap.RegistryResource`` [#492]
+
+- Added the ``source_value`` and ``alt_identifier`` information to the verbose
+  output of ``describe()`` in ``regtap``. [#492]
+
 - Added convenience method DALResults.to_qtable() that returns an
   astropy.table.QTable object. [#384]
 

docs/dal/index.rst

@@ -4,7 +4,7 @@
 Data Access (`pyvo.dal`)
 ************************
 
-This subpackage provides access to the various data servies in the VO.
+This subpackage provides access to the various data services in the VO.
 
 Getting started
 ===============
@@ -47,10 +47,10 @@ See :ref:`pyvo-services` for a explanation of the different interfaces.
 
 .. _pyvo-astro-params:
 
-Astrometrical parameters
-------------------------
+Astrometric parameters
+----------------------
 
-Most services expose the astrometrical parameters ``pos`` and ``size`` for which
+Most services expose the astrometric parameters ``pos`` and ``size`` for which
 PyVO accept `~astropy.coordinates.SkyCoord` or `~astropy.units.Quantity`
 objects as well as any other sequence containing right ascension and declination
 in degrees, which are converted to the standard coordinate frame
@@ -72,7 +72,7 @@ astronomical objects you are searching for.
 See :ref:`astropy-coordinates` and :ref:`astropy-units` for details.
 
 The `~astropy.units.Quantity` object is also suitable for any other
-astrometrical parameter, such as waveband ranges.
+astrometric parameter, such as waveband ranges.
 
 Some services also accept `~astropy.time.Time` as ``time`` parameter.
 
@@ -103,7 +103,7 @@ Capabilities describe specific pieces of functionality (such as “this is a
 spectral search”) and further metadata (such as ”this service will never
 return more than 10000 rows”).
 
-This information is contained in the datastructure
+This information is contained in the data structure
 :py:class:`~pyvo.io.vosi.endpoint.CapabilitiesFile` available through
 :py:attr:`~pyvo.dal.mixin.CapabilityMixin.capabilities`.
 
@@ -117,7 +117,7 @@ Services
 ========
 
 There are five types of services with different purposes but a mostly
-similiar interface available.
+similar interface available.
 
 .. _pyvo_tap:
 
@@ -234,7 +234,7 @@ entire runtime of the query, and query processing generally starts
 when the request is submitted.  This is convenient but becomes
 brittle as queries have runtimes of the order of minutes, when you
 may encounter query timeouts.  Also, many data providers impose
-rather strict limits on the runtime alotted to sync queries.
+rather strict limits on the runtime allotted to sync queries.
 
 In asynchronous (“async”) mode, on the other hand, the client just
 submits a query and receives a URL that let us inspect the
@@ -592,7 +592,7 @@ These have a ``submit_job`` method, which has the same
 parameters as their ``search`` but start a server-side job instead of waiting
 for the result to return.
 
-This is particulary useful for longer-running queries or when you want
+This is particularly useful for longer-running queries or when you want
 to run several queries in parallel from one script.
 
 .. note::
@@ -747,7 +747,7 @@ If the row contains datasets, they are exposed by several retrieval methods:
     >>> fileobj = row.getdataset()
     >>> obj = row.getdataobj()
 
-Returning the access url, the file-like object or the appropiate python object
+Returning the access url, the file-like object or the appropriate python object
 to further work on.
 
 As with general numpy arrays, accessing individual columns via names gives an
@@ -845,7 +845,7 @@ can pass as keywords to the ``process`` method.
 For more details about this have a look at
 :py:class:`astropy.io.votable.tree.Param`.
 
-Calling the method will return a file-like object on sucess.
+Calling the method will return a file-like object on success.
 
 .. remove skip once https://github.com/astropy/pyvo/issues/361 is fixed
 .. doctest-skip::
@@ -858,15 +858,15 @@ SODA
 ^^^^
 SODA is a service with predefined parameters, available on row-level through
 :py:meth:`pyvo.dal.adhoc.SodaRecordMixin.processed` which exposes a set of
-parameters who are dependend on the type of service.
+parameters which are dependent on the type of service.
 
 - ``circle`` -- a sequence (degrees) or :py:class:`astropy.units.Quantity` of
   longitude, latitude and radius
 - ``range`` -- a sequence (degrees) or :py:class:`astropy.units.Quantity` of
   two longitude values and two latitude values describing a rectangle.
 - ``polygon`` -- multiple pairs of longitude and latitude points
 - ``band`` -- a sequence of two values (meters) or
-  :py:class:`astropy.units.Quantity` with two bandwitdh values. The right sort
+  :py:class:`astropy.units.Quantity` with two bandwidth values. The right sort
   order will be ensured if converting from frequency to wavelength.
 
 
@@ -880,7 +880,7 @@ resultset or a single product (image, spectrum) by calling this method on the
 SIA or SSA record.
 
 .. note::
-  Don't forget to start the application and make sure there is a runnung SAMP
+  Don't forget to start the application and make sure there is a running SAMP
   Hub.
 
 Underlying data structures

docs/index.rst

@@ -85,7 +85,7 @@ specific to the service type. In this example, a database query is enough:
                image                     ... ppakm31.maps
 
 What is returned by the search method is a to get a resultset object, which
-esseintially works like a numpy record array.  It can be processed either by
+essentially works like a numpy record array.  It can be processed either by
 columns:
 
 .. doctest-remote-data::

docs/registry/index.rst

@@ -39,7 +39,7 @@ the examples below assume::
   >>> from pyvo import registry
 
 This function accepts one or more search constraints, which can be
-either specificed using constraint objects as positional arguments or as
+either specified using constraint objects as positional arguments or as
 keyword arguments.  The following constraints are available:
 
 * :py:class:`pyvo.registry.Freetext` (``keywords``): one or more
@@ -212,7 +212,7 @@ A special sort of access mode is ``web``, which represents some facility related
 to the resource that works in a web browser.  You can ask for a
 “service” for it, too; you will then receive an object that has a
 ``search`` method, and when you call it, a browser window should open
-with the query facility (this uses python's webbrowser module):
+with the query facility (this uses python's ``webbrowser`` module):
 
 .. doctest-skip::
 
@@ -229,10 +229,10 @@ or at services like DataScope_ or WIRR_ in your web browser.
 Service Discovery
 =================
 
-Service discovery is what you want typcially in connection with a search
+Service discovery is what you want typically in connection with a search
 for datasets, as in “Give me all infrared spectra of Bellatrix“.  To do
 that, you want to run the same DAL query against all the services of a
-given sort.  This means that you will have to include a servicetype
+given sort.  This means that you will have to include a ``servicetype``
 constraint such that all resources in your registry results can be
 queried in the same way.
 
@@ -253,9 +253,9 @@ In reality, you will have to add some error handling to this kind of
 all-VO queries: in a wide and distributed network, some service is
 always down.  See `Appendix: Robust All-VO Queries`_
 
-The central point is: With a servicetype constraint, each result has
-a well-defined ``service`` attribute that contains some subclass of
-dal.Service and that can be queried in a uniform fashion.
+The central point is: With a ``servicetype`` constraint,
+each result has a well-defined ``service`` attribute that contains some
+subclass of dal.Service and that can be queried in a uniform fashion.
 
 TAP services may provide tables in well-defined data models, like
 EPN-TAP or obscore.  These can be queried in similar loops, although
@@ -320,7 +320,7 @@ and access URL:
   Chandra Source Catalog Release 1 http://cda.cfa.harvard.edu/csc1siap/queryImages?
   ...
 
-It is not neccessary to keep track of the URL because you can search
+It is not necessary to keep track of the URL because you can search
 images directly from the registry record, for example using the Chandra
 X-ray Observatory (CDA) service and the ``search`` method, inserting
 the position and size for the desired object.
@@ -382,19 +382,24 @@ reviewing the titles is sufficient. Other times, particularly when
 you are not sure what you are looking for, it helps to look deeper.
 
 A selection of the resource metadata, including the title, shortname and
-desription, can be printed out in a summary form with
+description, can be printed out in a summary form with
 the ``describe`` function.
 
 .. doctest-remote-data::
 
-  >>> nvss.describe()
+  >>> nvss.describe(verbose=True)
   NRA) VLA Sky Survey
   Short Name: NVSS
   IVOA Identifier: ivo://nasa.heasarc/skyview/nvss
   Access modes: sia
   Base URL: https://skyview.gsfc.nasa.gov/cgi-bin/vo/sia.pl?survey=nvss&
   ...
 
+The verbose option in ``describe`` will output more information about
+the content of the resource, if available. Possible added entries are
+the authors of the resource, an associated DOI, an url where more
+information is provided, or a reference to a related paper.
+
 The method ``service`` will, for resources that only have a single
 capability, return a DAL service object ready for querying using the
 respective protocol.  You should only use that attribute when the

pyvo/registry/regtap.py

@@ -426,6 +426,9 @@ class RegistryResource(dalq.Record):
         "res_description",
         "reference_url",
         "creator_seq",
+        "created",
+        "updated",
+        "rights",
         "content_type",
         "source_format",
         "source_value",
@@ -438,7 +441,8 @@ class RegistryResource(dalq.Record):
         (f"\n  ivo_string_agg(COALESCE(intf_type, ''), '{TOKEN_SEP}')",
             "intf_types"),
         (f"\n  ivo_string_agg(COALESCE(intf_role, ''), '{TOKEN_SEP}')",
-            "intf_roles"), ]
+            "intf_roles"),
+        "alt_identifier"]
 
     def __init__(self, results, index, session=None):
         dalq.Record.__init__(self, results, index, session)
@@ -534,6 +538,14 @@ def reference_url(self):
         """
         return self.get("reference_url", decode=True)
 
+    @property
+    def alt_identifier(self):
+        """Alternative identifier.
+
+        It is often used to provide the resource associated DOI.
+        """
+        return self.get("alt_identifier", decode=True)
+
     @property
     def creators(self):
         """
@@ -542,6 +554,25 @@ def creators(self):
         """
         return self.get("creator_seq", default="", decode=True).split(";")
 
+    @property
+    def created(self):
+        """Date of creation of the resource."""
+        return self.get("created", decode=True)
+
+    @property
+    def updated(self):
+        """Date of last modification of the resource."""
+        return self.get("updated", decode=True)
+
+    @property
+    def rights(self):
+        """A statement of usage conditions for the content of the resource.
+
+        This information is often incomplete in the registry, you
+        might get more information at the ``reference_url``.
+        """
+        return self.get("rights", decode=True)
+
     @property
     def content_types(self):
         """
@@ -789,8 +820,10 @@ def describe(self, verbose=False, width=78, file=None):
         ----------
         verbose : bool
             If false (default), only user-oriented information is
-            printed; if true, additional information will be printed
-            as well.
+            printed.
+            If true, additional information -- reference url,
+            reference to the related article, and alternative identifier
+            (often a DOI) -- will be printed if available.
         width : int
             Format the description with given character-width.
         out : writable file-like object
@@ -806,24 +839,35 @@ def describe(self, verbose=False, width=78, file=None):
         if len(self._mapping["access_urls"]) == 1:
             print("Base URL: " + self.access_url, file=file)
         else:
-            print("Multi-capabilty service -- use get_service()", file=file)
+            print("Multi-capability service -- use get_service()", file=file)
 
         if self.res_description:
             print(file=file)
             print(para_format_desc(self.res_description), file=file)
             print(file=file)
 
-        if self.short_name:
-            print(
-                para_format_desc("Subjects: {}".format(self.short_name)),
-                file=file)
         if self.waveband:
             val = (str(v) for v in self.waveband)
             print(
                 para_format_desc("Waveband Coverage: " + ", ".join(val)),
                 file=file)
 
         if verbose:
+            if self.source_value:
+                print(f"\nSource: {self.source_value}", file=file)
+            if self.creators:
+                # if any creator has a name longer than 70 characters, we
+                # truncate it.
+                creators = [f"{creator[:70]}..." if len(creator) > 70
+                            else creator for creator in self.creators]
+                nmax_authors = 5
+                if len(creators) <= nmax_authors:
+                    print(f"Authors: {', '.join(creators)}", file=file)
+                else:
+                    print(f"Authors: {', '.join(creators[:nmax_authors])} et al.\n"
+                    "See creators attribute for the complete list of authors.", file=file)
+            if self.alt_identifier:
+                print(f"Alternative identifier: {self.alt_identifier}", file=file)
             if self.reference_url:
                 print("More info: " + self.reference_url, file=file)
 

pyvo/registry/rtcons.py

@@ -790,7 +790,8 @@ def build_regtap_query(constraints):
         serialized.append("(" + constraint.get_search_condition() + ")")
         extra_tables |= set(constraint._extra_tables)
 
-    joined_tables = ["rr.resource", "rr.capability", "rr.interface"
+    joined_tables = ["rr.resource", "rr.capability", "rr.interface",
+                     "rr.alt_identifier"
                      ] + list(extra_tables)
 
     # see comment in regtap.RegistryResource for the following