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!

[Thomas Robitaille]

Hi everyone,

Just to follow up on this, drizzlepac does actively use a few
functions from the C API, but actually only a small number (6 out of
24 symbols), so I think it's worth thinking about how we want to deal
with this going forward:

1. We could just keep things as-is and keep undocumented

2. We could keep things as-is but actually document the whole API publicly

3. We could deprecate the 18 symbols that are *not* used by drizzlepac
now and also add a note to get_include_path to indicate that this is
legacy functionality (though not deprecated) and discouraged for new
projects. There are no other projects on PyPI that use this
functionality as noted before, though some people might be using it in
private packages

4. We could deprecate the whole API but agree to keep the symbols used
by drizzlepac deprecated until drizzlepac itself is no longer
maintained (and remove the other symbols after a major release or
two). Then the long term plan is to have the C API completely removed.

5. Move WCSLIB and the astropy extensions to this (related to
distortions) out into a separate package and actually expose more of
WCSLIB so that other projects that need to link against WCSLIB can do
so without re-bundling it themselves

6. Something else I haven't thought of?

I'd be interested in people's thoughts about this!

Cheers,
Tom

[Pey Lian Lim]

FWIW, my preferences (from like to dislike, and I think Steve Goldman and Mihai Cara more or less agree): 1, 3, 4, 2, 5

2 and 5 are going to come back and bite us. I'd rather we not even think about them anymore.

1 is the least work for everyone. The code was from pywcs days and it is useful in at least one package (drizzlepac), so if it is not broken, why fix? Mihai mentioned that if you need thread-safety, one option that aligns with (1) is you add new thread-safe functions and document the old ones as not thread-safe.

Hope this helps. Thanks for the ideas!

[Thomas Robitaille]

I agree that 2 is not a good idea. My preference at the moment would
be 3 because it doesn't affect drizzlepac but discourages new use of
undocumented functionality - if other packages start using some of
these other currently unused symbols, it may end up being more work in
future for us to support.

Cheers,
Tom

> To view this discussion visit https://groups.google.com/d/msgid/astropy-dev/ab6d6cac-1f70-421e-8739-5694e2edf6dan%40googlegroups.com.

[Pey Lian Lim]

Thanks, Tom. I think we can tolerate Option 3. Thanks! :)

[Thomas Robitaille]

Hi everyone,

Since there are no objections, I have opened https://github.com/astropy/astropy/pull/19971 - this deprecates the unused slots (unused meaning by any package on PyPI), and this means we could remove most of the API in 10.0.0. If drizzlepac is able to transition away from the remaining slots, we will be able to deprecate and remove the whole C API.

Cheers,

Tom

To view this discussion visit https://groups.google.com/d/msgid/astropy-dev/34823eee-1a25-4eab-bb11-371e050807a8n%40googlegroups.com.