### Install PyVO with all optional dependencies

Source: https://github.com/astropy/pyvo/blob/main/README.rst

Install PyVO from source, including all optional dependencies for full functionality.

```bash
pip install .[all]
```

--------------------------------

### Install PyVO using pip

Source: https://github.com/astropy/pyvo/blob/main/README.rst

Install PyVO and its prerequisites using pip. This is the recommended method for most users.

```bash
pip install pyvo
```

--------------------------------

### Install PyVO from Source

Source: https://github.com/astropy/pyvo/blob/main/docs/index.rst

Clone the PyVO repository and install it locally. This is useful for developers or users who need the latest unreleased version.

```bash
git clone http://github.com/astropy/pyvo
cd pyvo
python setup.py install
```

--------------------------------

### Access TAPService Query Examples

Source: https://github.com/astropy/pyvo/blob/main/docs/dal/index.rst

Retrieves example queries available from a TAPService. This is helpful for understanding how to construct more complex ADQL queries for specific datasets.

```python
print(tap_service.examples[1]['QUERY'])
```

--------------------------------

### ImageDiscoverer Example

Source: https://github.com/astropy/pyvo/blob/main/docs/discover/index.rst

A complete example demonstrating the use of ImageDiscoverer to find image services within a specified space and time range, then querying services and printing logs and results.

```python
from pyvo import discover, registry
from astropy.time import Time

im_discoverer = discover.image.ImageDiscoverer(
  space=(274.6880, -13.7920, 0.1),
  time=(Time('1996-10-04'), Time('1996-10-10')))
im_discoverer.set_services(
  registry.search(keywords=["heasarc rass"]))
im_discoverer.query_services()
print(im_discoverer.log_messages)
print(im_discoverer.results)
```

--------------------------------

### Install PyVO for testing

Source: https://github.com/astropy/pyvo/blob/main/README.rst

Install PyVO with testing infrastructure packages. This command installs pytest-astropy and requests-mock.

```bash
pip install .[test]
```

--------------------------------

### Install and Run MIVOT Validator

Source: https://github.com/astropy/pyvo/blob/main/docs/mivot/writer.rst

Installs the mivot-validator package and runs the instance validation command against a VOTable file. Successful validation results in no error messages.

```shell
% pip install mivot-validator
% mivot-instance-validate pyvo-tuto.xml
...
Valid if no error message
...
```

--------------------------------

### Set Services with Keywords

Source: https://github.com/astropy/pyvo/blob/main/docs/discover/index.rst

Set the services for a discoverer using registry.search with keywords. This example uses 'heasarc rass' as keywords.

```python
im_discoverer.set_services(
  registry.search(keywords=["heasarc rass"]))

```

--------------------------------

### Run TAP Query

Source: https://github.com/astropy/pyvo/blob/main/docs/registry/index.rst

Execute a TAP query against a specific service associated with a resource. This example demonstrates querying for astronomical objects based on redshift and magnitude.

```python
>>> resources["J/ApJ/727/14"].get_service(service_type="tap#aux").run_sync(
...   'SELECT id, z FROM "J/ApJ/727/14/table2" WHERE z>0.09 and umag<18')
<DALResultsTable length=1>
        ID            z
      object       float64
  ------------------ -------
  171319.90+635428.0 0.09043
```

--------------------------------

### Access Dataset URLs and Objects

Source: https://github.com/astropy/pyvo/blob/main/docs/dal/index.rst

Retrieve the URL for associated datasets or get a file-like object for the dataset. This example is currently skipped due to a known issue.

```python
>>> row.getdataurl()
'http://dc.g-vo.org/getproduct/califa/datadr3/V500/NGC0551.V500.rscube.fits'
>>> type(row.getdataset())
<class 'urllib3.response.HTTPResponse'>
```

--------------------------------

### Upload to PyPI

Source: https://github.com/astropy/pyvo/blob/main/RELEASE.rst

Uploads the generated source distribution to the Python Package Index (PyPI). Ensure you have twine installed.

```bash
twine upload sdist/*
```

--------------------------------

### Install developer version of PyVO

Source: https://github.com/astropy/pyvo/blob/main/README.rst

Install the developer version of PyVO directly from GitHub for testing purposes. This is useful for dependent libraries and notebook providers.

```bash
pip install git+https://github.com/astropy/pyvo.git#egg=pyvo
```

--------------------------------

### Run Asynchronous TAP Job

Source: https://github.com/astropy/pyvo/blob/main/docs/dal/index.rst

Start an asynchronous TAP job that was previously submitted and configured. This action moves the job to the 'QUEUED' state.

```python
job.run()
```

--------------------------------

### Search with Keywords

Source: https://github.com/astropy/pyvo/blob/main/docs/discover/index.rst

Use registry.search with keywords to find services, for example, those related to 'heasarc rass'.

```python
registry.search(keywords=["heasarc rass"])
```

--------------------------------

### Instantiate MivotViewer from Search Results

Source: https://github.com/astropy/pyvo/blob/main/docs/mivot/viewer.rst

Instantiates a MivotViewer from the results of a search query. Ensure astropy 6+ is installed. The viewer can resolve references if `resolve_ref` is set to True.

```python
import astropy.units as u
from astropy.io.votable import parse
from astropy.coordinates import SkyCoord
from pyvo.dal.scs import SCSService
from pyvo.utils.prototype import activate_features
from pyvo.mivot.viewer.mivot_viewer import MivotViewer

scs_srv = SCSService("https://vizier.cds.unistra.fr/viz-bin/conesearch/V1.5/I/311/hip2")
m_viewer = MivotViewer(
    scs_srv.search(
        pos=SkyCoord(ra=52.26708 * u.degree, dec=59.94027 * u.degree,
                     frame='icrs'),
        radius=0.1
        ),
    resolve_ref=True
)
```

--------------------------------

### Construct Service from Interface

