Skip to content

GAIA: update the method gaia load data returns the path of the downloaded DataLink archive - #3673

Open
cosmoJFH wants to merge 3 commits into
astropy:mainfrom
esdc-esac-esa-int:ESAC_Gaia_GAIASA-3522_method_Gaia-load_data_returns_tuple
Open

GAIA: update the method gaia load data returns the path of the downloaded DataLink archive #3673
cosmoJFH wants to merge 3 commits into
astropy:mainfrom
esdc-esac-esa-int:ESAC_Gaia_GAIASA-3522_method_Gaia-load_data_returns_tuple

Conversation

@cosmoJFH

@cosmoJFH cosmoJFH commented Oct 1, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Dear Astroquery team,

we have opened this PR since we'd like to update the Gaia.load_data method to return the path of the downloaded DataLink archive when dump_to_file=True.

Currently, load_data prints the generated archive path but does not make it available programmatically. Returning the path allows users to directly access and process downloaded products, which is particularly useful for the upcoming Gaia DR4 residual_image products.

We have implemented the following changes:

  1. Return None when dump_to_file=False.
  2. Return the absolute path to the downloaded ZIP file when dump_to_file=True.
  3. Preserve the existing method signature and backwards compatibility.

Example

dl_dict, out_path = Gaia.load_data(
    ids=ids,
    data_release="Gaia DR4_RC3",
    retrieval_type="RESIDUAL_IMAGE",
    data_structure="DATAMODEL_STANDARD",
    dump_to_file=True,
    format="fits",
)

cc @esdc-esac-esa-int
jira: GAIASA-3522

@keflavich

keflavich commented Oct 1, 2026

Copy link
Copy Markdown
Contributor

The proposed API seems fine to me.

This should be accompanied by a warning, since it will change the output of load_data from a single table entry to (table, string), right?

An alternative approach is to leave the default behavior as-is (table = Gaia.load_data(dump_to_file=False)) and only add the new return if the file is dumped (table, path = Gaia.load_data(dump_to_File=True)).

I may slightly prefer the latter but I don't feel strongly. I'll check what we do elsewhere in astroquery...

@cosmoJFH
cosmoJFH force-pushed the ESAC_Gaia_GAIASA-3522_method_Gaia-load_data_returns_tuple branch from 84e1f46 to ff2fa5a Compare October 1, 2026 16:35
@cosmoJFH

cosmoJFH commented Oct 1, 2026

Copy link
Copy Markdown
Contributor Author

The proposed API seems fine to me.

This should be accompanied by a warning, since it will change the output of load_data from a single table entry to (table, string), right?

An alternative approach is to leave the default behavior as-is (table = Gaia.load_data(dump_to_file=False)) and only add the new return if the file is dumped (table, path = Gaia.load_data(dump_to_File=True)).

I may slightly prefer the latter but I don't feel strongly. I'll check what we do elsewhere in astroquery...

Hi @keflavich, thanks for your feedback. I will discuss this alternative implementation with the rest of the team.

@cosmoJFH
cosmoJFH force-pushed the ESAC_Gaia_GAIASA-3522_method_Gaia-load_data_returns_tuple branch from a5983b0 to 2090536 Compare October 1, 2026 17:22
@codecov

codecov Bot commented Oct 1, 2026 •
edited
Loading

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 73.80%. Comparing base (c777720) to head (d449dcb).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files 
@@            Coverage Diff             @@
##             main    #3673      +/-   ##
==========================================
+ Coverage   73.76%   73.80%   +0.03%     
==========================================
  Files         230      230              
  Lines       21570    21575       +5     
==========================================
+ Hits        15911    15923      +12     
+ Misses       5659     5652       -7

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@cosmoJFH

cosmoJFH commented Oct 1, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

This should be accompanied by a warning,

What kind of warning should we include?

We included the following warning message at the beginning of the method

        warnings.warn(
            "The return value of Gaia.load_data() has changed. The method now "
            "returns a tuple containing the DataLink products and the path to the output file.",
            AstropyUserWarning,
            stacklevel=2,
        )

Could you provide an example?

@cosmoJFH
cosmoJFH force-pushed the ESAC_Gaia_GAIASA-3522_method_Gaia-load_data_returns_tuple branch 4 times, most recently from 6295371 to 2eb645b Compare October 1, 2026 18:50
@cosmoJFH
cosmoJFH force-pushed the ESAC_Gaia_GAIASA-3522_method_Gaia-load_data_returns_tuple branch from fb3e3c6 to d449dcb Compare October 1, 2026 18:54
@bsipocz bsipocz added the gaia label Oct 2, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

gaia

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@cosmoJFH @keflavich @bsipocz