astropy.wcs 'public' C-level API

[Thomas Robitaille]

Hi everyone,

As I was working on some code in astropy.wcs I came across something I had forgotten existed – a small C-level API alongside the Python one: when you pip install astropy (even a binary wheel), the package bundles a set of C headers, discoverable at runtime via astropy.wcs.get_include(), that let another C/Cython extension call into astropy's C-level WCS machinery directly,  without going through Python objects. I encountered this because I was about to remove a couple of C functions and then realised they are exposed through this. However, this isn't actually documented anywhere.

I'm curious whether anyone here actually uses this or knows of people/groups that do, and if not, how do people feel about deprecating this and removing it in the long term? I personally would prefer for the C WCS code in astropy to be an internal implementation detail rather than some public C functions we have to keep stable.

Cheers,

Tom

[Pey Lian Lim]

Curious!

1. Is there a pattern we can grep for on GitHub to smoke out possible unsanctioned use?

2. Does the blame tell us why it was exposed in the first place?

Thanks for following up!

[Reem Hamraz]

Hi Thomas! (hi everyone!)

I just wanted to chime in here because this kind of perfectly overlaps with what I’ll be working on this summer!
Quick intro: I'm Reem, the GSoC student tackling the "Hardening Astropy's Core Stability" project alongside my mentors (Clément & Nathaniel)

A big part of my project involves writing tests that directly hit Astropy's compiled extension modules without going through the Python API, and one of my specific milestones is to write these direct tests for the astropy/wcs compiled modules and to look into refactoring the unit_list_proxy.c runtime dependency.

So, since you're looking at cleaning up and potentially deprecating parts of the WCS C-level API, I just wanted to wave hello and put my project on your radar! I chatted with my mentors this morning, and we agreed that I'll simply hold off on tackling the WCS extensions until this conversation wraps up and the dust settles on what the final C API will look like.

I'll be following this thread closely to see where things land. Thank you so much for bringing this up!

Best,
Reem

--
You received this message because you are subscribed to the Google Groups "astropy-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to astropy-dev...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/astropy-dev/CAGMHX_0J1j9CqKSHfMnPwioo%2B42natzddMuWOeFjLX_HEU%2Bdew%40mail.gmail.com.

[Thomas Robitaille]

On Thu, 4 Jun 2026 at 15:58, Pey Lian Lim <p3y...@gmail.com> wrote:

Curious!

1. Is there a pattern we can grep for on GitHub to smoke out possible unsanctioned use?

For another experiment I did, I had previously/recently downloaded the source distribution of every package that declares astropy as a dependency (actually I downloaded all those that mentioned 'astropy' anywhere and then cut it down to ones that had astropy as a dependency). There were 2531 packages with astropy as a dependency a month ago. Searching through those, I found exactly one that make use of the public C API: drizzlepac

It looks like it makes use of six C functions:

- wcsprm_python2c

- wcsprm_c2python

- pipeline_all_pixel2world

- wcss2p

- wcsprt

- wcslib_get_error_message

This is actually very relevant to know for my work in https://github.com/astropy/astropy/pull/19862 to try and get rid of wcsprm_python2c and wcsprm_c2python - now I know there is one user of them, so I should be more careful.

 

2. Does the blame tell us why it was exposed in the first place?

Given that it's used by an STScI package, I guess the answer is 'insider job'? 😅

 

I guess we should probably think about this more though to figure out what to do long term. If we do want to keep supporting it, I guess we should make it properly public and document it, but we should probably have a discussion. At least it seems likely that for now drizzlepac is the only user of this, so it might make the conversation easier to arrange.

Cheers,

Tom

Thanks for following up!

On Wednesday, June 3, 2026 at 4:45:53 PM UTC-4 Thomas Robitaille wrote:

Hi everyone,

As I was working on some code in astropy.wcs I came across something I had forgotten existed – a small C-level API alongside the Python one: when you pip install astropy (even a binary wheel), the package bundles a set of C headers, discoverable at runtime via astropy.wcs.get_include(), that let another C/Cython extension call into astropy's C-level WCS machinery directly,  without going through Python objects. I encountered this because I was about to remove a couple of C functions and then realised they are exposed through this. However, this isn't actually documented anywhere.

I'm curious whether anyone here actually uses this or knows of people/groups that do, and if not, how do people feel about deprecating this and removing it in the long term? I personally would prefer for the C WCS code in astropy to be an internal implementation detail rather than some public C functions we have to keep stable.

Cheers,

Tom

--
You received this message because you are subscribed to the Google Groups "astropy-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to astropy-dev...@googlegroups.com.

To view this discussion visit https://groups.google.com/d/msgid/astropy-dev/57be747b-1836-41e0-bf72-c3823e053b62n%40googlegroups.com.

[Thomas Robitaille]

Hi Reem

Welcome to the project! Glad you will be helping out with the compiled extensions :)

Cheers,

Tom

To view this discussion visit https://groups.google.com/d/msgid/astropy-dev/CAJEECRK4sJg7KH%2BF%2BE_wEE6OBZw7XzP1q07LurX1ZEGh2zc3_Q%40mail.gmail.com.

[Pey Lian Lim]

Drizzlepac... I'll ask around. Thanks for digging that out!