Source: https://github.com/astropy/pyvo/blob/main/docs/registry/index.rst

Create a service object directly from an interface object. This is a convenient way to get a usable service instance.

```python
>>> voresource.list_interfaces()[0].to_service()
TAPService(baseurl : 'https://tapvizier.cds.unistra.fr/TAPVizieR/tap', description : '')
```

--------------------------------

### Retrieving Tables from a Resource

Source: https://github.com/astropy/pyvo/blob/main/docs/registry/index.rst

Explains how to get a list of tables associated with a registry resource, particularly for TAP services.

```APIDOC
## Retrieving Tables from a Resource

### Description
This method allows you to retrieve metadata about tables available within a registry resource, which is useful for TAP services.

### Method
`get_tables()`

### Parameters
None

### Request Example
```python
# Assuming 'resources' is a dictionary of registry resources
tables = resources["J/ApJ/727/14"].get_tables() 
print(list(tables.keys()))
```

### Response Example
```
['J/ApJ/727/14/table2']
```
```

--------------------------------

### Example UWS Job XML Document

Source: https://github.com/astropy/pyvo/blob/main/docs/io/uws.rst

This is a sample XML document representing a UWS job. It includes details such as job ID, phase, timestamps, parameters, and results.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<job xmlns:uws="http://www.ivoa.net/xml/UWS/v1.0" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1">
  <jobId>async-query-12345</jobId>
  <runId>query-run-id</runId>
  <ownerId>user-1</ownerId>
  <phase>COMPLETED</phase>
  <quote>2025-06-19T14:35:00.000Z</quote>
  <creationTime>2025-06-19T14:30:00.000Z</creationTime>
  <startTime>2025-06-19T14:30:05.123Z</startTime>
  <endTime>2025-06-19T14:32:18.456Z</endTime>
  <executionDuration>600</executionDuration>
  <destruction>2025-06-26T14:30:00.000Z</destruction>

  <parameters>
    <parameter id="LANG">ADQL</parameter>
    <parameter id="QUERY">SELECT obj_id, ra, dec, magnitude FROM catalog.objects WHERE 1=CONTAINS(POINT('ICRS', ra, dec), CIRCLE('ICRS', 180.0, 45.0, 1.0))</parameter>
    <parameter id="FORMAT">votable</parameter>
    <parameter id="MAXREC">10000</parameter>
  </parameters>

  <results>
    <result id="result"
            xlink:href="http://example.com/tap/async/async-query-12345/results/result"/>
  </results>

  <jobInfo>
    <rowsReturned>1234</rowsReturned>
    <executionTime>133.333</executionTime>
    <cpuTime>98.765</cpuTime>
    <queuePosition>0</queuePosition>
    <estimatedDuration>120</estimatedDuration>
    <nodeId>compute-node-03</nodeId>
    <serviceVersion>1.1</serviceVersion>
  </jobInfo>
</job>
```

--------------------------------

### Run and Monitor Asynchronous TAP Job

Source: https://github.com/astropy/pyvo/blob/main/docs/dal/index.rst

After submitting a job, use the `run()` method to start its execution. The `phase` attribute can be used to check the job's current status. Requires the job object obtained from `submit_job`.

```python
>>> job.run()  # doctest: +IGNORE_OUTPUT
```

```python
>>> print(job.phase)  # doctest: +IGNORE_OUTPUT
```

--------------------------------

### Get Tables from Resource

Source: https://github.com/astropy/pyvo/blob/main/docs/registry/index.rst

Retrieve a dictionary of tables associated with a specific registry resource. This is useful for understanding the data structure available within a resource.

```python
>>> tables = resources["J/ApJ/727/14"].get_tables()  # doctest: +IGNORE_WARNINGS
>>> list(tables.keys())
['J/ApJ/727/14/table2']
>>> sorted(c.name for c in tables["J/ApJ/727/14/table2"].columns)
['[24]', '[70]', 'dej2000', 'dr7', 'e_[24]', 'e_[70]', 'e_l15', 'e_l24', 'e_n3', 'e_n4', 'e_s11', 'e_s7', 'f_id', 'gmag', 'id', 'imag', 'l15', 'l24', 'n3', 'n4', 'raj2000', 'recno', 'rmag', 's11', 's7', 'sed', 'simbad', 'sloan', 'umag', 'y03', 'z', 'zmag']
```

--------------------------------

### Manage CADC Tables with Prototype Feature

Source: https://context7.com/astropy/pyvo/llms.txt

Demonstrates using the 'cadc-tb-upload' prototype feature to manage tables in the CADC archive, including creation, loading data, indexing, and removal. Requires authentication setup.

```python
from pyvo.utils.prototype import activate_features
activate_features("cadc-tb-upload")

import pyvo as vo
from io import StringIO

session = vo.auth.AuthSession()
session.credentials.set_client_certificate("/path/to/cert.pem")
tap = vo.dal.TAPService("https://ws-cadc.canfar.net/youcat", session=session)

table_def = '''<vosi:table xmlns:vosi="http://www.ivoa.net/xml/VOSITables/v1.0"
    xmlns:vod="http://www.ivoa.net/xml/VODataService/v1.1"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" type="output">
  <name>my_table</name>
  <column>
    <name>label</name>
    <dataType xsi:type="vod:VOTableType" arraysize="30*">char</dataType>
  </column>
</vosi:table>'''

tap.create_table(name="my_schema.my_table", definition=StringIO(table_def))
tap.load_table(name="my_schema.my_table",
               source=StringIO("label\nhello\nworld\n"), format="csv")
