add list_services method

CHANGES.rst

@@ -1,6 +1,9 @@
 1.5 (unreleased)
 ================
 
+- Add method ``list_services`` to ``pyvo.registry.regtap.RegistryResource`` that returns the
+  list of available services [#505]
+
 - Add optional ``description`` parameter and a ``__repr__`` to ``pyvo.dal.query.DALService``
   abstract base class [#505]
 

docs/registry/index.rst

@@ -190,14 +190,35 @@ thus say:
 
 .. doctest-remote-data::
 
-  >>> resources["II/283"].get_service("conesearch").search(pos=(120, 73), sr=1)
+  >>> voresource = resources["II/283"]
+  >>> voresource.get_service("conesearch").search(pos=(120, 73), sr=1)
   <DALResultsTable length=1>
     _RAJ2000     _DEJ2000      _r    recno ... NED    RAJ2000      DEJ2000
       deg          deg                     ...
     float64      float64    float64  int32 ... str3    str12        str12
   ------------ ------------ -------- ----- ... ---- ------------ ------------
   117.98645833  73.00961111 0.588592   986 ...  NED 07 51 56.750 +73 00 34.60
 
+This method will raise an error if there is more than one service of the desired
+type. If you know for sure that all declared conesearch will be the same, you can
+safely use ``get_service('conesearch', lax=True)`` that will return the first
+conesearch it finds. If you need to be sure, all the available standard services
+can be inspected with `~pyvo.registry.RegistryResource.list_services`.
+
+.. doctest-remote-data::
+
+  >>> for service in voresource.list_services():
+  ...     print(service)
+  SCSService(baseurl:'http://vizier.cds.unistra.fr/viz-bin/conesearch/II/283/sncat?', description:'Cone search capability for table II/283/sncat (List of SNe arranged in chronological order)')
+  TAPService(baseurl:'http://tapvizier.cds.unistra.fr/TAPVizieR/tap', description:'None')
+
+Or to get the list of services corresponding to a specific service type:
+
+.. doctest-remote-data::
+
+  >>> voresource.list_services("tap")
+  [TAPService(baseurl:'http://tapvizier.cds.unistra.fr/TAPVizieR/tap', description:'None')]
+
 To operate TAP services, you need to know what tables make up a
 resource; you could construct a TAP service and access its ``tables``
 attribute, but you can take a shortcut and call a RegistryResource's

pyvo/registry/regtap.py

@@ -316,6 +316,9 @@ class _BrowserService:
     def __init__(self, access_url):
         self.access_url = access_url
 
+    def __repr__(self):
+        return str(self.access_url)
+
     def search(self):
         import webbrowser
         webbrowser.open(self.access_url, 2)
@@ -345,17 +348,18 @@ class Interface:
         "ivo://ivoa.net/std/sla": sla.SLAService,
         "ivo://ivoa.net/std/tap": tap.TAPService}
 
-    def __init__(self, access_url, standard_id, intf_type, intf_role):
+    def __init__(self, access_url, standard_id, intf_type, intf_role, description):
         self.access_url = access_url
         self.standard_id = standard_id or None
         self.is_vosi = standard_id.startswith("ivo://ivoa.net/std/vosi")
         self.type = intf_type or None
         self.role = intf_role or None
+        self.description = description or None
         self.is_standard = self.role == "std"
 
     def __repr__(self):
         return (f"Interface({self.access_url!r}, {self.standard_id!r},"
-                f" {self.type!r}, {self.role!r})")
+                f" {self.type!r}, {self.role!r}, {self.description!r})")
 
     def to_service(self):
         if self.type == "vr:webbrowser":
@@ -372,9 +376,9 @@ def to_service(self):
                              f" standard id {self.standard_id}.")
 
         if service_class == sia2.SIA2Service:
-            return service_class(self.access_url, check_baseurl=False)
+            return service_class(self.access_url, description=self.description, check_baseurl=False)
         else:
-            return service_class(self.access_url)
+            return service_class(self.access_url, description=self.description)
 
     def supports(self, standard_id):
         """returns true if we believe the interface should be able to talk
@@ -445,6 +449,8 @@ class RegistryResource(dalq.Record):
             "intf_types"),
         (f"\n  ivo_string_agg(COALESCE(intf_role, ''), '{TOKEN_SEP}')",
             "intf_roles"),
+        (f"\n  ivo_string_agg(COALESCE(cap_description, ''), '{TOKEN_SEP}')",
+            "cap_descriptions"),
         "alt_identifier"]
 
     def __init__(self, results, index, session=None):
@@ -459,13 +465,16 @@ def __init__(self, results, index, session=None):
                       ] = self._parse_pseudo_array(self._mapping["intf_types"])
         self._mapping["intf_roles"
                       ] = self._parse_pseudo_array(self._mapping["intf_roles"])
+        self._mapping["cap_descriptions"
+                      ] = self._parse_pseudo_array(self._mapping["cap_descriptions"])
 
         self.interfaces = [Interface(*props)
                            for props in itertools.zip_longest(
             self["access_urls"],
             self["standard_ids"],
             self["intf_types"],
-            self["intf_roles"])]
+            self["intf_roles"],
+            self["cap_descriptions"])]
 
     @staticmethod
     def _parse_pseudo_array(literal):
@@ -779,6 +788,30 @@ def service(self):
         self._service = self.get_service(None, True)
         return self._service
 
+    def list_services(self, service_type=None):
+        """List the services available for this registry record.
+
+        Parameters
+        ----------
+        service_type : str, optional
+            Restricts the list to services corresponding to this service type.
+            The list of possible values can be printed with
+            ``pyvo.registry.rtcons.SERVICE_TYPE_MAP.keys()``.
+
+        Returns
+        -------
+        list
+            A list of service objects. They can be
+            `~pyvo.dal.scs.SCSService`, `~pyvo.dal.sia.SIAService`,
+            `~pyvo.dal.sia2.SIA2Service`, `~pyvo.dal.ssa.SSAService`,
+            `~pyvo.dal.sla.SLAService`, or `~pyvo.dal.tap.TAPService`.
+        """
+        if service_type is not None:
+            service_type = expand_stdid(rtcons.SERVICE_TYPE_MAP.get(service_type, service_type))
+        return [interface.to_service() for interface in self.interfaces
+                if (interface.is_standard
+                    and (service_type is None) or interface.supports(service_type))]
+
     def search(self, *args, **keys):
         """
         assuming this resource refers to a searchable service, execute a