*********************
Astrometry.net Client
*********************
.. image:: https://readthedocs.org/projects/astrometry-net-client/badge/?version=latest
:target: https://astrometry-net-client.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. image:: https://github.com/StenSipma/astrometry_net_client/workflows/Build%20&%20Tests/badge.svg
:target: https://github.com/StenSipma/astrometry_net_client/actions?query=workflow%3A%22Build+%26+Tests%22
:alt: Build & Tests Status
.. note::
The package is still in development, but it can already be used.
Do not hesitate to leave any feedback (positive or negative)!
Quickstart
----------
Install the package via pip:
.. code:: bash
pip install astrometry-net-client
Get your API key from: `api_help`_, and paste it in a plaintext file (name it something like `key`).
A script called `anc_upload` should be included with the install.
.. _api_help: https://nova.astrometry.net/api_help
Introduction
------------
This package is meant to be a simple but extensible interface for the `Astrometry.net API`_.
A higher level interface is offered through the ``Client`` class, combining most functionality.
However, if you want more control over the requests (e.g. by manually checking the responses), you can also use the ``Job``, ``Submission`` and ``UploadFile`` classes directly.
The structure of these classes tries to follow the pattern of the API itself, which is essentially:
1. Upload some file (``UploadFile``), which requires an API key & a login (``Session``)
2. The upload creates a submission (``Submission``), unique for each upload. This has to do some general processing, even before the uploaded image is processed.
3. When the submission is done preprocessing, and the system is ready to process the uploaded file, a job (``Job``) is spawned for each image.
4. The job then takes some time to process, and when it is done it can either be successful or fail.
5. When successful, some information (e.g. found objects) and result files like the generated WCS header can be retrieved.
Using this package, these steps are (note that this is not the ideal way to upload multiple files):
.. code:: python
from astrometry_net_client import Session
from astrometry_net_client import FileUpload
s = Session(api_key='xxxxxxxxx')
upl = FileUpload('some/file/name', session=s) # 1.
submission = upl.submit() # 2.
submission.until_done() # blocks until it is finished
job = submission.jobs[0] # 3.
job.until_done() # 4. (again blocks)
if job.success():
wcs = job.wcs_file() # 5. (only if successful)
print(job.info()) # works even though the job failed
Or with the higher level ``Client`` :
.. code:: python
from astrometry_net_client import Client
c = Client(api_key='xxxxxxxxxx')
# WARNING: this can take a while, as it blocks until the file is solved.
# wcs will be None if upload is not successful
wcs = c.calibrate_file_wcs(filename)
One of the core ideas of this package is to try and make the minimal amount of requests possible and make them at a clear time. This is realized by the following *initialize & send* pattern:
.. code:: python
r = Request(url) # initialize (request not yet sent)
response = r.make() # send the request
Similarely, retrieving files like the WCS file (after a successful ``Job``) will be done once and cached thereafter:
.. code:: python
wcs = job.wcs_file() # first call makes the actual request
wcs_2 = job.wcs_file() # second call uses previously obtained result
.. _Astrometry.net API: http://nova.astrometry.net/
Installation
------------
Installation required python version 3.8 or greater.
Simpy install the package usng PyPi:
.. code:: bash
pip install astrometry-net-client
Note that the development and testing of this package is done on Linux, so it
may not work on a different platform.
Installing From Source
""""""""""""""""""""""
Installing the package from source is made easy by the Makefile, once you have a local copy of the repository (e.g. by cloning, or downloading & extracting the repo ZIP).
It is heavily recommended to use a virtual environment. Create and activate one by running:
.. code:: bash
make virt-env
source .env/bin/activate
pip install wheel
Then build & install the package with (does not install development dependencies):
.. code:: bash
make install
Documentation
-------------
Documentation is available at `Readthedocs`_
.. _Readthedocs: https://astrometry-net-client.readthedocs.io/en/latest/
There is a local documentation available (defined by docstrings). To access it, first install the package and the development dependencies:
.. code:: bash
make dependencies
then generate the documentation (using Sphinx) by:
.. code:: bash
make documentation
The main page can then be found at (assuming you are in the project root) ``./docs/_build/html/index.html``. Open this (for example) with:
.. code:: bash
firefox ./docs/_build/html/index.html
Examples
--------
Some example files/scripts are found at the `examples entry`_ of the documentation.
Some elaborate examples can be found in the ``examples`` directory.
For more specific usage, refer to the `documentation`_.
.. _examples entry: https://astrometry-net-client.readthedocs.io/en/latest/examples/overview.html
.. _documentation: https://astrometry-net-client.readthedocs.io/en/latest
Raw data
{
"_id": null,
"home_page": null,
"name": "astrometry-net-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "astronomy, astrometry, client, coordinates, wcs, api",
"author": null,
"author_email": "Sten Sipma <sten.sipma@ziggo.nl>",
"download_url": "https://files.pythonhosted.org/packages/e5/6e/2c22ba9f8dbbb9d34811f05b68af0a61ef12180579b77b58f98188222e60/astrometry_net_client-0.5.0.tar.gz",
"platform": null,
"description": "*********************\nAstrometry.net Client\n*********************\n\n.. image:: https://readthedocs.org/projects/astrometry-net-client/badge/?version=latest\n :target: https://astrometry-net-client.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation Status\n \n.. image:: https://github.com/StenSipma/astrometry_net_client/workflows/Build%20&%20Tests/badge.svg\n :target: https://github.com/StenSipma/astrometry_net_client/actions?query=workflow%3A%22Build+%26+Tests%22\n :alt: Build & Tests Status\n\n.. note:: \n The package is still in development, but it can already be used. \n Do not hesitate to leave any feedback (positive or negative)!\n\nQuickstart\n----------\n\nInstall the package via pip:\n\n.. code:: bash\n\n pip install astrometry-net-client\n\nGet your API key from: `api_help`_, and paste it in a plaintext file (name it something like `key`).\n\nA script called `anc_upload` should be included with the install.\n\n.. _api_help: https://nova.astrometry.net/api_help\n\n\n\nIntroduction\n------------\n\nThis package is meant to be a simple but extensible interface for the `Astrometry.net API`_.\nA higher level interface is offered through the ``Client`` class, combining most functionality.\nHowever, if you want more control over the requests (e.g. by manually checking the responses), you can also use the ``Job``, ``Submission`` and ``UploadFile`` classes directly.\n\nThe structure of these classes tries to follow the pattern of the API itself, which is essentially:\n\n1. Upload some file (``UploadFile``), which requires an API key & a login (``Session``)\n2. The upload creates a submission (``Submission``), unique for each upload. This has to do some general processing, even before the uploaded image is processed.\n3. When the submission is done preprocessing, and the system is ready to process the uploaded file, a job (``Job``) is spawned for each image.\n4. The job then takes some time to process, and when it is done it can either be successful or fail.\n5. When successful, some information (e.g. found objects) and result files like the generated WCS header can be retrieved.\n\nUsing this package, these steps are (note that this is not the ideal way to upload multiple files):\n\n.. code:: python\n \n from astrometry_net_client import Session\n from astrometry_net_client import FileUpload\n\n s = Session(api_key='xxxxxxxxx')\n upl = FileUpload('some/file/name', session=s) # 1.\n submission = upl.submit() # 2.\n submission.until_done() # blocks until it is finished \n job = submission.jobs[0] # 3.\n job.until_done() # 4. (again blocks)\n if job.success():\n wcs = job.wcs_file() # 5. (only if successful)\n print(job.info()) # works even though the job failed\n\nOr with the higher level ``Client`` :\n\n.. code:: python\n \n from astrometry_net_client import Client\n\n c = Client(api_key='xxxxxxxxxx')\n\n # WARNING: this can take a while, as it blocks until the file is solved.\n # wcs will be None if upload is not successful\n wcs = c.calibrate_file_wcs(filename) \n\nOne of the core ideas of this package is to try and make the minimal amount of requests possible and make them at a clear time. This is realized by the following *initialize & send* pattern:\n\n.. code:: python\n\n r = Request(url) # initialize (request not yet sent)\n response = r.make() # send the request\n\nSimilarely, retrieving files like the WCS file (after a successful ``Job``) will be done once and cached thereafter:\n\n.. code:: python\n\n wcs = job.wcs_file() # first call makes the actual request\n wcs_2 = job.wcs_file() # second call uses previously obtained result\n\n.. _Astrometry.net API: http://nova.astrometry.net/\n\n\nInstallation\n------------\n\nInstallation required python version 3.8 or greater.\n\nSimpy install the package usng PyPi:\n\n.. code:: bash\n\n pip install astrometry-net-client\n\nNote that the development and testing of this package is done on Linux, so it\nmay not work on a different platform.\n\nInstalling From Source\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nInstalling the package from source is made easy by the Makefile, once you have a local copy of the repository (e.g. by cloning, or downloading & extracting the repo ZIP).\n\nIt is heavily recommended to use a virtual environment. Create and activate one by running:\n\n.. code:: bash\n\n make virt-env\n source .env/bin/activate\n pip install wheel\n\nThen build & install the package with (does not install development dependencies):\n\n.. code:: bash\n\n make install\n\nDocumentation\n-------------\nDocumentation is available at `Readthedocs`_\n\n.. _Readthedocs: https://astrometry-net-client.readthedocs.io/en/latest/\n\nThere is a local documentation available (defined by docstrings). To access it, first install the package and the development dependencies:\n\n.. code:: bash\n\n make dependencies\n \nthen generate the documentation (using Sphinx) by:\n\n.. code:: bash\n\n make documentation\n\nThe main page can then be found at (assuming you are in the project root) ``./docs/_build/html/index.html``. Open this (for example) with:\n\n.. code:: bash\n\n firefox ./docs/_build/html/index.html\n\nExamples\n--------\nSome example files/scripts are found at the `examples entry`_ of the documentation.\n\nSome elaborate examples can be found in the ``examples`` directory. \nFor more specific usage, refer to the `documentation`_.\n\n.. _examples entry: https://astrometry-net-client.readthedocs.io/en/latest/examples/overview.html\n.. _documentation: https://astrometry-net-client.readthedocs.io/en/latest\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python interface for the Astrometry.net API.",
"version": "0.5.0",
"project_urls": {
"Documentation": "https://astrometry-net-client.readthedocs.io/en/latest/index.html",
"Repository": "https://github.com/StenSipma/astrometry_net_client"
},
"split_keywords": [
"astronomy",
" astrometry",
" client",
" coordinates",
" wcs",
" api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ab8882bb70467004e597d27ff4ce247669449b3c3a54f7346243d07914095587",
"md5": "005dce4dfa4116af0462ddb65f6184fe",
"sha256": "ca1077e7efb8c6e5ae357f5947e6915d7fbc62120bdf443ea61ebd7661a22a31"
},
"downloads": -1,
"filename": "astrometry_net_client-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "005dce4dfa4116af0462ddb65f6184fe",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 24651,
"upload_time": "2024-05-19T19:20:04",
"upload_time_iso_8601": "2024-05-19T19:20:04.686684Z",
"url": "https://files.pythonhosted.org/packages/ab/88/82bb70467004e597d27ff4ce247669449b3c3a54f7346243d07914095587/astrometry_net_client-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e56e2c22ba9f8dbbb9d34811f05b68af0a61ef12180579b77b58f98188222e60",
"md5": "c42bcd845cbdbe371432a7204945fe62",
"sha256": "9114cd4fa5de166bb9f2a7f91757c06f716d4398e0aa8d7784917718b7b0e427"
},
"downloads": -1,
"filename": "astrometry_net_client-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "c42bcd845cbdbe371432a7204945fe62",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 27950,
"upload_time": "2024-05-19T19:20:06",
"upload_time_iso_8601": "2024-05-19T19:20:06.904955Z",
"url": "https://files.pythonhosted.org/packages/e5/6e/2c22ba9f8dbbb9d34811f05b68af0a61ef12180579b77b58f98188222e60/astrometry_net_client-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-19 19:20:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "StenSipma",
"github_project": "astrometry_net_client",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "astrometry-net-client"
}
JSON