tap.create_index(table_name="my_schema.my_table", column_name="label", unique=False)
tap.remove_table(name="my_schema.my_table")
```

--------------------------------

### Query TAP Service and Get Field Names

Source: https://github.com/astropy/pyvo/blob/main/docs/dal/index.rst

Connect to a TAP service, execute a search query, and retrieve the names of the columns in the resultset. Ensure the TAPService URL is correct and the query is valid.

```python
>>> tap_service = vo.dal.TAPService("http://dc.g-vo.org/tap")
>>> resultset = tap_service.search("SELECT * FROM ivoa.obscore"\
... " WHERE obs_collection='CALIFA' AND"\
... " 1=CONTAINS(s_region, CIRCLE(23, 42, 5))"\
... " ORDER BY obs_publisher_did")
>>> print(resultset.fieldnames)
```

--------------------------------

### Perform Cone Search with Mivot Response

Source: https://github.com/astropy/pyvo/blob/main/docs/mivot/example.rst

This snippet shows how to configure and execute a Cone Search query to a Simbad server, requesting results in the Mivot format. Ensure you have astropy and pyvo installed.

```python
SERVER = "https://simbad.cds.unistra.fr/cone?"
VERB = 2
RA = 269.452076* u.degree
DEC = 4.6933649* u.degree
SR = 0.1* u.degree
MAXREC = 100
RESPONSEFORMAT = "mivot"

scs_srv = SCSService(SERVER)

query_result = scs_srv.search(
    pos=SkyCoord(ra=RA, dec=DEC, frame='icrs'),
    radius=SR,
    verbosity=VERB,
    RESPONSEFORMAT=RESPONSEFORMAT,
    MAXREC=MAXREC)

```

--------------------------------

### Direct Gateway to Astropy SkyCoord with MivotViewer

Source: https://github.com/astropy/pyvo/blob/main/docs/mivot/viewer.rst

Use Mivot annotations to directly build Astropy SkyCoord objects. This example iterates through rows, builds a SkyCoord for each, and prints it. An error is raised if the mapped model cannot be used as a SkyCoord precursor.

```python
from pyvo.mivot.features.sky_coord_builder import SkyCoordBuilder

m_viewer.rewind()
while m_viewer.next_row_view():
    sky_coord_builder = SkyCoordBuilder(mivot_instance)
    sky_coord = sky_coord_builder.build_sky_coord()
    print(sky_coord)
```

--------------------------------

### Search Registry with Keyword Arguments

Source: https://github.com/astropy/pyvo/blob/main/docs/registry/index.rst

Shows how to search the registry using keyword arguments for waveband and author, which is a more concise syntax.

```python
>>> resources = registry.search(waveband=["Radio", "Millimeter"],
...   author='%Miller%')
```

--------------------------------

### Service Discovery for Specific Waveband and Service Type

Source: https://github.com/astropy/pyvo/blob/main/docs/registry/index.rst

Perform a registry search for resources matching specific criteria (e.g., 'infrared' waveband and 'ssap' service type) and then query each found service. This demonstrates a basic pattern for all-VO queries.

```python
>>> from astropy.coordinates import SkyCoord
>>> my_obj = SkyCoord.from_name("Bellatrix")
>>> for res in registry.search(waveband="infrared", servicetype="ssap"):
...     print(res.service.search(pos=my_obj, size=0.001))
...
```

--------------------------------

### Listing and Inspecting Interfaces

Source: https://github.com/astropy/pyvo/blob/main/docs/registry/index.rst

Demonstrates how to list available interfaces for a registry resource and inspect their details.

```APIDOC
## Listing and Inspecting Interfaces

### Description
This section shows how to list all available interfaces for a given registry resource and how to filter them by service type.

### Method
`list_interfaces()`

### Parameters
- `service_type` (str, optional): Filter interfaces by their type (e.g., 'tap', 'conesearch').

### Request Example
```python
# List all interfaces for a resource
for interface in voresource.list_interfaces():
    print(interface)

# List only TAP interfaces
voresource.list_interfaces("tap")
```

### Response Example
```
Interface(type='tap#aux', description='', url='https://tapvizier.cds.unistra.fr/TAPVizieR/tap')
Interface(type='vr:webbrowser', description='', url='https://vizier.cds.unistra.fr/viz-bin/VizieR-2?-source=J/ApJ/727/14')
Interface(type='conesearch', description='Cone search capability for table J/ApJ/727/14/table2 (AKARI IRC 3-24{mu}m, and Spitzer MIPS 24/70{mu}m photometry of Abell 2255 member galaxies)', url='https://vizier.cds.unistra.fr/viz-bin/conesearch/J/ApJ/727/14/table2?')
```
```

--------------------------------

### Search with Keywords and Expand Down

Source: https://github.com/astropy/pyvo/blob/main/docs/discover/index.rst

Use registry.search with keywords and expand_down to find services related to galaxies. The discoverer will discard services it cannot handle.

```python
registry.search(registry.UAT("galaxies", expand_down=3))
```

--------------------------------

### Get Total Number of Rows

Source: https://github.com/astropy/pyvo/blob/main/docs/dal/index.rst

Obtain the total number of rows in the resultset using the built-in len() function.

```python
>>> print(len(resultset))
```

--------------------------------

### Running a TAP Query

Source: https://github.com/astropy/pyvo/blob/main/docs/registry/index.rst

Demonstrates how to execute a TAP query against a specific table within a registry resource.

```APIDOC
## Running a TAP Query

### Description
This shows how to obtain a TAP service for a resource and execute a synchronous query against a specific table.

### Method
`get_service(service_type='tap#aux').run_sync()`

### Parameters
- `query` (str): The SQL-like query string to execute.

### Request Example
```python
# Assuming 'resources' is a dictionary of registry resources
query_result = resources["J/ApJ/727/14"].get_service(service_type="tap#aux").run_sync(
  'SELECT id, z FROM "J/ApJ/727/14/table2" WHERE z>0.09 and umag<18')
print(query_result)
```

