<commit_before># Licensed under a 3-clause BSD style license - see LICENSE.rst
"""
Support basic VO conesearch capabilities.

Based on the `Simple Cone Search Version 1.03 Recommendation
<http://www.ivoa.net/Documents/REC/DAL/ConeSearch-20080222.html>`_.

Available databases are generated on the server side by
`astropy.vo.server.validate.check_conesearch_sites`.
Default database is 'conesearch_good.json', which can be changed
locally in a session via AstroPy configuration system.

.. note::

    Currently, setting the `pedantic` keyword to `True`
    will not yield any results.

.. warning::

    When Cone Search returns warnings, user should decide
    whether the results are reliable by inspecting the
    warning codes in `astropy.io.votable.exceptions`.

*CONFIGURABLE PROPERTIES*

These properties are set via Astropy configuration system:

    * `astropy.vo.client.conesearch_dbname`
    * Also depends on properties set by `astropy.vo.client.vos_catalog`

Examples
--------
Perform cone search for 0.5 degree radius around 47 Tuc
(RA 6.088 deg, DEC -72.086 deg) with minimum verbosity,
if supported. The first catalog in the database to
successfully return a result is used. If running this for
the first time, a copy of the catalogs database will be
downloaded to local cache. To run this again without
using cached data, set `cache` keyword to `False`:

>>> from astropy.vo.client import conesearch
>>> result = conesearch.conesearch(6.088, -72.086, 0.5, pedantic=False)

Extract Numpy array containing the matched objects. See
`numpy.ndarray` for available operations:

>>> cone_arr = result.array.data
>>> col_names = cone_arr.dtype.names
>>> col_ra = col_names[1] # This depends on the catalog
>>> n_rec = cone_arr.size
>>> ra_list = cone_arr[col_ra]
>>> first_row = cone_arr[0]
>>> last_row = cone_arr[-1]
>>> first_ten_rows = cone_arr[:10]

Result can also be manipulated as `astropy.io.votable`
and its unit can be manipulated as `astropy.units`:

>>> from astropy import units as u
>>> ra_field = result.get_field_by_id(col_ra)
>>> print(ra_field.unit)
deg
>>> ra_arcsec = ra_field.unit.to(u.arcsec) * ra_list

Perform the same cone search as above but asynchronously:

>>> async_search = conesearch.AsyncConeSearch(
...     6.088, -72.086, 0.5, pedantic=False)

Check search status:
<commit_msg>in doc, show example unit conv print out<commit_after># Licensed under a 3-clause BSD style license - see LICENSE.rst
"""
Support basic VO conesearch capabilities.

Based on the `Simple Cone Search Version 1.03 Recommendation
<http://www.ivoa.net/Documents/REC/DAL/ConeSearch-20080222.html>`_.

Available databases are generated on the server side by
`astropy.vo.server.validate.check_conesearch_sites`.
Default database is 'conesearch_good.json', which can be changed
locally in a session via AstroPy configuration system.

.. note::

    Currently, setting the `pedantic` keyword to `True`
    will not yield any results.

.. warning::

    When Cone Search returns warnings, user should decide
    whether the results are reliable by inspecting the
    warning codes in `astropy.io.votable.exceptions`.

*CONFIGURABLE PROPERTIES*

These properties are set via Astropy configuration system:

    * `astropy.vo.client.conesearch_dbname`
    * Also depends on properties set by `astropy.vo.client.vos_catalog`

Examples
--------
Perform cone search for 0.5 degree radius around 47 Tuc
(RA 6.088 deg, DEC -72.086 deg) with minimum verbosity,
if supported. The first catalog in the database to
successfully return a result is used. If running this for
the first time, a copy of the catalogs database will be
downloaded to local cache. To run this again without
using cached data, set `cache` keyword to `False`:

>>> from astropy.vo.client import conesearch
>>> result = conesearch.conesearch(6.088, -72.086, 0.5, pedantic=False)

Extract Numpy array containing the matched objects. See
`numpy.ndarray` for available operations:

>>> cone_arr = result.array.data
>>> col_names = cone_arr.dtype.names
>>> col_ra = col_names[1] # This depends on the catalog
>>> n_rec = cone_arr.size
>>> ra_list = cone_arr[col_ra]
>>> first_row = cone_arr[0]
>>> last_row = cone_arr[-1]
>>> first_ten_rows = cone_arr[:10]

Result can also be manipulated as `astropy.io.votable`
and its unit can be manipulated as `astropy.units`:

>>> from astropy import units as u
>>> ra_field = result.get_field_by_id(col_ra)
>>> print(ra_field.unit)
deg
>>> ra_field.unit.to(u.arcsec) * ra_list
array([ 16075.35  ,  16088.0112,  16090.4628, ...])

Perform the same cone search as above but asynchronously:

>>> async_search = conesearch.AsyncConeSearch(
...     6.088, -72.086, 0.5, pedantic=False)

Check search status:

{'fraction_non_alphanumeric': 0.1008706731790189, 'fraction_numerical': 0.027394351242301974, 'mean_word_length': 4.3583617747440275, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 95, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7034870', 'n_tokens_mistral': 1560, 'n_tokens_neox': 1442, 'n_words': 526}