From df1d2fae200fd29a328dc5dc364b6c12551af237 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Brigitta=20Sip=C5=91cz?= Date: Sat, 17 Feb 2024 02:11:08 +0100 Subject: [PATCH] Merge pull request #416 from bsipocz/DOC_nitpicky DOC: Enabling nitpicky docs build --- docs/auth/index.rst | 4 ++ docs/conf.py | 12 +++++ docs/dal/index.rst | 20 ++++---- docs/index.rst | 5 +- docs/io/index.rst | 7 +-- docs/io/uws.rst | 6 +-- docs/io/vosi.rst | 6 +-- docs/nitpick-exceptions | 13 +++++ docs/registry/index.rst | 94 ++++++++++++++++++++--------------- docs/utils/index.rst | 16 ++++++ docs/utils/prototypes.rst | 1 + pyvo/auth/authsession.py | 2 +- pyvo/auth/authurls.py | 2 +- pyvo/dal/__init__.py | 4 +- pyvo/dal/adhoc.py | 28 +++++------ pyvo/dal/query.py | 4 +- pyvo/dal/scs.py | 18 +++---- pyvo/dal/sia.py | 18 +++---- pyvo/dal/sia2.py | 22 ++++---- pyvo/dal/sla.py | 16 +++--- pyvo/dal/ssa.py | 18 +++---- pyvo/dal/tap.py | 26 +++++----- pyvo/io/uws/endpoint.py | 4 +- pyvo/io/uws/tree.py | 1 + pyvo/io/vosi/endpoint.py | 4 +- pyvo/io/vosi/vodataservice.py | 6 +-- pyvo/io/vosi/voresource.py | 6 +-- pyvo/registry/__init__.py | 15 +++--- pyvo/registry/regtap.py | 14 ++---- pyvo/registry/rtcons.py | 11 ++-- 30 files changed, 228 insertions(+), 175 deletions(-) create mode 100644 docs/nitpick-exceptions create mode 100644 docs/utils/index.rst diff --git a/docs/auth/index.rst b/docs/auth/index.rst index bf094f22f..03608c38d 100644 --- a/docs/auth/index.rst +++ b/docs/auth/index.rst @@ -1,6 +1,9 @@ +.. _pyvo-auth: + ****************** Auth (`pyvo.auth`) ****************** + This module contains submodules which help handle auth when communicating with virtual observatory services. @@ -8,3 +11,4 @@ Reference/API ============= .. automodapi:: pyvo.auth + :no-inheritance-diagram: diff --git a/docs/conf.py b/docs/conf.py index 32db0328a..1e0529c35 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -161,3 +161,15 @@ edit_on_github_source_root = "" edit_on_github_doc_root = "docs" + + +# -- Enable nitpicky mode - which ensures that all references in the docs resolve ---- + +nitpicky = True +# See docs/nitpick-exceptions file for the actual listing. +nitpick_ignore = [] +for line in open("nitpick-exceptions"): + if line.strip() == "" or line.startswith("#"): + continue + dtype, target = line.split(None, 1) + nitpick_ignore.append((dtype, target.strip())) diff --git a/docs/dal/index.rst b/docs/dal/index.rst index 953007f05..917175a6c 100644 --- a/docs/dal/index.rst +++ b/docs/dal/index.rst @@ -105,11 +105,11 @@ return more than 10000 rows”). This information is contained in the data structure :py:class:`~pyvo.io.vosi.endpoint.CapabilitiesFile` available through -:py:attr:`~pyvo.dal.mixin.CapabilityMixin.capabilities`. +the ``pyvo.dal.vosi.CapabilityMixin.capabilities`` attribute. Exceptions ---------- -See :py:mod:`pyvo.dal.exceptions`. +See the ``pyvo.dal.exceptions`` module. .. _pyvo-services: @@ -622,7 +622,7 @@ Get the current job phase: EXECUTING Maximum run time in seconds is available and can be changed with -:py:attr:`~pyvo.dal.tap.AsyncTAPJob.execution_duration` +:py:attr:`~pyvo.dal.AsyncTAPJob.execution_duration` .. doctest-remote-data:: @@ -639,18 +639,18 @@ Obtaining the job url, which is needed to reconstruct the job at a later point: Besides ``run`` there are also several other job control methods: -* :py:meth:`~pyvo.dal.tap.AsyncTAPJob.abort` -* :py:meth:`~pyvo.dal.tap.AsyncTAPJob.delete` -* :py:meth:`~pyvo.dal.tap.AsyncTAPJob.wait` +* :py:meth:`~pyvo.dal.AsyncTAPJob.abort` +* :py:meth:`~pyvo.dal.AsyncTAPJob.delete` +* :py:meth:`~pyvo.dal.AsyncTAPJob.wait` .. note:: Usually the service deletes the job after a certain time, but it is a good practice to delete it manually when done. The destruction time can be obtained and changed with - :py:attr:`~pyvo.dal.tap.AsyncTAPJob.destruction` + :py:attr:`~pyvo.dal.AsyncTAPJob.destruction` -Also, :py:class:`pyvo.dal.tap.AsyncTAPJob` works as a context manager which +Also, :py:class:`pyvo.dal.AsyncTAPJob` works as a context manager which takes care of this automatically: .. doctest-remote-data:: @@ -667,9 +667,9 @@ Check for errors in the job execution: >>> job.raise_if_error() If the execution was successful, the resultset can be obtained using -:py:meth:`~pyvo.dal.tap.AsyncTAPJob.fetch_result` +:py:meth:`~pyvo.dal.AsyncTAPJob.fetch_result` -The result url is available under :py:attr:`~pyvo.dal.tap.AsyncTAPJob.result_uri` +The result url is available under :py:attr:`~pyvo.dal.AsyncTAPJob.result_uri` .. _pyvo-resultsets: diff --git a/docs/index.rst b/docs/index.rst index 91262306d..093354483 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -124,8 +124,8 @@ observational datasets through TAP tables), you can write: ivo://xcatdb/4xmm/tap -Using `pyvo` ------------- +Using ``pyvo`` +-------------- .. toctree:: :maxdepth: 1 @@ -134,4 +134,5 @@ Using `pyvo` registry/index io/index auth/index + utils/index utils/prototypes diff --git a/docs/io/index.rst b/docs/io/index.rst index ba48581e7..0f901ad89 100644 --- a/docs/io/index.rst +++ b/docs/io/index.rst @@ -1,6 +1,7 @@ -************** -IO (`pyvo.io`) -************** +**************** +IO (``pyvo.io``) +**************** + This module contains submodules which handle datastructures related to the virtual observatory. diff --git a/docs/io/uws.rst b/docs/io/uws.rst index eb3beaf88..20a55c05c 100644 --- a/docs/io/uws.rst +++ b/docs/io/uws.rst @@ -1,6 +1,6 @@ -******************* -UWS (`pyvo.io.uws`) -******************* +********************* +UWS (``pyvo.io.uws``) +********************* Reference/API ============= diff --git a/docs/io/vosi.rst b/docs/io/vosi.rst index 0fd9c75af..35f4a5241 100644 --- a/docs/io/vosi.rst +++ b/docs/io/vosi.rst @@ -1,6 +1,6 @@ -********************* -VOSI (`pyvo.io.vosi`) -********************* +*********************** +VOSI (``pyvo.io.vosi``) +*********************** Reference/API ============= diff --git a/docs/nitpick-exceptions b/docs/nitpick-exceptions new file mode 100644 index 000000000..db309a9a1 --- /dev/null +++ b/docs/nitpick-exceptions @@ -0,0 +1,13 @@ +# Deprecated API +py:class pyvo.dal.vosi.AvailabilityMixin + +# Non-public API classes. We should probably remove references to them altogether +py:obj pyvo.io.uws.tree.Jobs +py:class pyvo.dal.vosi.CapabilityMixin +py:class pyvo.dal.vosi.EndpointMixin +py:class pyvo.dal.adhoc.AxisParamMixin +py:class pyvo.dam.obscore.ObsCoreMetadata +py:obj pyvo.registry.regtap.Interface +# There is no public API docs for this, yet it's useful to leave the reference in +py:obj pyvo.io.vosi.exceptions +py:class pyvo.dal.exceptions.PyvoUserWarning diff --git a/docs/registry/index.rst b/docs/registry/index.rst index fe14dd74e..cd99fc6b3 100644 --- a/docs/registry/index.rst +++ b/docs/registry/index.rst @@ -42,35 +42,35 @@ This function accepts one or more search constraints, which can be 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 +* :py:class:`~pyvo.registry.Freetext` (``keywords``): one or more freetext words, mached in the title, description or subject of the resource. -* :py:class:`pyvo.registry.Servicetype` (``servicetype``): constrain to +* :py:class:`~pyvo.registry.Servicetype` (``servicetype``): constrain to one of tap, ssa, sia, conesearch (or full ivoids for other service types). This is the constraint you want to use for service discovery. -* :py:class:`pyvo.registry.UCD` (``ucd``): constrain by one or more UCD +* :py:class:`~pyvo.registry.UCD` (``ucd``): constrain by one or more UCD patterns; resources match when they serve columns having a matching UCD (e.g., ``phot.mag;em.ir.%`` for “any infrared magnitude”). -* :py:class:`pyvo.registry.Waveband` (``waveband``): one or more terms +* :py:class:`~pyvo.registry.Waveband` (``waveband``): one or more terms from the vocabulary at http://www.ivoa.net/rdf/messenger giving the rough spectral location of the resource. -* :py:class:`pyvo.registry.Author` (``author``): an author (“creator”). +* :py:class:`~pyvo.registry.Author` (``author``): an author (“creator”). This is a single SQL pattern, and given the sloppy practices in the VO for how to write author names, you should probably generously use wildcards. -* :py:class:`pyvo.registry.Datamodel` (``datamodel``): one of obscore, +* :py:class:`~pyvo.registry.Datamodel` (``datamodel``): one of obscore, epntap, or regtap: only return TAP services having tables of this kind. -* :py:class:`pyvo.registry.Ivoid` (``ivoid``): exactly match a single +* :py:class:`~pyvo.registry.Ivoid` (``ivoid``): exactly match a single IVOA identifier (that is, in effect, the primary key in the VO). -* :py:class:`pyvo.registry.Spatial` (``spatial``): match resources +* :py:class:`~pyvo.registry.Spatial` (``spatial``): match resources covering, enclosed or overlapping a certain geometry (point, circle, polygon, or MOC). *RegTAP 1.2 Extension* -* :py:class:`pyvo.registry.Spectral` (``spectral``): match resources +* :py:class:`~pyvo.registry.Spectral` (``spectral``): match resources covering a certain part of the spectrum (usually, but not limited to, the electromagnetic spectrum). *RegTAP 1.2 Extension* -* :py:class:`pyvo.registry.Temporal` (``temporal``): match resources +* :py:class:`~pyvo.registry.Temporal` (``temporal``): match resources covering a some point or interval in time. *RegTAP 1.2 Extension* Multiple constraints are combined conjunctively (”AND”). @@ -109,7 +109,7 @@ is equivalent to: >>> resources = registry.search(waveband=["Radio", "Millimeter"]) -There is also :py:meth:`pyvo.registry.get_RegTAP_query`, accepting the +There is also :py:meth:`~pyvo.registry.get_RegTAP_query`, accepting the same arguments as :py:meth:`pyvo.registry.search`. This function simply returns the ADQL query that search would execute. This is may be useful to construct custom RegTAP queries, which could then be executed on @@ -130,7 +130,7 @@ you would say: ... registry.Freetext("supernova")) After that, ``resources`` is an instance of -:py:class:`pyvo.registry.regtap.RegistryResults`, which you can iterate over. In +:py:class:`~pyvo.registry.regtap.RegistryResults`, which you can iterate over. In interactive data discovery, however, it is usually preferable to use the ``to_table`` method for an overview of the resources available: @@ -171,7 +171,7 @@ title, description, and perhaps the access mode (“interface”) offered. In the list of interfaces, you will sometimes spot an ``#aux`` after a standard id; this is a minor VO technicality that you can in practice ignore. For instance, you can simply construct -:py:class:`pyvo.dal.TAPService`-s from ``tap#aux`` interfaces. +:py:class:`~pyvo.dal.TAPService`-s from ``tap#aux`` interfaces. Once you have found a resource you would like to query, you can pick it by index; however, @@ -183,7 +183,7 @@ are not), but it is rather clunky, and in the real VO short name collisions should be very rare. Use the ``get_service`` method of -:py:class:`pyvo.registry.regtap.RegistryResource` to obtain a DAL service +:py:class:`~pyvo.registry.regtap.RegistryResource` to obtain a DAL service object for a particular sort of interface. To query the fourth match using simple cone search, you would thus say: @@ -198,6 +198,7 @@ thus say: ------------ ------------ -------- ----- ... ---- ------------ ------------ 117.98645833 73.00961111 0.588592 986 ... NED 07 51 56.750 +73 00 34.60 + 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 @@ -382,7 +383,7 @@ similar to :ref:`pyvo-resultsets`; just remember that for interactive use there is the ``to_tables`` method discussed above. The individual items are instances of -:py:class:`pyvo.registry.regtap.RegistryResource`, which expose many +:py:class:`~pyvo.registry.regtap.RegistryResource`, which expose many pieces of metadata (e.g., title, description, creators, etc) in attributes named like their RegTAP counterparts (see the class documentation). Some attributes deserve a second look. @@ -569,29 +570,40 @@ should catch errors and, at least in interactive sessions, provide some way to interrupt overly long queries. Here is an example for how to query all obscore services; remove the ``break`` at the end of the loop to actually do the global query (it's there so that you don't blindly -run all-VO queries without reading at least this sentence):: - - from astropy import table - from pyvo import registry - - QUERY = "SELECT TOP 1 s_ra, s_dec from ivoa.obscore" - - results = [] - for svc_rec in registry.search( - datamodel="obscore", servicetype="tap"): - print("Querying {}".format(svc_rec.res_title)) - try: - svc = svc_rec.get_service("tap") - results.append( - svc.run_sync(QUERY).to_table()) - except KeyboardInterrupt: - # someone lost their patience with a service. Query next. - pass - except Exception as msg: - # some service is broken; you *should* complain, but - print(" Broken: {} ({}). Complain to {}.\n".format( - svc_rec.ivoid, msg, svc_rec.get_contact())) - break - - total_result = table.vstack(results) - print(total_result) +run all-VO queries without reading at least this sentence): + +.. doctest-remote-data:: + + >>> from astropy.table import vstack + >>> from pyvo import registry + >>> + >>> QUERY = "SELECT TOP 1 s_ra, s_dec from ivoa.obscore" + >>> + >>> results = [] + >>> for i, svc_rec in enumerate(registry.search(datamodel="obscore", servicetype="tap")): + ... # print("Querying {}".format(svc_rec.res_title)) + ... try: + ... svc = svc_rec.get_service(service_type="tap", lax=True) + ... results.append( + ... svc.run_sync(QUERY).to_table()) + ... except KeyboardInterrupt: + ... # someone lost their patience with a service. Query next. + ... pass + ... except Exception as msg: + ... # some service is broken; you *should* complain, but + ... #print(" Broken: {} ({}). Complain to {}.\n".format( + ... pass # svc_rec.ivoid, msg, svc_rec.get_contact())) + ... if i == 5: + ... break + >>> total_result = vstack(results) # doctest: +IGNORE_WARNINGS + >>> total_result # doctest: +IGNORE_OUTPUT + + s_ra s_dec + deg deg + float64 float64 + ------------------ ------------------- + 350.4619 -9.76139 + 208.360833592735 52.3611106494996 + 148.204840298431 29.1690999975089 + 243.044008 -51.778222 + 321.63278049999997 -54.579285999999996 diff --git a/docs/utils/index.rst b/docs/utils/index.rst new file mode 100644 index 000000000..7dcaa929b --- /dev/null +++ b/docs/utils/index.rst @@ -0,0 +1,16 @@ +.. _pyvo-utils: + +*************************** +PyVO utils (``pyvo.utils``) +*************************** + + +This module contains utilities and base classes intended for internal use +within PyVO or other dependent libraries. + + +Reference/API +============= + +.. automodapi:: pyvo.utils.xml.elements + :no-inheritance-diagram: diff --git a/docs/utils/prototypes.rst b/docs/utils/prototypes.rst index 9bc50d573..a52278eae 100644 --- a/docs/utils/prototypes.rst +++ b/docs/utils/prototypes.rst @@ -87,6 +87,7 @@ Reference/API ============= .. automodapi:: pyvo.utils.prototype +.. automodapi:: pyvo.utils.protofeature Existing Prototypes diff --git a/pyvo/auth/authsession.py b/pyvo/auth/authsession.py index 01fb15fe9..b60d6ebee 100644 --- a/pyvo/auth/authsession.py +++ b/pyvo/auth/authsession.py @@ -53,7 +53,7 @@ def update_from_capabilities(self, capabilities): Parameters ---------- capabilities : object - List of `~pyvo.io.vosi.voresource.Capabilities` + List of `~pyvo.io.vosi.voresource.Capability` """ self._auth_urls.update_from_capabilities(capabilities) diff --git a/pyvo/auth/authurls.py b/pyvo/auth/authurls.py index 74479399a..0a658eb9b 100644 --- a/pyvo/auth/authurls.py +++ b/pyvo/auth/authurls.py @@ -25,7 +25,7 @@ def update_from_capabilities(self, capabilities): Parameters ---------- capabilities : object - List of `~pyvo.io.vosi.voresource.Capabilities` + List of `~pyvo.io.vosi.voresource.Capability` """ for c in capabilities: for i in c.interfaces: diff --git a/pyvo/dal/__init__.py b/pyvo/dal/__init__.py index 134451305..8a6213155 100644 --- a/pyvo/dal/__init__.py +++ b/pyvo/dal/__init__.py @@ -9,7 +9,7 @@ from .query import DALService, DALQuery, DALResults, Record from .sia import SIAService, SIAQuery, SIAResults, SIARecord -from .sia2 import SIA2Service, SIA2Query, SIA2Results +from .sia2 import SIA2Service, SIA2Query, SIA2Results, ObsCoreRecord from .ssa import SSAService, SSAQuery, SSAResults, SSARecord from .sla import SLAService, SLAQuery, SLAResults, SLARecord from .scs import SCSService, SCSQuery, SCSResults, SCSRecord @@ -27,7 +27,7 @@ "DALQuery", "SIAQuery", "SIA2Query", "SSAQuery", "SLAQuery", "SCSQuery", "TAPQuery", "DALResults", "SIAResults", "SIA2Results", "SSAResults", "SLAResults", "SCSResults", "TAPResults", - "Record", + "Record", "ObsCoreRecord", "SIARecord", "SSARecord", "SLARecord", "SCSRecord", "AsyncTAPJob", "DALAccessError", "DALProtocolError", "DALFormatError", "DALServiceError", diff --git a/pyvo/dal/adhoc.py b/pyvo/dal/adhoc.py index fe7783915..f31dc1df5 100644 --- a/pyvo/dal/adhoc.py +++ b/pyvo/dal/adhoc.py @@ -104,7 +104,7 @@ def _get_accessurl_from_params(params): class AdhocServiceResultsMixin: """ - Mixing for adhoc:service functionallity for results classes. + Mixin for adhoc:service functionallity for results classes. """ def __init__(self, votable, url=None, session=None): @@ -168,7 +168,7 @@ def get_adhocservice_by_id(self, id_): class DatalinkResultsMixin(AdhocServiceResultsMixin): """ - Mixing for datalink functionallity for results classes. + Mixin for datalink functionallity for results classes. """ def iter_datalinks(self): @@ -334,7 +334,7 @@ class DatalinkQuery(DALQuery): The base URL for the query, which controls where the query will be sent when one of the execute functions is called, is typically set at construction time; however, it can be updated later via the - :py:attr:`~pyvo.dal.query.DALQuery.baseurl` to send a configured + :py:attr:`~pyvo.dal.DALQuery.baseurl` to send a configured query to another service. A session can also optionally be passed in that will be used for @@ -456,25 +456,25 @@ class DatalinkResults(DatalinkResultsMixin, DALResults): This class supports iterable semantics; thus, individual records (in the form of - :py:class:`~pyvo.dal.query.Record` instances) are typically + :py:class:`~pyvo.dal.Record` instances) are typically accessed by iterating over an ``DatalinkResults`` instance. Alternatively, records can be accessed randomly via :py:meth:`getrecord` or through a Python Database API (v2) - Cursor (via :py:meth:`~pyvo.dal.query.DALResults.cursor`). + Cursor (via :py:meth:`~pyvo.dal.DALResults.cursor`). Column-based data access is possible via the - :py:meth:`~pyvo.dal.query.DALResults.getcolumn` method. + :py:meth:`~pyvo.dal.DALResults.getcolumn` method. ``DatalinkResults`` is essentially a wrapper around an Astropy :py:mod:`~astropy.io.votable` :py:class:`~astropy.io.votable.tree.TableElement` instance where the columns contain the various metadata describing the images. One can access that VOTable directly via the - :py:attr:`~pyvo.dal.query.DALResults.votable` attribute. Thus, + :py:attr:`~pyvo.dal.DALResults.votable` attribute. Thus, when one retrieves a whole column via - :py:meth:`~pyvo.dal.query.DALResults.getcolumn`, the result is + :py:meth:`~pyvo.dal.DALResults.getcolumn`, the result is a Numpy array. Alternatively, one can manipulate the results - as an Astropy :py:class:`~astropy.table.table.Table` via the + as an Astropy :py:class:`~astropy.table.Table` via the following conversion: ``table = results.to_table()`` @@ -482,7 +482,7 @@ class DatalinkResults(DatalinkResultsMixin, DALResults): ``DatalinkResults`` supports the array item operator ``[...]`` in a read-only context. When the argument is numerical, the result is an - :py:class:`~pyvo.dal.query.Record` instance, representing the + :py:class:`~pyvo.dal.Record` instance, representing the record at the position given by the numerical index. If the argument is a string, it is interpreted as the name of a column, and the data from the column matching that name is returned as @@ -494,7 +494,7 @@ def getrecord(self, index): return a representation of a datalink result record that follows dictionary semantics. The keys of the dictionary are those returned by this instance's fieldnames attribute. The returned record has the - additional function :py:meth:`~pyvo.dal.query.DALResults.getdataset` + additional function ``getdataset`` Parameters ---------- @@ -515,7 +515,7 @@ def getrecord(self, index): See Also -------- - Record + pyvo.dal.Record """ return DatalinkRecord(self, index, session=self._session) @@ -635,7 +635,7 @@ class SodaRecordMixin: """ Mixin for soda functionality for record classes. If used, it's result class must have - `pyvo.dal.datalink.AdhocServiceResultsMixin` mixed in. + `pyvo.dal.adhoc.AdhocServiceResultsMixin` mixed in. """ def _get_soda_resource(self): @@ -785,7 +785,7 @@ def getdataurl(self): """ return the URL contained in the access URL column which can be used to retrieve the dataset described by this record. Raises - :py:class:`~pyvo.dal.query.DALServiceError` if theres an error. + :py:class:`~pyvo.dal.DALServiceError` if theres an error. """ if self.error_message: raise DALServiceError(self.error_message) diff --git a/pyvo/dal/query.py b/pyvo/dal/query.py index 43dcff546..887acb31f 100644 --- a/pyvo/dal/query.py +++ b/pyvo/dal/query.py @@ -310,7 +310,7 @@ def __init__(self, votable, url=None, session=None): See Also -------- - DALFormatError + pyvo.dal.DALFormatError """ self._votable = votable @@ -638,7 +638,7 @@ def broadcast_samp(self, client_name=None): def cursor(self): """ return a cursor that is compliant with the Python Database API's - :class:`.Cursor` interface. See PEP 249 for details. + ``Cursor`` interface. See PEP 249 for details. """ from .dbapi2 import Cursor return Cursor(self) diff --git a/pyvo/dal/scs.py b/pyvo/dal/scs.py index da3f4242b..26d528c76 100644 --- a/pyvo/dal/scs.py +++ b/pyvo/dal/scs.py @@ -76,8 +76,8 @@ def search(url, pos, radius=1.0, verbosity=2, **keywords): See Also -------- SCSResults - pyvo.dal.query.DALServiceError - pyvo.dal.query.DALQueryError + pyvo.dal.DALServiceError + pyvo.dal.DALQueryError """ return SCSService(url).search(pos=pos, radius=radius, verbosity=verbosity, **keywords) @@ -181,8 +181,8 @@ def search(self, pos, radius=1.0, verbosity=2, **keywords): See Also -------- SCSResults - pyvo.dal.query.DALServiceError - pyvo.dal.query.DALQueryError + pyvo.dal.DALServiceError + pyvo.dal.DALQueryError """ return self.create_query(pos=pos, radius=radius, verbosity=verbosity, **keywords).execute() @@ -263,7 +263,7 @@ class SCSQuery(DALQuery): The base URL for the query, which controls where the query will be sent when one of the execute functions is called, is typically set at construction time; however, it can be updated later via the - :py:attr:`~pyvo.dal.query.DALQuery.baseurl` to send a configured + :py:attr:`~pyvo.dal.DALQuery.baseurl` to send a configured query to another service. In addition to the search constraint attributes described below, search @@ -429,18 +429,18 @@ class SCSResults(DatalinkResultsMixin, DALResults): Alternatively, records can be accessed randomly via :py:meth:`getrecord` or through a Python Database API (v2) - Cursor (via :py:meth:`~pyvo.dal.query.DALResults.cursor`). + Cursor (via :py:meth:`~pyvo.dal.DALResults.cursor`). Column-based data access is possible via the - :py:meth:`~pyvo.dal.query.DALResults.getcolumn` method. + :py:meth:`~pyvo.dal.DALResults.getcolumn` method. ``SCSResults`` is essentially a wrapper around an Astropy :py:mod:`~astropy.io.votable` :py:class:`~astropy.io.votable.tree.TableElement` instance where the columns contain the various metadata describing the images. One can access that VOTable directly via the - :py:attr:`~pyvo.dal.query.DALResults.votable` attribute. Thus, + :py:attr:`~pyvo.dal.DALResults.votable` attribute. Thus, when one retrieves a whole column via - :py:meth:`~pyvo.dal.query.DALResults.getcolumn`, the result is + :py:meth:`~pyvo.dal.DALResults.getcolumn`, the result is a Numpy array. Alternatively, one can manipulate the results as an Astropy :py:class:`~astropy.table.table.Table` via the following conversion: diff --git a/pyvo/dal/sia.py b/pyvo/dal/sia.py index 1f8e67de6..d2efcc1ee 100644 --- a/pyvo/dal/sia.py +++ b/pyvo/dal/sia.py @@ -109,8 +109,8 @@ def search( See Also -------- SIAResults - pyvo.dal.query.DALServiceError - pyvo.dal.query.DALQueryError + pyvo.dal.DALServiceError + pyvo.dal.DALQueryError """ service = SIAService(url) return service.search(pos=pos, size=size, format=format, intersect=intersect, @@ -252,8 +252,8 @@ def search( See Also -------- SIAResults - pyvo.dal.query.DALServiceError - pyvo.dal.query.DALQueryError + pyvo.dal.DALServiceError + pyvo.dal.DALQueryError """ return self.create_query( pos=pos, size=size, format=format, intersect=intersect, verbosity=verbosity, **keywords).execute() @@ -335,7 +335,7 @@ class SIAQuery(DALQuery): The base URL for the query, which controls where the query will be sent when one of the execute functions is called, is typically set at construction time; however, it can be updated later via the - :py:attr:`~pyvo.dal.query.DALQuery.baseurl` to send a configured + :py:attr:`~pyvo.dal.DALQuery.baseurl` to send a configured query to another service. In addition to the search constraint attributes described below, search @@ -590,18 +590,18 @@ class SIAResults(DatalinkResultsMixin, DALResults): Alternatively, records can be accessed randomly via :py:meth:`getrecord` or through a Python Database API (v2) - Cursor (via :py:meth:`~pyvo.dal.query.DALResults.cursor`). + Cursor (via :py:meth:`~pyvo.dal.DALResults.cursor`). Column-based data access is possible via the - :py:meth:`~pyvo.dal.query.DALResults.getcolumn` method. + :py:meth:`~pyvo.dal.DALResults.getcolumn` method. ``SIAResults`` is essentially a wrapper around an Astropy :py:mod:`~astropy.io.votable` :py:class:`~astropy.io.votable.tree.TableElement` instance where the columns contain the various metadata describing the images. One can access that VOTable directly via the - :py:attr:`~pyvo.dal.query.DALResults.votable` attribute. Thus, + :py:attr:`~pyvo.dal.DALResults.votable` attribute. Thus, when one retrieves a whole column via - :py:meth:`~pyvo.dal.query.DALResults.getcolumn`, the result is + :py:meth:`~pyvo.dal.DALResults.getcolumn`, the result is a Numpy array. Alternatively, one can manipulate the results as an Astropy :py:class:`~astropy.table.table.Table` via the following conversion: diff --git a/pyvo/dal/sia2.py b/pyvo/dal/sia2.py index eb3a3312e..7601ff152 100644 --- a/pyvo/dal/sia2.py +++ b/pyvo/dal/sia2.py @@ -4,7 +4,7 @@ A Simple Image Access v2 (SIA2) service allows a client to search for images based on a number of criteria/parameters. The results are -represented in `pyvo.dam.obscore.ObsCoreMetadata` format. +represented in ``pyvo.dam.ObsCoreMetadata`` format. The ``SIA2Service`` class can represent a specific service available at a URL endpoint. @@ -45,7 +45,7 @@ the energy interval(s) to be searched for data. time : single or list of `~astropy.time.Time` or compatible strings the time interval(s) to be searched for data. -pol : single or list of str from `pyvo.dam.obscore.POLARIZATION_STATES` +pol : single or list of str from ``pyvo.dam.obscore.POLARIZATION_STATES`` the polarization state(s) to be searched for data. field_of_view : single or list of tuples angle units (default arcsec) @@ -76,7 +76,7 @@ data_type : 'image'|'cube' specifies the type of the data calib_level : single or list from enum - `pyvo.dam.obscore.CALIBRATION_LEVELS` + ``pyvo.dam.obscore.CALIBRATION_LEVELS`` specifies the calibration level of the data. Can be a single value or a list of values target_name : single or list of str @@ -228,7 +228,7 @@ def search(self, pos=None, band=None, time=None, pol=None, class SIA2Query(DALQuery, AxisParamMixin): """ - a class very similar to :py:attr:`~pyvo.dal.query.SIAQuery` class but + a class very similar to :py:attr:`~pyvo.dal.SIAQuery` class but used to interact with SIA2 services. """ @@ -278,8 +278,8 @@ def __init__(self, url, pos=None, band=None, time=None, pol=None, See Also -------- SIA2Results - pyvo.dal.query.DALServiceError - pyvo.dal.query.DALQueryError + pyvo.dal.DALServiceError + pyvo.dal.DALQueryError """ super().__init__(url, session=session) @@ -485,18 +485,18 @@ class SIA2Results(DatalinkResultsMixin, DALResults): Alternatively, records can be accessed randomly via :py:meth:`getrecord` or through a Python Database API (v2) - Cursor (via :py:meth:`~pyvo.dal.query.DALResults.cursor`). + Cursor (via :py:meth:`~pyvo.dal.DALResults.cursor`). Column-based data access is possible via the - :py:meth:`~pyvo.dal.query.DALResults.getcolumn` method. + :py:meth:`~pyvo.dal.DALResults.getcolumn` method. ``SIA2Results`` is essentially a wrapper around an Astropy :py:mod:`~astropy.io.votable` :py:class:`~astropy.io.votable.tree.TableElement` instance where the columns contain the various metadata describing the images. One can access that VOTable directly via the - :py:attr:`~pyvo.dal.query.DALResults.votable` attribute. Thus, + :py:attr:`~pyvo.dal.DALResults.votable` attribute. Thus, when one retrieves a whole column via - :py:meth:`~pyvo.dal.query.DALResults.getcolumn`, the result is + :py:meth:`~pyvo.dal.DALResults.getcolumn`, the result is a Numpy array. Alternatively, one can manipulate the results as an Astropy :py:class:`~astropy.table.table.Table` via the following conversion: @@ -1078,7 +1078,7 @@ def pol_xel(self): """ Number of different polarization states present in the data. The default value is 0, indicating that polarization was not explicitly - observed. Corresponding values are stored in the `pol` property + observed. Corresponding values are stored in the ``pol`` property """ return self.get('pol_xel') diff --git a/pyvo/dal/sla.py b/pyvo/dal/sla.py index 25ef7d857..f8b5891f7 100644 --- a/pyvo/dal/sla.py +++ b/pyvo/dal/sla.py @@ -158,8 +158,8 @@ def search(self, wavelength, **keywords): See Also -------- SLAResults - pyvo.dal.query.DALServiceError - pyvo.dal.query.DALQueryError + pyvo.dal.DALServiceError + pyvo.dal.DALQueryError """ return self.create_query(wavelength, **keywords).execute() @@ -230,7 +230,7 @@ class SLAQuery(DALQuery): The base URL for the query, which controls where the query will be sent when one of the execute functions is called, is typically set at construction time; however, it can be updated later via the - :py:attr:`~pyvo.dal.query.DALQuery.baseurl` to send a configured + :py:attr:`~pyvo.dal.DALQuery.baseurl` to send a configured query to another service. In addition to the search constraint attributes described below, search @@ -357,23 +357,23 @@ class SLAResults(DALResults): This class supports iterable semantics; thus, individual records (in the form of - :py:class:`~pyvo.dal.sia.SLARecord` instances) are typically + :py:class:`~pyvo.dal.sla.SLARecord` instances) are typically accessed by iterating over an ``SLAResults`` instance. Alternatively, records can be accessed randomly via :py:meth:`getrecord` or through a Python Database API (v2) - Cursor (via :py:meth:`~pyvo.dal.query.DALResults.cursor`). + Cursor (via :py:meth:`~pyvo.dal.DALResults.cursor`). Column-based data access is possible via the - :py:meth:`~pyvo.dal.query.DALResults.getcolumn` method. + :py:meth:`~pyvo.dal.DALResults.getcolumn` method. ``SLAResults`` is essentially a wrapper around an Astropy :py:mod:`~astropy.io.votable` :py:class:`~astropy.io.votable.tree.TableElement` instance where the columns contain the various metadata describing the images. One can access that VOTable directly via the - :py:attr:`~pyvo.dal.query.DALResults.votable` attribute. Thus, + :py:attr:`~pyvo.dal.DALResults.votable` attribute. Thus, when one retrieves a whole column via - :py:meth:`~pyvo.dal.query.DALResults.getcolumn`, the result is + :py:meth:`~pyvo.dal.DALResults.getcolumn`, the result is a Numpy array. Alternatively, one can manipulate the results as an Astropy :py:class:`~astropy.table.table.Table` via the following conversion: diff --git a/pyvo/dal/ssa.py b/pyvo/dal/ssa.py index be31a51b2..ea577e897 100644 --- a/pyvo/dal/ssa.py +++ b/pyvo/dal/ssa.py @@ -98,8 +98,8 @@ def search( See Also -------- SSAResults - pyvo.dal.query.DALServiceError - pyvo.dal.query.DALQueryError + pyvo.dal.DALServiceError + pyvo.dal.DALQueryError """ return SSAService(baseurl).search( pos=pos, diameter=diameter, band=band, time=time, format=format, **keywords) @@ -207,8 +207,8 @@ def search( See Also -------- SSAResults - pyvo.dal.query.DALServiceError - pyvo.dal.query.DALQueryError + pyvo.dal.DALServiceError + pyvo.dal.DALQueryError """ return self.create_query( pos=pos, diameter=diameter, band=band, time=time, format=format, **keywords).execute() @@ -299,7 +299,7 @@ class SSAQuery(DALQuery): The base URL for the query, which controls where the query will be sent when one of the execute functions is called, is typically set at construction time; however, it can be updated later via the - :py:attr:`~pyvo.dal.query.DALQuery.baseurl` to send a configured + :py:attr:`~pyvo.dal.DALQuery.baseurl` to send a configured query to another service. The typical function for submitting the query is ``execute()``; however, @@ -591,18 +591,18 @@ class SSAResults(DatalinkResultsMixin, DALResults): Alternatively, records can be accessed randomly via :py:meth:`getrecord` or through a Python Database API (v2) - Cursor (via :py:meth:`~pyvo.dal.query.DALResults.cursor`). + Cursor (via :py:meth:`~pyvo.dal.DALResults.cursor`). Column-based data access is possible via the - :py:meth:`~pyvo.dal.query.DALResults.getcolumn` method. + :py:meth:`~pyvo.dal.DALResults.getcolumn` method. ``SSAResults`` is essentially a wrapper around an Astropy :py:mod:`~astropy.io.votable` :py:class:`~astropy.io.votable.tree.TableElement` instance where the columns contain the various metadata describing the spectra. One can access that VOTable directly via the - :py:attr:`~pyvo.dal.query.DALResults.votable` attribute. Thus, + :py:attr:`~pyvo.dal.DALResults.votable` attribute. Thus, when one retrieves a whole column via - :py:meth:`~pyvo.dal.query.DALResults.getcolumn`, the result is + :py:meth:`~pyvo.dal.DALResults.getcolumn`, the result is a Numpy array. Alternatively, one can manipulate the results as an Astropy :py:class:`~astropy.table.table.Table` via the following conversion: diff --git a/pyvo/dal/tap.py b/pyvo/dal/tap.py index 248d03754..25bbdf59a 100644 --- a/pyvo/dal/tap.py +++ b/pyvo/dal/tap.py @@ -400,7 +400,7 @@ def get_job(self, job_id): Returns ------- - `~pyvo.io.vosi.endpoint.JobSummary` corresponding to the job ID + `~pyvo.io.uws.tree.JobSummary` corresponding to the job ID """ response = self._session.get( self.baseurl + '/async/' + job_id, @@ -415,7 +415,7 @@ def get_job_list(self, phases=None, after=None, last=None, lists jobs that the caller can see in the current security context. The list can be filtered on the server side by the phases of the jobs, creation date time or - Note that by default jobs in 'ARCHIVED` phase are not returned. + Note that by default jobs in 'ARCHIVED' phase are not returned. Parameters ---------- @@ -433,7 +433,7 @@ def get_job_list(self, phases=None, after=None, last=None, Returns ------- - list of `~pyvo.io.vosi.endpoint.JobSummary` + list of `~pyvo.io.uws.tree.JobSummary` """ params = {'PHASE': phases, 'LAST': last} @@ -618,7 +618,7 @@ def create( cls, baseurl, query, language="ADQL", maxrec=None, uploads=None, session=None, **keywords): """ - creates a async tap job on the server under `baseurl` + creates a async tap job on the server under ``baseurl`` Parameters ---------- @@ -727,7 +727,7 @@ def phase(self): @property def execution_duration(self): """ - maximum execution duration as ~`astropy.time.TimeDelta` + maximum execution duration as `~astropy.time.TimeDelta`. """ self._update() return self._job.executionduration @@ -1016,7 +1016,7 @@ class TAPQuery(DALQuery): The base URL for the query, which controls where the query will be sent when one of the execute functions is called, is typically set at construction time; however, it can be updated later via the - :py:attr:`~pyvo.dal.query.DALQuery.baseurl` to send a configured + :py:attr:`~pyvo.dal.DALQuery.baseurl` to send a configured query to another service. In addition to the search constraint attributes described below, search @@ -1145,12 +1145,12 @@ class TAPResults(DatalinkResultsMixin, DALResults): This class supports iterable semantics; thus, individual records (in the form of - :py:class:`~pyvo.dal.query.Record` instances) are typically + :py:class:`~pyvo.dal.Record` instances) are typically accessed by iterating over an ``TAPResults`` instance. Alternatively, records can be accessed randomly via :py:meth:`getrecord` or through a Python Database API (v2) - Cursor (via :py:meth:`~pyvo.dal.query.DALResults.cursor`). + Cursor (via :py:meth:`~pyvo.dal.DALResults.cursor`). Column-based data access is possible via the :py:meth:`~pyvo.dal.query.DALResults.getcolumn` method. @@ -1159,19 +1159,19 @@ class TAPResults(DatalinkResultsMixin, DALResults): :py:class:`~astropy.io.votable.tree.TableElement` instance where the columns contain the various metadata describing the images. One can access that VOTable directly via the - :py:attr:`~pyvo.dal.query.DALResults.votable` attribute. Thus, + :py:attr:`pyvo.dal.DALResults.votable` attribute. Thus, when one retrieves a whole column via - :py:meth:`~pyvo.dal.query.DALResults.getcolumn`, the result is + :py:meth:`~pyvo.dal.DALResults.getcolumn`, the result is a Numpy array. Alternatively, one can manipulate the results - as an Astropy :py:class:`~astropy.table.table.Table` via the + as an Astropy :py:class:`astropy.table.Table` via the following conversion: - ``table = results.table`` + ``table = results.to_table`` ``SIAResults`` supports the array item operator ``[...]`` in a read-only context. When the argument is numerical, the result is an - :py:class:`~pyvo.dal.query.Record` instance, representing the + :py:class:`~pyvo.dal.Record` instance, representing the record at the position given by the numerical index. If the argument is a string, it is interpreted as the name of a column, and the data from the column matching that name is returned as diff --git a/pyvo/io/uws/endpoint.py b/pyvo/io/uws/endpoint.py index 33ed2c3ae..02477a5d5 100644 --- a/pyvo/io/uws/endpoint.py +++ b/pyvo/io/uws/endpoint.py @@ -54,7 +54,7 @@ def parse_job( ): """ Parses a job xml file (or file-like object), and returns a - `~pyvo.io.uws.tree.JobFile` object. + `~pyvo.io.uws.endpoint.JobFile` object. Parameters ---------- @@ -75,7 +75,7 @@ def parse_job( Returns ------- - `~pyvo.io.vosi.endpoint.JobFile` object + `~pyvo.io.uws.endpoint.JobFile` object See also -------- diff --git a/pyvo/io/uws/tree.py b/pyvo/io/uws/tree.py index e918e4b48..15ee75cb2 100644 --- a/pyvo/io/uws/tree.py +++ b/pyvo/io/uws/tree.py @@ -348,6 +348,7 @@ def id_(self, id_): class Results(UWSElement, HomogeneousList): + """ """ def __init__(self, config=None, pos=None, _name='results', **kwargs): HomogeneousList.__init__(self, Result) UWSElement.__init__(self, config, pos, _name, **kwargs) diff --git a/pyvo/io/vosi/endpoint.py b/pyvo/io/vosi/endpoint.py index 4d8714643..a26a0e813 100644 --- a/pyvo/io/vosi/endpoint.py +++ b/pyvo/io/vosi/endpoint.py @@ -49,7 +49,7 @@ def parse_tables(source, pedantic=None, filename=None, _debug_python_based_parser=False): """ Parses a tableset xml file (or file-like object), and returns a - `~pyvo.io.vosi.endpoint.TablesetFile` object. + `~pyvo.io.vosi.endpoint.TablesFile` object. Parameters ---------- @@ -70,7 +70,7 @@ def parse_tables(source, pedantic=None, filename=None, Returns ------- - tables_file : `~pyvo.io.vosi.endpoint.TableSetFile` object + tables_file : `~pyvo.io.vosi.endpoint.TablesFile` object See also -------- diff --git a/pyvo/io/vosi/vodataservice.py b/pyvo/io/vosi/vodataservice.py index 68bc107f8..15c3b61a8 100644 --- a/pyvo/io/vosi/vodataservice.py +++ b/pyvo/io/vosi/vodataservice.py @@ -8,10 +8,10 @@ * Elements with simple content and attributes * Elements with simple content without attributes -Elements with complex content are parsed with objects inherited from `Element`. +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 `Element` -defining a `value` property. +Elements with simple content are parsed with objects inherited from `~pyvo.utils.xml.elements.Element` +defining a ``value`` property. """ import re diff --git a/pyvo/io/vosi/voresource.py b/pyvo/io/vosi/voresource.py index 9e25b9c09..8299ab83d 100644 --- a/pyvo/io/vosi/voresource.py +++ b/pyvo/io/vosi/voresource.py @@ -8,10 +8,10 @@ * Elements with simple content and attributes * Elements with simple content without attributes -Elements with complex content are parsed with objects inherited from `Element`. +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 `Element` -defining a `value` property. +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 diff --git a/pyvo/registry/__init__.py b/pyvo/registry/__init__.py index 848fa1755..ae56eca88 100644 --- a/pyvo/registry/__init__.py +++ b/pyvo/registry/__init__.py @@ -5,14 +5,13 @@ The regtap module supports access to the IVOA Registries """ -from .regtap import (search, ivoid2service, get_RegTAP_query, - choose_RegTAP_service) +from .regtap import search, ivoid2service, get_RegTAP_query, choose_RegTAP_service from .rtcons import (Constraint, - Freetext, Author, Servicetype, Waveband, Datamodel, Ivoid, - UCD, Spatial, Spectral, Temporal) + Freetext, Author, Servicetype, Waveband, Datamodel, Ivoid, + UCD, Spatial, Spectral, Temporal, RegTAPFeatureMissing) -__all__ = ["search", "get_RegTAP_query", "Freetext", "Author", - "Servicetype", "Waveband", "Datamodel", "Ivoid", "UCD", - "Spatial", "Spectral", "Temporal", - "choose_RegTAP_service"] +__all__ = ["search", "get_RegTAP_query", "Constraint", "Freetext", "Author", + "Servicetype", "Waveband", "Datamodel", "Ivoid", "UCD", + "Spatial", "Spectral", "Temporal", + "choose_RegTAP_service", "RegTAPFeatureMissing"] diff --git a/pyvo/registry/regtap.py b/pyvo/registry/regtap.py index 2d06b4c7e..1472d5bad 100644 --- a/pyvo/registry/regtap.py +++ b/pyvo/registry/regtap.py @@ -170,7 +170,7 @@ def search(*constraints: rtcons.Constraint, The function accepts query constraints either as Constraint objects passed in as positional arguments or as their associated keywords. - For what constraints are available, see ref:`registry_basic_interface`. + For what constraints are available, see :ref:`registry-basic-interface`. The values of keyword arguments may be tuples or lists when the associated @@ -181,7 +181,7 @@ def search(*constraints: rtcons.Constraint, Parameters ---------- - *constraints : `rtcons.Constraint` instances + *constraints : `~pyvo.registry.Constraint` instances The constraints (keywords to match, positions to cover, ...) that the returned records need to satisfy. The accepted constraints are: @@ -228,18 +228,15 @@ def search(*constraints: rtcons.Constraint, are not reproducible. **kwargs : strings, mostly - shorthands for `constraints`; see the documentation of + shorthands for ``constraints``; see the documentation of a specific constraint for what keyword it uses and what literal it expects. Returns ------- - RegistryResults + ~pyvo.registry.regtap.RegistryResults` a container holding a table of matching resource (e.g. services) - See Also - -------- - RegistryResults """ service = get_RegTAP_service() query = RegistryQuery( @@ -570,9 +567,6 @@ def res_description(self): """ the textual description of the resource. - See Also - -------- - SimpleResource.describe """ return self.get("res_description", decode=True) diff --git a/pyvo/registry/rtcons.py b/pyvo/registry/rtcons.py index 6aa59c52d..166dbf792 100644 --- a/pyvo/registry/rtcons.py +++ b/pyvo/registry/rtcons.py @@ -22,9 +22,8 @@ from .import regtap -__all__ = ["Freetext", "Author", "Servicetype", "Waveband", - "Datamodel", "Ivoid", "UCD", "Spatial", "Spectral", "Temporal", - "Constraint", "build_regtap_query", "RegTAPFeatureMissing"] +# Classes from this module are exposed at the higher level namespace, not listing them here +__all__ = ["build_regtap_query"] # a mapping of service type shorthands to the ivoids of the @@ -180,7 +179,7 @@ def get_search_condition(self, service): Parameters ---------- - service : `dal.tap.TAPService` + service : `~pyvo.dal.TAPService` The RegTAP service the query is supposed to be run on (that is relevant because we adapt to the features available on given services). @@ -881,12 +880,12 @@ def build_regtap_query(constraints, service): Parameters ---------- - constraints : sequence of ``Constraint``-s + constraints : sequence of `~pyvo.registry.Constraint`-s A sequence of constraints for a RegTAP query. All of them will become part of a conjunction (i.e., all of them have to be satisfied for a record to match). - service : `~pyvo.dal.tap.TAPService` + service : `~pyvo.dal.TAPService` The RegTAP service the query is supposed to be run on (that is relevant because we adapt to the features available on given services).