### Response Example
```
<DALResultsTable length=1>
        ID            z
      object       float64
------------------ -------
171319.90+635428.0 0.09043
```
```

--------------------------------

### Create Release Tag

Source: https://github.com/astropy/pyvo/blob/main/RELEASE.rst

Creates an annotated Git tag for the new release. Replace 'version' with the actual version number.

```bash
git tag -a version -m "releasing new version version"
```

--------------------------------

### UWS Job Document Structure

Source: https://github.com/astropy/pyvo/blob/main/docs/io/uws.rst

This section provides an example of a UWS job XML document, illustrating the structure and common fields.

```APIDOC
## UWS Job Document Example

### Description
This is a sample XML document representing a UWS job. It includes details such as job ID, phase, creation time, parameters, and results.

### Document Structure

- **jobId**: Unique identifier for the job.
- **runId**: Identifier for a specific run of the job.
- **ownerId**: Identifier of the user who owns the job.
- **phase**: Current status of the job (e.g., COMPLETED, PENDING, RUNNING, ERROR).
- **quote**: Timestamp indicating when the job is scheduled for destruction.
- **creationTime**: Timestamp when the job was created.
- **startTime**: Timestamp when the job execution began.
- **endTime**: Timestamp when the job execution finished.
- **executionDuration**: The total time in seconds the job took to execute.
- **destruction**: Timestamp indicating when the job will be destroyed.

#### Parameters
- **parameter**: Represents a job parameter.
  - **id**: The name of the parameter.
  - **content**: The value of the parameter.

#### Results
- **result**: Represents a job result.
  - **id**: The identifier for the result.
  - **xlink:href**: A URL pointing to the location of the result.

#### Job Info
- **jobInfo**: Contains additional information about the job's execution.
  - **rowsReturned**: Number of rows returned by the job.
  - **executionTime**: Actual execution time in seconds.
  - **cpuTime**: CPU time consumed by the job in seconds.
  - **queuePosition**: The job's position in the execution queue.
  - **estimatedDuration**: Estimated time in seconds for job completion.
  - **nodeId**: The identifier of the compute node where the job ran.
  - **serviceVersion**: The version of the UWS service.

### Example XML Document
```xml
<?xml version="1.0" encoding="UTF-8"?>
<job xmlns:uws="http://www.ivoa.net/xml/UWS/v1.0" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1">
  <jobId>async-query-12345</jobId>
  <runId>query-run-id</runId>
  <ownerId>user-1</ownerId>
  <phase>COMPLETED</phase>
  <quote>2025-06-19T14:35:00.000Z</quote>
  <creationTime>2025-06-19T14:30:00.000Z</creationTime>
  <startTime>2025-06-19T14:30:05.123Z</startTime>
  <endTime>2025-06-19T14:32:18.456Z</endTime>
  <executionDuration>600</executionDuration>
  <destruction>2025-06-26T14:30:00.000Z</destruction>

  <parameters>
    <parameter id="LANG">ADQL</parameter>
    <parameter id="QUERY">SELECT obj_id, ra, dec, magnitude FROM catalog.objects WHERE 1=CONTAINS(POINT('ICRS', ra, dec), CIRCLE('ICRS', 180.0, 45.0, 1.0))</parameter>
    <parameter id="FORMAT">votable</parameter>
    <parameter id="MAXREC">10000</parameter>
  </parameters>

  <results>
    <result id="result"
            xlink:href="http://example.com/tap/async/async-query-12345/results/result"/>
  </results>

  <jobInfo>
    <rowsReturned>1234</rowsReturned>
    <executionTime>133.333</executionTime>
    <cpuTime>98.765</cpuTime>
    <queuePosition>0</queuePosition>
    <estimatedDuration>120</estimatedDuration>
    <nodeId>compute-node-03</nodeId>
    <serviceVersion>1.1</serviceVersion>
  </jobInfo>
</job>
```
```

--------------------------------

### Set pyVO User Agent for Bulk Downloads

Source: https://github.com/astropy/pyvo/blob/main/docs/utils/index.rst

Code performing bulk downloads for mirroring or archiving should use this setting. Requires importing `setup_user_agent` from `pyvo.utils.http`.

```python
setup_user_agent(purpose="copy")
```

--------------------------------

### Create and Execute a Query Object

Source: https://github.com/astropy/pyvo/blob/main/docs/registry/index.rst

Demonstrates creating a query object from a DAL service and then setting its parameters to execute a search. This is an alternative to calling the search function directly on the service object.

```python
>>> cutouts1 = nvss.search(pos=(148.8888, 69.065), size=0.2)
>>> nvssq = nvss.create_query(size=0.2)  # or create a query object
>>> nvssq.pos = (350.85, 58.815)
>>> cutouts2 = nvssq.execute()
```

--------------------------------

### Get TAP Service Hard Limit

Source: https://github.com/astropy/pyvo/blob/main/docs/dal/index.rst

Retrieve the hard limit for maximum records that a TAP service will allow. This limit cannot be overridden by the user.

```python
print(tap_service.hardlimit)
```

--------------------------------

### Search registry using explicit constraints

Source: https://github.com/astropy/pyvo/blob/main/docs/registry/index.rst

Find resources matching "white dwarf" and "UV" waveband using explicit Freetext and Waveband constraints.

```python
resources = registry.search(registry.Freetext("white dwarf"),
                            registry.Waveband("UV"))
```

--------------------------------

### Pack MIVOT Block

Source: https://github.com/astropy/pyvo/blob/main/docs/mivot/writer.rst

Packages the previously built MIVOT model instances. The build_mivot_block method includes a syntax validation if the 'xmlvalidator' package is installed.

```python
mivot_annotations.add_templates(position)
mivot_annotations.build_mivot_block()
```

--------------------------------

### Retrieve and List Interfaces from a Resource

Source: https://context7.com/astropy/pyvo/llms.txt

Fetches tables associated with a registry resource and lists its available interfaces. Shows how to convert a TAP interface to a service object.

```python
tables = nvss.get_tables()

for iface in nvss.list_interfaces():
    print(iface)
