# Licensed under a 3-clause BSD style license - see LICENSE.rst
"""
This file contains xml element classes as defined in the VOResource standard.
There are different ways of handling the various xml tags.
* Elements with complex content
* Elements with simple content and attributes
* Elements with simple content without attributes
Elements with complex content are parsed with objects inherited from `~pyvo.utils.xml.elements.Element`.
Elements with simple content are parsed with objects inherited from `~pyvo.utils.xml.elements.Element`
defining a ``value`` property.
"""
from astropy.utils.collections import HomogeneousList
from astropy.utils.misc import indent
from ...utils.xml.elements import (
Element, ElementWithXSIType, ContentMixin, xmlattribute, xmlelement)
from .exceptions import W06
__all__ = [
"ValidationLevel", "Capability", "Interface", "AccessURL",
"SecurityMethod", "WebBrowser", "WebService", "MirrorURL"]
######################################################################
# ELEMENT CLASSES
[docs]class ValidationLevel(ContentMixin, Element):
"""
ValidationLevel element as described in
http://www.ivoa.net/xml/VOResource/v1.0
the allowed values for describing the resource descriptions and interfaces.
See the RM (v1.1, section 4) for more guidance on the use of these values.
Possible values:
0:
The resource has a description that is stored in a
registry. This level does not imply a compliant
description.
1:
In addition to meeting the level 0 definition, the
resource description conforms syntactically to this
standard and to the encoding scheme used.
2:
In addition to meeting the level 1 definition, the
resource description refers to an existing resource that
has demonstrated to be functionally compliant.
When the resource is a service, it is consider to exist
and functionally compliant if use of the
service accessURL responds without error when used as
intended by the resource. If the service is a standard
one, it must also demonstrate the response is syntactically
compliant with the service standard in order to be
considered functionally compliant. If the resource is
not a service, then the ReferenceURL must be shown to
return a document without error.
3:
In addition to meeting the level 2 definition, the
resource description has been inspected by a human and
judged to comply semantically to this standard as well
as meeting any additional minimum quality criteria (e.g.,
providing values for important but non-required
metadata) set by the human inspector.
4:
In addition to meeting the level 3 definition, the
resource description meets additional quality criteria
set by the human inspector and is therefore considered
an excellent description of the resource. Consequently,
the resource is expected to be operate well as part of a
VO application or research study.
"""
def __init__(
self, config=None, pos=None, _name='validationLevel', validatedBy=None,
**kwargs
):
super().__init__(config, pos, _name, **kwargs)
self._validatedby = validatedBy
def __repr__(self):
return '<ValidationLevel validatedBy={}>{}</ValidationLevel>'.format(
self.validatedby, self.content)
@xmlattribute
def validatedby(self):
"""
The IVOA ID of the registry or organisation that
assigned the validation level.
"""
return self._validatedby
@validatedby.setter
def validatedby(self, validatedby):
self._validatedby = validatedby
[docs]class AccessURL(ContentMixin, Element):
"""
AccessURL element as described in
http://www.ivoa.net/xml/VOResource/v1.0
The URL (or base URL) that a client uses to access the
service. How this URL is to be interpreted and used
depends on the specific Interface subclass
"""
def __init__(
self, config=None, pos=None, _name='accessURL', use=None, **kwargs
):
super().__init__(config, pos, _name, **kwargs)
self._use = use
def __repr__(self):
return '<AccessURL use={}>{}</AccessURL>'.format(
self.use, self.content)
@xmlattribute
def use(self):
"""
A flag indicating whether this should be interpreted as a base
URL, a full URL, or a URL to a directory that will produce a
listing of files.
Possible values:
full:
Assume a full URL--that is, one that can be invoked directly
without alteration. This usually returns a single document or
file.
base:
Assume a base URL--that is, one requiring an extra portion to be
appended before being invoked.
dir:
Assume URL points to a directory that will return a listing of
files.
"""
return self._use
@use.setter
def use(self, use):
self._use = use
[docs]class MirrorURL(ContentMixin, Element):
"""
A URL available as a mirror of an access URL.
These come with a human-readable title intended to aid in mirror
selection.
"""
def __init__(
self, config=None, pos=None, _name='accessURL', title=None, **kwargs
):
super().__init__(config, pos, _name, **kwargs)
self._title = title
@xmlattribute
def title(self):
"""
A human-readable title for the mirror.
"""
return self._title
[docs]class SecurityMethod(ContentMixin, Element):
"""
SecurityMethod element as described in
http://www.ivoa.net/xml/VOResource/v1.0
A description of a security mechanism.
this type only allows one to refer to the mechanism via a URI.
Derived types would allow for more metadata.
"""
def __init__(
self, config=None, pos=None, _name='securityMethod', standardID=None,
**kwargs
):
super().__init__(config, pos, _name, **kwargs)
self._standardid = standardID
def __repr__(self):
return '<SecurityMethod standardID={}>{}</SecurityMethod>'.format(
self.standardid, self.content)
@xmlattribute(name='standardID')
def standardid(self):
"""
A URI identifier for a standard security mechanism.
"""
return self._standardid
@standardid.setter
def standardid(self, standardid):
self._standardid = standardid
[docs]class Interface(ElementWithXSIType):
"""
Interface element as described in
http://www.ivoa.net/xml/VOResource/v1.0
A description of a service interface.
Since this type is abstract, one must use an Interface subclassto describe
an actual interface.
Additional interface subtypes (beyond WebService and WebBrowser) are
defined in the VODataService schema.
"""
def __init__(
self, config=None, pos=None, _name='interface', version='1.0',
role=None, **kwargs
):
super().__init__(config, pos, _name, **kwargs)
self._xsi_type = kwargs.get('xsi:type')
self._version = version
self._role = role
self._resulttype = None
self._testquerystring = None
self._accessurls = HomogeneousList(AccessURL)
self._securitymethods = HomogeneousList(SecurityMethod)
self._mirrorurls = HomogeneousList(MirrorURL)
def __repr__(self):
return '<Interface role={}>...</Interface>'.format(
self.role)
[docs] def describe(self):
"""
Prints out a human readable description
"""
print('Interface {}'.format(self._xsi_type))
accessurls = '\n'.join(
accessurl.content for accessurl in self.accessurls)
print(indent(accessurls))
print()
@xmlattribute
def version(self):
"""
The version of a standard interface specification that this
interface complies with. When the interface is
provided in the context of a Capability element, then
the standard being refered to is the one identified by
the Capability's standardID element. If the standardID
is not provided, the meaning of this attribute is
undefined.
"""
return self._version
@version.setter
def version(self, version):
self._version = version
@xmlattribute
def role(self):
"""
A tag name the identifies the role the interface plays
in the particular capability. If the value is equal to
"std" or begins with "std:", then the interface refers
to a standard interface defined by the standard
referred to by the capability's standardID attribute.
For an interface complying with some registered
standard (i.e. has a legal standardID), the role can be
match against interface roles enumerated in standard
resource record. The interface descriptions in
the standard record can provide default descriptions
so that such details need not be repeated here.
"""
return self._role
@role.setter
def role(self, role):
self._role = role
@xmlelement(name='accessURL', cls=AccessURL)
def accessurls(self):
"""
A list of access urls in the interface. Must contain only `AccessURL`
objects.
"""
return self._accessurls
@xmlelement(name='mirrorURL', cls=MirrorURL)
def mirrorurls(self):
"""
mirror(s) for this access URL.
"""
return self._mirrorurls
@xmlelement(name='securityMethod', cls=SecurityMethod)
def securitymethods(self):
"""
the mechanism the client must employ to gain secure
access to the service.
when more than one method is listed, each one must
be employed to gain access.
"""
return self._securitymethods
@xmlelement(name='testQueryString')
def testquerystring(self):
"""
a string to be used in an interface-specific way to obtain a
non-empty result from the service.
"""
return self._testquerystring
@testquerystring.setter
def testquerystring(self, testquerystring):
self._testquerystring = testquerystring
@xmlelement
def resulttype(self):
"""
The MIME type of a document returned in the HTTP response.
"""
return self._resulttype
@resulttype.setter
def resulttype(self, resulttype):
self._resulttype = resulttype
[docs]class Capability(ElementWithXSIType):
"""
Capability element as described in
http://www.ivoa.net/xml/VOResource/v1.0
a description of what the service does
(in terms of context-specific behavior), and how to use it
(in terms of an interface)
"""
def __init__(
self, config=None, pos=None, _name='capability', standardID=None,
**kwargs
):
super().__init__(config, pos, _name, **kwargs)
self._description = None
self._standardid = standardID
self._validationlevels = HomogeneousList(ValidationLevel)
self._interfaces = HomogeneousList(Interface)
def __repr__(self):
return (
'<Capability standardID={}>'
'... {} validationLevels, {} interfaces ...'
'</Capability>'
).format(
self.standardid, len(self.validationlevels), len(self.interfaces))
[docs] def describe(self):
"""
Prints out a human readable description
"""
print("Capability {}".format(self.standardid))
print()
if self.description:
print(self.description)
print()
for interface in self.interfaces:
interface.describe()
@xmlelement(plain=True, multiple_exc=W06)
def description(self):
"""
A human-readable description of what this capability
provides as part of the over-all service
Use of this optional element is especially encouraged when
this capability is non-standard and is one of several
capabilities listed.
"""
return self._description
@description.setter
def description(self, description):
self._description = description
@xmlelement(name='validationLevel', cls=ValidationLevel)
def validationlevels(self):
"""
A numeric grade describing the quality of the
capability description and interface, when applicable,
to be used to indicate the confidence an end-user
can put in the resource as part of a VO application
or research study.
"""
return self._validationlevels
@xmlelement(name='interface', cls=Interface)
def interfaces(self):
"""
a description of how to call the service to access this capability
Since the Interface type is abstract, one must describe
the interface using a subclass of Interface, denoting
it via xsi:type.
Multiple occurances can describe different interfaces to
the logically same capability--i.e. data or functionality.
That is, the inputs accepted and the output provides should
be logically the same. For example, a WebBrowser interface
given in addition to a WebService interface would simply
provide an interactive, human-targeted interface to the
underlying WebService interface.
"""
return self._interfaces
@xmlattribute(name='standardID')
def standardid(self):
"""
A URI identifier for a standard service.
This provides a unique way to refer to a service
specification standard, such as a Simple Image Access service.
The use of an IVOA identifier here implies that a
VOResource description of the standard is registered and
accessible.
"""
return self._standardid
@standardid.setter
def standardid(self, standardid):
self._standardid = standardid
[docs]@Interface.register_xsi_type('vr:WebBrowser')
class WebBrowser(Interface):
"""
WebBrowser element as described in
http://www.ivoa.net/xml/VOResource/v1.0
A (form-based) interface intended to be accesed interactively by a user via
a web browser. The accessURL represents the URL of the web form itself.
"""
[docs]@Interface.register_xsi_type('vr:WebService')
class WebService(Interface):
"""
WebService element as described in
http://www.ivoa.net/xml/VOResource/v1.0
A Web Service that is describable by a WSDL document.
The accessURL element gives the Web Service's endpoint URL.
"""
def __init__(self, config=None, pos=None, _name='interface', **kwargs):
super().__init__(config, pos, _name, **kwargs)
self._wsdlurls = HomogeneousList(str)
@xmlelement(name='wsdlURL')
def wsdlurls(self):
"""
The location of the WSDL that describes this Web Service.
If not provided, the location is assumed to be the accessURL with
"?wsdl" appended.
Multiple occurances should represent mirror copies of the same WSDL
file.
"""
return self._wsdlurls