PyVO

Common errors

• ModuleNotFoundError: No module named 'astropy'

  cause The core `astropy` library, a fundamental dependency for PyVO, is not installed in your environment.
  fix Install Astropy: `pip install astropy`.

• pyvo.exceptions.DALServiceError: HTTP Error 4xx: Client Error or HTTP Error 5xx: Server Error

  cause The remote Virtual Observatory service is inaccessible, unavailable, or returned an error for your request (e.g., invalid query, authentication issue, server-side problem).
  fix Check the specific HTTP error code for details. Verify the service URL, ensure your query is valid, and check the service's status if possible. Network connectivity issues can also cause this.

• TypeError: some_method() takes 1 positional argument but N were given

  cause You are passing optional arguments positionally to a PyVO function or method that now expects them as keyword arguments due to API changes in v1.6.
  fix Identify the method in question and change its call signature to use keyword arguments for all optional parameters. For example, change `method(param1, value_for_optional)` to `method(param1, optional_param=value_for_optional)`.

Warnings

• breaking Starting with PyVO v1.6, many optional arguments to functions and methods were changed to be keyword-only. This means calling them positionally will raise a `TypeError`.
  Fix: Review your code for positional arguments, especially for optional parameters, and explicitly pass them as keyword arguments (e.g., `func(arg1, arg2=value)` instead of `func(arg1, value)`).
• gotcha Asynchronous TAP job handling in versions prior to 1.8.1 might not correctly implement or respect timeout parameters for `run_async` methods, potentially leading to jobs hanging indefinitely.
  Fix: Upgrade to PyVO >= 1.8.1 to ensure proper timeout handling for asynchronous TAP jobs. If upgrading is not possible, implement external timeout mechanisms or carefully monitor job status.
• gotcha Error handling for HTTP 429 (Too Many Requests) responses was improved in v1.8.1 with the introduction of `DALRateLimitError`. Older versions might raise generic HTTP errors without explicit retry information.
  Fix: Upgrade to PyVO >= 1.8.1 to leverage `DALRateLimitError` for more robust handling of rate limits, including automatic retry logic where available. For older versions, implement custom retry logic for HTTP 429 errors.

Install

• pip install pyvo Install PyVO

Imports

• pyvo

  import pyvo

• TAPService
  wrong:

  from pyvo.services import TAPService

  correct:

  from pyvo.dal import TAPService

  Services were moved to the `pyvo.dal` submodule in earlier versions (pre-1.0) and this old path may persist in older examples.
• registry
  wrong:

  from pyvo import registry

  correct:

  import pyvo.registry

  While `from pyvo import registry` works, `import pyvo.registry` is more explicit and common in examples for sub-modules.

Quickstart

This quickstart demonstrates how to search the Virtual Observatory registry for services and then execute a simple ADQL query against a public TAP (Table Access Protocol) service using PyVO. Results are returned as Astropy Table objects, integrating well with the broader Astropy ecosystem.

import pyvo
import os

# 1. Search the VO registry for services
# Example: Find services related to galaxies and spectroscopy
print("Searching the VO registry...")
results = pyvo.registry.search(keywords=['galaxy', 'spectroscopy'])
print(f"Found {len(results)} services matching 'galaxy' and 'spectroscopy'.")

# 2. Access a TAP service (Table Access Protocol)
# For a stable quickstart, we'll use a widely known public TAP service.
# Note: Service availability can change. This is an example.
tap_service_url = os.environ.get('PYVO_TAP_SERVICE_URL', 'https://tap.voservices.net/tap')
tap_service = pyvo.dal.TAPService(tap_service_url)
print(f"\nAttempting to connect to TAP service: {tap_service.url}")

# 3. Execute an ADQL (Astronomical Data Query Language) query
# Example: Query the ivoa.ObsCore table for Gaia data
query = "SELECT TOP 5 ra, dec, dataproduct_type FROM ivoa.ObsCore WHERE obs_collection LIKE '%Gaia%'"
try:
    tap_results = tap_service.search(query)
    print(f"\nTAP query returned {len(tap_results)} results.")
    # Results are returned as an Astropy Table object (pyvo.dal.TableSet)
    print("\nFirst 5 results (Astropy Table):")
    print(tap_results.to_table())
except Exception as e:
    print(f"\nError during TAP query: {e}")
    print("The TAP service might be temporarily unavailable or the query invalid.")