tap_svc = nvss.list_interfaces("tap")[0].to_service()
```

--------------------------------

### Constructing a Service from an Interface

Source: https://github.com/astropy/pyvo/blob/main/docs/registry/index.rst

Shows how to create a service object directly from an interface object.

```APIDOC
## Constructing a Service from an Interface

### Description
This demonstrates how to convert an `Interface` object into a usable service object.

### Method
`to_service()`

### Request Example
```python
# Assuming 'interface' is an Interface object obtained from list_interfaces()
service = interface.to_service()
print(service)
```

### Response Example
```
TAPService(baseurl : 'https://tapvizier.cds.unistra.fr/TAPVizieR/tap', description : '')
```
```

--------------------------------

### Perform Simple Cone Search (SCS)

Source: https://github.com/astropy/pyvo/blob/main/docs/dal/index.rst

Initialize an `SCSService` with a service URL and use its `search` method to find catalog entries within a specified sky position and radius. Requires `pos` and `radius` parameters.

```python
>>> scs_srv = vo.dal.SCSService('http://dc.g-vo.org/arihip/q/cone/scs.xml')
>>> scs_results = scs_srv.search(pos=pos, radius=size)
```

--------------------------------

### Accessing Web Browser Service

Source: https://github.com/astropy/pyvo/blob/main/docs/registry/index.rst

Illustrates how to access a 'web' service associated with a resource, which typically opens a browser window for interaction.

```APIDOC
## Accessing Web Browser Service

### Description
This method retrieves a service of type 'web' which, when its `search` method is called, opens a web browser to a specific query interface.

### Method
`get_service(service_type='web').search()`

### Parameters
None for `get_service`. The `search` method may accept parameters depending on the specific web service.

### Request Example
```python
# Assuming 'resources' is a dictionary of registry resources
resources["J/ApJ/727/14"].get_service(service_type="web").search()
```

### Response Example
(Opens a web browser window. No direct console output.)
```

--------------------------------

### Handling Job Errors

Source: https://github.com/astropy/pyvo/blob/main/docs/io/uws.rst

Provides an example of how to check the status of a job and specifically handle cases where the job phase is 'ERROR', accessing the error summary message.

```python
# Example of handling a job with errors
def check_job_status(job_file):
    job = parse_job(job_file)

    if job.phase == 'ERROR':
```

--------------------------------

### Initialize MIVOT Annotations and Models

Source: https://github.com/astropy/pyvo/blob/main/docs/mivot/writer.rst

Activate the MIVOT feature and set up the MivotAnnotations object by adding necessary data models. This includes defining the models used and setting up reporting for the annotation process.

```python
from astropy.io.votable import parse
from pyvo.utils import activate_features
from pyvo.mivot.utils.exceptions import MappingException
from pyvo.mivot.utils.dict_utils import DictUtils
from pyvo.mivot.writer.annotations import MivotAnnotations
from pyvo.mivot.writer.instance import MivotInstance
from pyvo.mivot.viewer.mivot_viewer import MivotViewer

activate_features("MIVOT")

mivot_annotations = MivotAnnotations()
mivot_annotations.add_model(
    "ivoa", "https://www.ivoa.net/xml/VODML/IVOA-v1.vo-dml.xml"
)
mivot_annotations.add_model(
    "coords", "https://www.ivoa.net/xml/STC/20200908/Coords-v1.0.vo-dml.xml"
)
mivot_annotations.add_model(
    "mango",
    "https://raw.githubusercontent.com/lmichel/MANGO/draft-0.1/vo-dml/mango.vo-dml.xml",
)
mivot_annotations.set_report(True, "PyVO Tuto")
```

--------------------------------

### Raw Requests Passthrough with Session

Source: https://context7.com/astropy/pyvo/llms.txt

Demonstrates making a raw HTTP GET request using an authenticated `AuthSession`, allowing direct interaction with service endpoints.

```python
response = session.get("https://ws-cadc.canfar.net/youcat/availability")
```

--------------------------------

### Get Data URL from SSA Results

Source: https://github.com/astropy/pyvo/blob/main/docs/dal/index.rst

Retrieves the URL for accessing the spectral data from an SSA search result. Assumes at least one result is available.

```python
ssa_results[0].getdataurl()
```

--------------------------------

### Get Current RegTAP Service URL

Source: https://github.com/astropy/pyvo/blob/main/docs/registry/index.rst

Retrieves the URL of the RegTAP service that pyVO is currently configured to use. This is helpful for verifying the active registry endpoint.

```python
>>> from pyvo import registry
>>> registry.get_RegTAP_service_url()
'http://reg.g-vo.org/tap'
```

--------------------------------

### Search Registry by Waveband and Author

Source: https://github.com/astropy/pyvo/blob/main/docs/registry/index.rst

Demonstrates searching the registry using explicit filter objects for waveband and author. This is an alternative to keyword arguments.

```python
>>> resources = registry.search(registry.Waveband("Radio", "Millimeter"),
...   registry.Author("%Miller%"))
```

--------------------------------

### Describe registry resource with verbose output

Source: https://github.com/astropy/pyvo/blob/main/docs/registry/index.rst

Prints a detailed description of a registry resource, including its short name, IVOA identifier, and access modes, when verbose is set to True.

```python
nvss.describe(verbose=True)
```

--------------------------------

### List Available Interfaces

Source: https://github.com/astropy/pyvo/blob/main/docs/registry/index.rst

Iterate through and print all available interfaces for a given resource. Useful for understanding the types of services offered by a provider.

```python
>>> for interface in voresource.list_interfaces():
...     print(interface)
Interface(type='tap#aux', description='', url='https://tapvizier.cds.unistra.fr/TAPVizieR/tap')
Interface(type='vr:webbrowser', description='', url='https://vizier.cds.unistra.fr/viz-bin/VizieR-2?-source=J/ApJ/727/14')
Interface(type='conesearch', description='Cone search capability for table J/ApJ/727/14/table2 (AKARI IRC 3-24{mu}m, and Spitzer MIPS 24/70{mu}m photometry of Abell 2255 member galaxies)', url='https://vizier.cds.unistra.fr/viz-bin/conesearch/J/ApJ/727/14/table2?')
```

--------------------------------

### Get Default Max Records from TAP Service

Source: https://github.com/astropy/pyvo/blob/main/docs/dal/index.rst

Retrieve the default maximum number of records a TAP service will return before overflowing. This is a sanity precaution set by the service.

```python
print(tap_service.maxrec)
```

--------------------------------

### Initialize MivotViewer and Perform Cone Search

Source: https://github.com/astropy/pyvo/blob/main/docs/mivot/example.rst

This code initializes the MIVOT-specific features in pyvo, sets up a cone search service, and performs a search query. The MivotViewer is then initialized with the query results to process MIVOT annotations.

```python
import astropy.units as u
from astropy.coordinates import SkyCoord
from pyvo.dal.scs import SCSService
from pyvo.utils import activate_features
from pyvo.mivot.viewer.mivot_viewer import MivotViewer
from pyvo.mivot.features.sky_coord_builder import SkyCoordBuilder

# Enable MIVOT-specific features in the pyvo library
activate_features("MIVOT")

scs_srv = SCSService("https://vizier.cds.unistra.fr/viz-bin/conesearch/V1.5/I/239/hip_main")

query_result = scs_srv.search(
    pos=SkyCoord(ra=52.26708 * u.degree, dec=59.94027 * u.degree, frame='icrs'),
    radius=0.5)
```

```python
# The MIVOT viewer generates the model view of the data
m_viewer = MivotViewer(query_result, resolve_ref=True)
```

--------------------------------

### Extract Frames for EpochPosition

Source: https://github.com/astropy/pyvo/blob/main/docs/mivot/annoter.rst

Automatically extracts space and time frames from COOSYS and TIMSYS VOTable elements for use in add_epoch_position. The frames can be dmid-s or mapping elements needed for installation.

```python
frame_mapping = builder.extract_frames()
builder.add_epoch_position(frame_mapping, mapping, semantics)
```

--------------------------------

### Push Release Tag

Source: https://github.com/astropy/pyvo/blob/main/RELEASE.rst

Pushes the newly created release tag to the origin repository.

```bash
git push origin version
```

--------------------------------

### Get Contact Information for a Service

Source: https://github.com/astropy/pyvo/blob/main/docs/registry/index.rst

Retrieves contact information, typically an email address and phone number, for a given registry resource. This is useful for reporting issues or seeking support.

```python
>>> res.get_contact()
'GAVO Data Centre Team (+49 6221 54 1837) <gavo@ari.uni-heidelberg.de>'
```

--------------------------------

### Get Metadata for a Specific Field

Source: https://github.com/astropy/pyvo/blob/main/docs/dal/index.rst

Retrieve rich metadata, such as UCD, for a specific field in the resultset using its name. This is useful for understanding the physical meaning or data model annotation of a column.

```python
>>> print(resultset.getdesc('s_fov').ucd)
```

--------------------------------

### Client Certificate Authentication

Source: https://context7.com/astropy/pyvo/llms.txt

Sets up an `AuthSession` for client certificate authentication (X.509) and uses it to establish a TAP service connection. Requires a valid certificate file path.

```python
import pyvo as vo


session = vo.auth.AuthSession()
session.credentials.set_client_certificate("/path/to/cert.pem")

tap = vo.dal.TAPService("https://ws-cadc.canfar.net/youcat", session=session)
results = tap.search("SELECT TOP 5 * FROM my_schema.my_table")
```

--------------------------------

### Access and Modify TAP Job Execution Duration

Source: https://github.com/astropy/pyvo/blob/main/docs/dal/index.rst

The `execution_duration` attribute of a TAP job can be accessed to get the maximum run time in seconds and modified to change it. The default is 7200 seconds.

```python
>>> print(job.execution_duration)
7200.0
>>> job.execution_duration = 3600
```

--------------------------------

### Create Source Distribution

Source: https://github.com/astropy/pyvo/blob/main/RELEASE.rst

Generates a source tarball of the package. This is typically done before uploading to PyPI.

```bash
python setup.py sdist
```

--------------------------------

### Submit Asynchronous TAP Query

Source: https://github.com/astropy/pyvo/blob/main/docs/dal/index.rst

Submit an asynchronous TAP query and get a job object. The job can be configured and run later. Use when you need to manage the query lifecycle explicitly.

```python
job = tap_service.submit_job(ex_query)
```

--------------------------------

### Extract Epoch Position Parameters

Source: https://github.com/astropy/pyvo/blob/main/docs/mivot/annoter_tips.rst

Use `extract_epoch_position_parameters` to get a template of mapping parameters for the EpochPosition class based on the VOTable FIELD UCDs. This is useful when the VOTable fields are available during annotation.

```python
scs_srv = SCSService(" https://vizier.cds.unistra.fr/viz-bin/conesearch/V1.5/I/239/hip_main")

    query_result = scs_srv.search(
        pos=SkyCoord(ra=52.26708 * u.degree, dec=59.94027 * u.degree, frame='icrs'),
        radius=0.5)

    builder = InstancesFromModels(query_result.votable, dmid="URAT1")
    
    # Get a mapping proposal based on the FIELD UCDs
    parameters = builder.extract_epoch_position_parameters()
    DictUtils.print_pretty_json(parameters)
```

--------------------------------

### Initializing the Annotation Builder

Source: https://github.com/astropy/pyvo/blob/main/docs/mivot/annoter.rst

Create an Annotation Builder instance and connect it to the VOTable to be annotated. The optional `dmid` parameter specifies the identifier column for Mango objects.

```APIDOC
## Initialize Annotation Builder

### Description
Creates an `InstancesFromModels` object to build MIVOT annotations for a given VOTable.

### Method
`InstancesFromModels(votable, dmid=None)`

### Parameters
- **votable**: The VOTable object to annotate.
- **dmid** (string, optional): The column ID or name to be used as the identifier for Mango objects. Defaults to None.

### Request Example
```python
from pyvo.io.votable import parse
from pyvo.mivot.writer import InstancesFromModels

votable = parse("MY/VOTABLE")
builder = InstancesFromModels(votable, dmid="DR3Name")
```
```

--------------------------------

### Simple Spectral Access with SSAService

Source: https://context7.com/astropy/pyvo/llms.txt

Use SSAService for discovering and retrieving one-dimensional spectra via the SSAP protocol. Supports position, diameter, time, and wavelength band constraints.

```python
import pyvo as vo
from astropy.coordinates import SkyCoord
from astropy.units import Quantity
from astropy.time import Time

ssa = vo.dal.SSAService("http://archive.stsci.edu/ssap/search2.php?id=BEFS&")
pos      = SkyCoord.from_name("Eta Carina")
diameter = Quantity(0.5, unit="deg")

# Basic search
results = ssa.search(pos=pos, diameter=diameter)
print(results[0].getdataurl())
```

```python
# Add time and wavelength constraints
results2 = ssa.search(
    pos=pos,
    diameter=diameter,
    time=Time((53000, 54000), format="mjd"),
    band=Quantity((1e-13, 1e-12), unit="m")   # wavelength range in meters
)
for row in results2:
    print(row["ssa_targname"], row.getdataurl())
```

```python
# Column metadata access
desc = results.getdesc("ssa_specstart")
print(desc.ucd, desc.unit)
```

```python
# Convert to AstroPy Table
tbl = results.to_table()
```

--------------------------------

### Search registry by keywords and waveband

Source: https://github.com/astropy/pyvo/blob/main/docs/registry/index.rst

Find resources matching "white dwarf" and "UV" waveband using keyword and waveband arguments.

```python
resources = registry.search(keywords="white dwarf", waveband="UV")
```

--------------------------------

### Submit Asynchronous TAP Job

Source: https://github.com/astropy/pyvo/blob/main/docs/dal/index.rst

Use `TAPService` to submit a job for asynchronous execution. The `submit_job` method starts a server-side job and returns a job object. Requires a service URL and a query string.

```python
>>> async_srv = vo.dal.TAPService("http://dc.g-vo.org/tap")
>>> job = async_srv.submit_job("SELECT * FROM ivoa.obscore")
```

--------------------------------

### Set pyVO User Agent for Specific Client

Source: https://github.com/astropy/pyvo/blob/main/docs/utils/index.rst

Use this at the beginning of a program to mark pyVO requests as coming from a specific client. Requires importing `setup_user_agent` from `pyvo.utils.http`.

```python
from pyvo.utils.http import setup_user_agent
setup_user_agent(primary_component="clusterfinder")
```

--------------------------------

### Set pyVO User Agent for Validation/Testing

Source: https://github.com/astropy/pyvo/blob/main/docs/utils/index.rst

Code running for validation or testing should use this setting before making requests. Requires importing `setup_user_agent` from `pyvo.utils.http`.

```python
setup_user_agent(purpose="test")
```

--------------------------------

### Create TAP Table

Source: https://github.com/astropy/pyvo/blob/main/docs/dal/index.rst

Creates a new table in a TAP service using a provided definition. Ensure the TAPService object is initialized.

```python
tap_service.create_table(name='test_schema.test_table', definition=StringIO(table_definition))
```

--------------------------------

### Perform SSA Query with Time and Band Constraints

Source: https://github.com/astropy/pyvo/blob/main/docs/dal/index.rst

Use the `ssa_service.search` method to query for data, constraining results by time and frequency band. Requires `pos`, `diameter`, `time`, and `band` parameters.

```python
>>> ssa_results = ssa_service.search(
...     pos=pos,
...     diameter=size,
...     time=Time((53000, 54000), format='mjd'),
...     band=Quantity((1e-13, 1e-12), unit="m"))
```

--------------------------------

### Service Discovery for Specific Service Types

Source: https://github.com/astropy/pyvo/blob/main/docs/registry/index.rst

Shows how to perform a registry search constrained by a specific service type to find resources that offer that service.

```APIDOC
## Service Discovery for Specific Service Types

### Description
This demonstrates how to search the VO Registry for resources that provide a specific type of service (e.g., 'ssap') and then access the `service` attribute of each result for uniform querying.

### Method
`registry.search(servicetype='...')`

### Parameters
- `servicetype` (str): The type of service to search for (e.g., 'ssap', 'conesearch').
- Other search parameters like `waveband`, `pos`, `size` can also be used.

### Request Example
```python
from astropy.coordinates import SkyCoord

my_obj = SkyCoord.from_name("Bellatrix")
# Search for infrared SSAP services near Bellatrix
for res in registry.search(waveband="infrared", servicetype="ssap", pos=my_obj, size=0.001):
    # Access the service and perform a search
    print(res.service.search(pos=my_obj, size=0.001))
```

### Response Example
(Output will vary based on search results and service responses. Each `res.service.search()` call will return results from a specific service.)
```

--------------------------------

### Safe JobInfo Access Patterns

Source: https://github.com/astropy/pyvo/blob/main/docs/io/uws.rst

Illustrates safe ways to access jobInfo, including error handling for expected elements, using .get() with defaults for optional elements, checking for existence, and iterating through all elements.

```python
def safe_jobinfo_access(job):
    """Demonstrates safe jobInfo access patterns"""
    if not job.jobinfo:
        print("No jobInfo available")
        return

    # Pattern 1: Expected elements with error handling
    try:
        rows = job.jobinfo['rowsReturned']
        exec_time = job.jobinfo['executionTime']
        print(f"Processed {rows.value:,} rows in {exec_time.value:.1f} seconds")
    except KeyError as e:
        print(f"Required statistics missing: {e}")

    # Pattern 2: Optional elements with defaults
    queue_pos = job.jobinfo.get('queuePosition', 'unknown')
    priority = job.jobinfo.get('priority', 'normal')

    # Pattern 3: Check existence before accessing
    if 'nodeId' in job.jobinfo:
        node = job.jobinfo['nodeId']
        print(f"Executed on node: {node.text}")

    # Pattern 4: Iterate through all available elements
    print("All jobInfo elements:")
    for key in job.jobinfo.keys():
        element = job.jobinfo[key]
        print(f"  {key}: {element.text}")
```

--------------------------------

### Create TAP Table Definition

Source: https://github.com/astropy/pyvo/blob/main/docs/dal/index.rst

Defines a table structure for a TAP service. Requires StringIO for in-memory definition.

```python
from io import StringIO
table_definition = '''<vosi:table xmlns:vosi="http://www.ivoa.net/xml/VOSITables/v1.0" xmlns:vod="http://www.ivoa.net/xml/VODataService/v1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" type="output">
    <name>my_table</name>
    <description>This is my very own table</description>
    <column>
        <name>article</name>
        <description>some article</description>
        <dataType xsi:type="vod:VOTableType" arraysize="30*">char</dataType>
    </column>
    <column>
        <name>count</name>
        <description>how many</description>
        <dataType xsi:type="vod:VOTableType">long</dataType>
    </column>
</vosi:table>'''
```

--------------------------------

### Initialize Annotation Builder

Source: https://github.com/astropy/pyvo/blob/main/docs/mivot/annoter.rst

Create an Annotation Builder and connect it to the VOTable to be annotated. The optional 'dmid' parameter specifies the column to use as an identifier for Mango objects.

```python
votable = parse("MY/VOTABLE")
builder = InstancesFromModels(votable, dmid="DR3Name")
```

--------------------------------

### Username/Password Authentication

Source: https://context7.com/astropy/pyvo/llms.txt

Configures an `AuthSession` for HTTP Basic authentication using a username and password, then creates a TAP service instance with this session.

```python
session2 = vo.auth.AuthSession()
session2.credentials.set_password("myuser", "s3cret")
svc = vo.dal.TAPService("https://protected.example.org/tap", session=session2)
```

--------------------------------

### Inspect Resource Metadata

Source: https://context7.com/astropy/pyvo/llms.txt

Demonstrates how to inspect metadata of a registry resource, including its title, access URL, IVOID, access modes, and contact information. Use `verbose=True` for more detailed descriptions.

```python
nvss.describe(verbose=True)
print(nvss.res_title, nvss.access_url, nvss.ivoid)
print(nvss.access_modes())      # set of capability strings
print(nvss.get_contact())
```

--------------------------------

### Load TAP Table from CSV

Source: https://github.com/astropy/pyvo/blob/main/docs/dal/index.rst

Loads table content into a TAP service from a CSV formatted string. The 'source' parameter expects a StringIO object.

```python
tap_service.load_table(name='test_schema.test_table',
                       source=StringIO('article,count\narticle1,10\narticle2,20\n'), format='csv')
```

--------------------------------

### Simple Line Access with SLAService

Source: https://context7.com/astropy/pyvo/llms.txt

Use SLAService for querying spectral line databases. Supports wavelength range constraints and returns SLAResults with SLARecord rows.

```python
import pyvo as vo
from astropy import units as u

sla = vo.dal.SLAService("http://www.splatalogue.net/slap.php")

# Wavelength range in meters (or use astropy Quantity)
results = sla.search(wavelength=(2.0e-3, 2.1e-3))  # 2–2.1 mm

# With Quantity
wl_range = (u.Quantity(115.0, "GHz").to(u.m, equivalencies=u.spectral()),
            u.Quantity(120.0, "GHz").to(u.m, equivalencies=u.spectral()))
results2 = sla.search(wavelength=wl_range)

for row in results2:
    print(row["chemical_name"], row["measfreq"])
```

```python
# Module-level shortcut
results3 = vo.linesearch(
    "http://www.splatalogue.net/slap.php",
    wavelength=(2.0e-3, 2.1e-3)
)
```

--------------------------------

### Simple Image Access v2 — pyvo.dal.SIA2Service

Source: https://context7.com/astropy/pyvo/llms.txt

SIA version 2 provides ObsCore-based multi-parameter discovery supporting position, band, time, polarization, calibration level, and more. Returns `SIA2Results` with `ObsCoreRecord` rows.

```APIDOC
## SIA2Service

### Description
Provides ObsCore-based multi-parameter discovery supporting position, band, time, polarization, calibration level, and more. Returns `SIA2Results` with `ObsCoreRecord` rows.

### Method
`pyvo.dal.SIA2Service(url)`

### Parameters
- **url** (string) - The base URL for the SIA2 service.

### Usage Example
```python
import pyvo as vo
from astropy import units as u
from astropy.time import Time

sia2 = vo.dal.SIA2Service("https://ws.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/sia")

results = sia2.search(
    pos=[(10.5, 41.2, 0.1)],                 # (ra, dec, radius) CIRCLE in deg
    band=[(0.5e-6, 0.9e-6)],                 # wavelength interval in meters
    time=[Time("2010-01-01"), Time("2020-12-31")],
    calib_level=[2, 3],                       # from pyvo.dam.obscore.CALIBRATION_LEVELS
    collection=["CFHT"],
    data_type="image"
)

for rec in results:
    print(rec["obs_id"], rec["access_url"])
    # rec.getdataurl(), rec.getdataset() also available
```

### Module-level convenience function
`pyvo.dal.sia2.search(url, **kwargs)`

### Usage Example
```python
from pyvo.dal.sia2 import search as imagesearch2
results2 = imagesearch2(
    "https://ws.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/sia",
    pos=[(180.0, 0.0, 0.5)]
)
```
```