astropop 0.9.5.dev11__tar.gz → 0.9.5.dev30__tar.gz

astropop-0.9.5.dev30/.agents/AGENTS.md

@@ -0,0 +1,27 @@
+# Working on Astropop
+
+Read [.agents/rules/development.md](rules/development.md) before changing this repository. These instructions apply throughout the checkout; explicit user instructions take precedence.
+
+## Commit messages
+
+Begin every commit subject with the module or area being changed, followed by a colon and a short description. Prefer a space after the colon:
+
+- `catalogs: handle empty SIMBAD responses`
+- `framedata: isolate cache shutdown tests`
+- `image: exclude rejected samples from summed errors`
+- `docs: explain FrameData conversion`
+- `ci: run live catalog checks in a separate job`
+- `agents: add repository skills`
+
+Make small, coherent commits. Use the affected module for its tests too; reserve `ci:` for workflows, environments, dependencies, and cross-cutting test infrastructure. Split unrelated changes rather than hiding them behind a broad prefix. Do not rewrite existing commits solely to enforce this convention unless asked.
+
+## Repository skills
+
+Read the relevant skill when its workflow applies. Ordinary small edits do not require loading every skill.
+
+| Skill | Use when |
+| --- | --- |
+| [astropop-ci](skills/astropop-ci/SKILL.md) | Diagnosing test, coverage, dependency, or GitHub Actions failures. |
+| [astropop-catalogs](skills/astropop-catalogs/SKILL.md) | Changing SIMBAD, VizieR, Gaia, or recorded/live catalog tests. |
+| [astropop-scientific-code](skills/astropop-scientific-code/SKILL.md) | Changing image reduction, FrameData, units, uncertainties, photometry, or polarimetry. |
+| [astropop-docs](skills/astropop-docs/SKILL.md) | Editing API docs, scientific examples, or fixing Sphinx builds. |

astropop-0.9.5.dev30/.agents/rules/development.md

@@ -0,0 +1,32 @@
+# Development rules
+
+## Scope and branches
+
+- Inspect `git status`, the current branch, and nearby code/tests before editing. Preserve unrelated work.
+- Keep independent fixes and features separate. A CI repair is not permission to redesign cache ownership, uncertainty semantics, or registration algorithms.
+- When asked for a new independent branch, use the requested base; otherwise prefer local `main` and state the choice. Use a feature branch as a base only when the work depends on it. Do not silently reset, discard work, or rewrite history.
+- Complete authorized local work without repeated confirmation. Local edits or commits do not themselves authorize a push, PR publication, merge, or release.
+
+## Implementation
+
+- Follow neighboring Python conventions and NumPy-style docstrings. Prefer the smallest change that fixes the cause while preserving public behavior.
+- Preserve physical units, coordinate frames/epochs, masks, uncertainties, shapes, and in-place semantics unless the task explicitly changes them.
+- Add regression coverage for behavioral fixes. Do not delete operations from exception or nonmutation tests just because their return values are unused.
+- Use `tmp_path` for disposable files/directories. Never hand a shared directory such as the system temporary root to an object that deletes its cache directory.
+- Test interpreter shutdown in a child process. Never call `atexit._run_exitfuncs()` inside pytest: it can stop coverage measurement and execute unrelated handlers.
+- Keep helpers inside their owning test classes where practical. Put genuinely shared fixtures in `conftest.py`; avoid one-off test files when an existing module fits.
+
+## Validation
+
+- Treat `pyproject.toml`, `tox.ini`, and `.github/workflows/` in this checkout as authoritative. Do not assume a test option or feature from another branch exists here.
+- Use an isolated Python environment with the appropriate test/docs extras. If using `XDG_CACHE_HOME` or `XDG_CONFIG_HOME`, create the directories first; Astropy may ignore nonexistent paths.
+- Start with the affected tests and broaden to the relevant integration checks. Once checks pass, repeat them only for new changes, failures, or unresolved concerns.
+- Keep ordinary CI offline and live catalog conformance in one explicit job when that infrastructure is present. Never make missing recorded responses silently fall through to the network.
+- Report commands/results, skips, and outstanding checks accurately. A local Linux pass does not prove Windows, macOS, oldest dependencies, development dependencies, or remote CI passed.
+- Do not globally suppress warnings or weaken tolerances to hide a failure. Expect deliberate warnings locally and fix unintended behavior at its source.
+
+## Commits and handoff
+
+Follow the module-prefix convention in [AGENTS.md](../AGENTS.md). Review the staged diff and commit in small batches, grouping implementation with its applicable tests. Stage named paths or hunks so unrelated changes are not included.
+
+PR descriptions should explain the concrete failure and resulting behavior, then give relevant validation and known limitations. Distinguish implemented fixes from future work and verified service behavior from recordings or historical observations.

astropop-0.9.5.dev30/.agents/skills/astropop-catalogs/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: astropop-catalogs
+description: Maintain Astropop SIMBAD, VizieR, and Gaia queries and their shared recorded/live tests, including schema changes, timeouts, and complete query results.
+---
+
+# Astropop catalogs
+
+Read the affected implementation in `astropop/catalogs/`, the corresponding tests in `tests/test_catalogs_online.py`, and the applicable VizieR YAML. Verify the installed Astroquery API and actual response shape before changing an endpoint or column name.
+
+## Compatibility invariants
+
+- SIMBAD can return degree-valued lowercase coordinates or legacy sexagesimal uppercase coordinates. Never infer hour-angle units from the semantic name RA alone. Handle both `None` and empty tables before indexing.
+- TAP photometry may have multiple rows per source/filter. Preserve source identity, band case, masks, proper motions, and bibliographic information when normalizing it.
+- Choose cone-search matches by separation rather than trusting response order. Identifier priority and prefix boundaries matter; substring matching can select a different catalog designation.
+- VizieR column aliases must work in outgoing column selection and incoming response normalization without renaming an already normalized column twice. Check sort-column names and epoch values against the configured time format.
+- Gaia asynchronous queue delays do not establish that a URL changed. Preserve the requested query mode and document timeout limitations honestly.
+- Where synchronous Gaia pagination is implemented, preserve integer source IDs, magnitude/cone filters on every page, exact column matching, final angular-distance ordering, and failure rather than partial results. Include page boundaries and IDs above `2**53` in deterministic coverage.
+- Keep timeout changes scoped to the client's connections, restore patched methods, close connections, and share a deadline across retries/pages. A socket timeout is not a hard deadline covering every DNS, streaming, or parsing step.
+
+## Recorded and live tests
+
+First check whether `tests/data/catalog_responses/README.md` and replay options exist on this branch. Read that README before recording. On branches without replay infrastructure, do not report skipped remote tests as offline conformance.
+
+Where supported:
+
+```sh
+python -m pytest tests/test_catalogs_online.py --remote-data=none
+python -m pytest tests/test_catalogs_online.py --remote-data=any
+```
+
+Keep assertions and collected test IDs shared between modes. Mock at the HTTP layer so Astroquery still builds queries and parses responses. Store compact fixtures per catalog, not per test. Offline mode must fail for unknown requests; live mode must bypass replay and result caches. Account for VizieR's explicit cache argument and import-time Gaia announcements.
+
+Refresh fixtures only when needed, using the documented explicit recording mode in one process. Preserve strict matching of query criteria, coordinates, filters, and pagination cursors. Normalize ordering only where semantically harmless, such as simple SELECT column lists. Review recordings for credentials/cookies and unrelated changes; rerun offline after recording.
+
+Keep deterministic edge-case tests alongside the catalog tests, with class-owned helpers where practical. Assert intentional no-result or proper-motion warnings around the precise call instead of suppressing them globally. A live Gaia skip option, if present, must leave offline and deterministic Gaia tests enabled and must not disable the dedicated conformance job's Gaia checks.

astropop-0.9.5.dev30/.agents/skills/astropop-ci/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: astropop-ci
+description: Diagnose and fix Astropop test, coverage, dependency, tox, and GitHub Actions failures while keeping ordinary CI independent of live catalogs.
+---
+
+# Astropop CI
+
+Inspect the failing job, current configuration, and failing test before choosing a fix. Separate a collection/import failure, assertion failure, service outage, dependency incompatibility, and coverage-measurement failure; they need different remedies.
+
+## Sources and checks
+
+- Dependency bounds and pytest/coverage settings: `pyproject.toml`.
+- Environment factors, extras, and commands: `tox.ini`.
+- Runner/platform and live/offline topology: `.github/workflows/`.
+- Catalog replay and custom options, if implemented: `tests/conftest.py` and `tests/data/catalog_responses/README.md`.
+
+Use the environment actually named in the failing job. Inspect `tox list` and `tox config -e <environment>` before assuming factors expand correctly. Check Python support and oldest dependency compatibility together. A version pin should explain the concrete incompatible API; it is not a substitute for claiming a migration is complete.
+
+Typical checks, adjusted to the installed tooling and changed files:
+
+```sh
+python -m pytest tests/test_affected_module.py
+python -m pytest tests docs --remote-data=none --cov=astropop --cov-report=term-missing
+python -m ruff check astropop tests
+git diff --check
+```
+
+The first path is a placeholder for the actual test module. If Ruff is not configured/installed in this checkout, inspect the repository's lint configuration first.
+
+## Coverage and resources
+
+For a coverage collapse, inspect collection/skips and whether any test executes process-wide shutdown handlers. Preserve the existing cache API while repairing harness isolation unless cache redesign is explicitly in scope. Test exit behavior with a subprocess, not pytest's own exit handlers. Use per-test cache directories and close file handles, including on Windows.
+
+## Catalog topology
+
+When the replay infrastructure exists, regular Python/platform/dependency jobs and coverage use recordings. Keep exactly one separate live catalog conformance job, including Gaia; a fast/offline Python job must still exist alongside it. Inspect the YAML embedded inside reusable-workflow `envs` strings as well as the outer workflow.
+
+Do not hide conformance failures by switching the live job to replay or silently skipping a service. Record an outage separately from a deterministic code failure. Use the catalog skill for query/schema and fixture changes.
+
+Validate relevant local checks, then report which remote/platform jobs remain unrun. Check the staged diff for unrelated feature code before making a module-prefixed commit.

astropop-0.9.5.dev30/.agents/skills/astropop-docs/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: astropop-docs
+description: Write or repair Astropop reStructuredText guides, NumPy-style API docstrings, and Sphinx examples using the behavior implemented on the current branch.
+---
+
+# Astropop documentation
+
+Read the implementation, nearby tests, and the relevant guide under `docs/`. Keep constructor APIs distinct from conversion helpers and describe actual defaults, mutation behavior, units, masks, and uncertainty semantics.
+
+Use runnable examples for deterministic local behavior where the existing documentation tooling supports them. Use static Python blocks for live catalog examples so documentation builds do not depend on external catalog queries. Remove IPython-only options when converting a directive to `code-block`.
+
+For FrameData guides, check shape/dtype constraints, copying and array sharing, metadata/WCS, FITS extension selection, overwrite defaults, and whether interchange preserves Boolean masks or full flag bits. Document only storage/configuration features available on this branch.
+
+For build failures:
+
+- Check reStructuredText section hierarchy, blank lines before lists, indentation, and balanced inline markup.
+- Keep the local checkout first on the documentation import path so autodoc describes the changed source.
+- Inspect `docs/conf.py` and docs extras rather than installing arbitrary extensions. Notebook rendering may require the Pandoc executable in addition to a Python package.
+- Distinguish rendering/autodoc errors, external inventory/network failures, and existing warnings. Do not suppress warnings globally to produce a green build.
+
+Validation depends on the change:
+
+```sh
+python -m pytest docs/path/to/changed-guide.rst
+python -m sphinx -b html docs /tmp/astropop-docs-build
+```
+
+Replace the guide path with the actual file. Use the configured tox docs environment when reproducing CI. For a warning audit, add `-W --keep-going` and report its result separately from the ordinary build. Inspect relevant rendered examples when layout or generated API content changes.
+
+Keep generated HTML, temporary images, and build caches out of commits. Use `docs:` for documentation commits and name the affected module when docstring updates are part of its implementation fix.

astropop-0.9.5.dev30/.agents/skills/astropop-scientific-code/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: astropop-scientific-code
+description: Implement and test Astropop scientific behavior in FrameData, image reduction, units and uncertainties, photometry, or polarimetry while preserving numerical and storage contracts.
+---
+
+# Astropop scientific code
+
+Locate the affected code in `astropop/framedata/`, `astropop/image/`, `astropop/math/`, `astropop/photometry/`, or `astropop/polarimetry/` and its existing tests. Read the current API and documentation; do not assume optional uncertainties, cache redesigns, or registration windows exist because they were discussed on another branch.
+
+## Define observable behavior
+
+Identify the expected data, units, shape/dtype, mask, uncertainty, metadata, and input-mutation behavior. Add a small numerical regression case with an independently derived result. Include compatible unit conversion and incompatible-unit errors when relevant.
+
+- Missing uncertainty and zero uncertainty are different storage states. If an operation promises to skip uncertainty work, test that conversion/propagation helpers are not invoked, not merely that the final array is absent.
+- In combining, apply rejection consistently to data and propagated errors. Check valid-sample counts and any normalization factor, including masked/all-rejected pixels. Preserve the existing estimator unless a statistical change is requested.
+- Test in-place and copying paths when affected; non-inplace calls must preserve source arrays and metadata. Exercise RAM/memmap paths for storage changes, including cleanup after exceptions.
+- Registration uses array row/column conventions and transform coordinate conventions that may differ. For a requested window feature, estimate from the window but test application to the full image and any necessary origin translation. Use sparse, deterministic synthetic sources to avoid ambiguous matches.
+- Photometry fixtures should use seeded noise when noise is necessary. Verify scalar and array-valued parameters against each other when both are supported. Do not simply loosen a numerical tolerance to hide nondeterminism.
+
+Use the existing test module for the affected subsystem. Restore global configuration changes with fixtures/monkeypatch. Keep regression cases small enough to diagnose and run routinely; use broader integration tests when the change crosses subsystem boundaries.
+
+Document changed scientific assumptions and API behavior, and distinguish numerical correctness checks from performance measurements. Do not claim speed or memory improvements without measurements when those claims matter to the task.

{astropop-0.9.5.dev11 → astropop-0.9.5.dev30}/.github/workflows/build-n-publish.yml

@@ -12,13 +12,13 @@ jobs:
     name: Build and publish to PyPi
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@master
+    - uses: actions/checkout@v6
       with:
         fetch-depth: 0
-    - name: Set up Python 3.9
-      uses: actions/setup-python@v1
+    - name: Set up Python 3.13
+      uses: actions/setup-python@v6
       with:
-        python-version: 3.9
+        python-version: '3.13'
     - name: Install pypa/build
       run: >-
         python -m

{astropop-0.9.5.dev11 → astropop-0.9.5.dev30}/.github/workflows/ci_devdeps.yml

@@ -23,19 +23,20 @@ jobs:
       libraries: |
         apt:
           - tzdata
-          - libopenblas-base
           - libopenblas-dev
       envs: |
-        - name: (Allowed Failure) Python 3.12 with dev version of deps
-          linux: py313-test-devdeps-online
-          python-version: 3.13-dev
-
+        # Live service compatibility is checked in CI's online conformance job.
+        # These environments exercise dependency/platform changes with mocks.
         - name: (Allowed Failure) Python 3.13 with dev version of deps
-          linux: py313-test-devdeps-online
-          python-version: 3.12
+          linux: py313-test-devdeps
+          python-version: '3.13'
+
+        - name: (Allowed Failure) Python 3.14 with dev version of deps
+          linux: py314-test-devdeps
+          python-version: '3.14'
 
-        - macos: py312-test-online
-          cache-key: ${{ github.ref }}-py312mac-astropycache
+        - macos: py313-test
+          cache-key: ${{ github.ref }}-py313mac-astropycache
 
-        - windows: py312-test-online
-          cache-key: ${{ github.ref }}-py312win-astropycache
+        - windows: py313-test
+          cache-key: ${{ github.ref }}-py313win-astropycache

{astropop-0.9.5.dev11 → astropop-0.9.5.dev30}/.github/workflows/ci_workflows.yml

@@ -20,16 +20,25 @@ jobs:
     with:
       cache-path: ~/.astropy
       envs: |
-        - linux: py38-test-olddeps-online
-          cache-key: ${{ github.ref }}-py38lin-astropycache
-        - linux: py39-test-online
-          cache-key: ${{ github.ref }}-py39lin-astropycache
-        - linux: py310-test-online
+        - linux: py310-test-olddeps
           cache-key: ${{ github.ref }}-py310lin-astropycache
-        - linux: py311-test-online
+        - linux: py311-test
           cache-key: ${{ github.ref }}-py311lin-astropycache
-        - linux: py312-test-online
+        - linux: py312-test
           cache-key: ${{ github.ref }}-py312lin-astropycache
+        - linux: py313-test
+          cache-key: ${{ github.ref }}-py313lin-astropycache
+        - linux: py314-test
+          cache-key: ${{ github.ref }}-py314lin-astropycache
+
+  online_conformance:
+    name: Online catalog conformance
+    uses: OpenAstronomy/github-actions-workflows/.github/workflows/tox.yml@v1
+    if: "!(contains(github.event.head_commit.message, '[skip ci]') || contains(github.event.head_commit.message, '[ci skip]'))"
+    with:
+      envs: |
+        - linux: py314-catalogs-online
+          python-version: '3.14'
 
   build_docs:
     uses: OpenAstronomy/github-actions-workflows/.github/workflows/tox.yml@v1
@@ -68,14 +77,12 @@ jobs:
         path: ${{ env.CONDA }}/envs
         key:
           ${{ github.ref }}-${{ runner.os }}-${{ runner.arch }}-${{ steps.get-date.outputs.today }}-conda-envs-${{ hashFiles('pyproject.toml') }}
-    - uses: conda-incubator/setup-miniconda@v2
+    - uses: conda-incubator/setup-miniconda@v4
       with:
-        miniforge-variant: Mambaforge
         miniforge-version: latest
         activate-environment: astropop
-        use-mamba: true
-        mamba-version: "*"
-        channels: conda-forge,defaults
+        channels: conda-forge
+        conda-remove-defaults: true
         python-version: "3.12"
     - name: Cache astropy cache
       uses: actions/cache@v3
@@ -87,7 +94,7 @@ jobs:
     - name: Install dependencies
       shell: bash -l {0}
       run: |
-        mamba install -y -q pytest astrometry \
+        conda install -y -q pytest astrometry \
                             astropy scipy numpy matplotlib \
                             scikit-image scikit-learn \
                             sep astroquery
@@ -104,7 +111,7 @@ jobs:
     - name: Run Pytest and generate coverage
       shell: bash -l {0}
       run: |
-        pytest --pyargs ./tests ./docs --remote-data --cov astropop --cov-config=./pyproject.toml
+        pytest --pyargs ./tests ./docs --remote-data=none --cov astropop --cov-config=./pyproject.toml
         coverage xml -o ./coverage.xml
     - name: Upload coverage to Codecov
       uses: codecov/codecov-action@v4

{astropop-0.9.5.dev11 → astropop-0.9.5.dev30}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: astropop
-Version: 0.9.5.dev11
+Version: 0.9.5.dev30
 Summary: Astronomical Polarimetry and Photometry Pipeline
 Author-email: Julio Campagnolo <julio.campagnolo@cefet-rj.br>
 License: BSD-3-Clause
@@ -17,15 +17,15 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Topic :: Scientific/Engineering :: Astronomy
 Classifier: Topic :: Scientific/Engineering :: Physics
-Requires-Python: >=3.8
+Requires-Python: >=3.10
 Description-Content-Type: text/x-rst
-Requires-Dist: astropy>=4.3
-Requires-Dist: numpy>=1.17
-Requires-Dist: scipy>=1.6
+Requires-Dist: astropy>=5.0
+Requires-Dist: numpy>=1.21.6
+Requires-Dist: scipy>=1.7.3
 Requires-Dist: astroquery
 Requires-Dist: scikit-image
 Requires-Dist: scikit-learn
-Requires-Dist: photutils>=1.7
+Requires-Dist: photutils<3,>=1.7
 Requires-Dist: pytz
 Requires-Dist: pyyaml
 Requires-Dist: astroscrappy
@@ -40,7 +40,9 @@ Requires-Dist: pytest-astropy; extra == "test"
 Requires-Dist: pytest-remotedata; extra == "test"
 Requires-Dist: testfixtures; extra == "test"
 Requires-Dist: pytest-rerunfailures; extra == "test"
+Requires-Dist: vcrpy>=7; extra == "test"
 Provides-Extra: docs
+Requires-Dist: matplotlib; extra == "docs"
 Requires-Dist: ipython; extra == "docs"
 Requires-Dist: ipykernel; extra == "docs"
 Requires-Dist: sphinx; extra == "docs"

{astropop-0.9.5.dev11 → astropop-0.9.5.dev30}/astropop/catalogs/_online_tools.py

@@ -76,9 +76,13 @@ def astroquery_skycoord(center, simbad=None):
             if simbad is None:
                 simbad = Simbad()
             t = simbad.query_object(center)
-            if t is None:
+            if t is None or len(t) == 0:
                 raise ValueError(f'Coordinates {center} could not be'
                                  ' resolved.')
+            # The TAP interface (Astroquery >= 0.4.8) returns degrees
+            # under lowercase names; the legacy interface used sexagesimal.
+            if 'ra' in t.colnames and 'dec' in t.colnames:
+                return SkyCoord(t['ra'][0], t['dec'][0], unit='deg')
             return guess_coordinates(t['RA'][0], t['DEC'][0], skycoord=True)
     if isinstance(center, (tuple, list, np.ndarray)) and len(center) == 2:
         return guess_coordinates(center[0], center[1], skycoord=True)

{astropop-0.9.5.dev11 → astropop-0.9.5.dev30}/astropop/catalogs/gaia.py

@@ -2,11 +2,14 @@
 """Query and match objects in catalogs using TAP services."""
 
 import copy
+import time
+from contextlib import contextmanager
 import numpy as np
 from astropy.coordinates import SkyCoord
 from astropy import units as u
 from astroquery.gaia import Gaia
 from astropy.time import Time
+from astropy.table import vstack
 
 from ._sources_catalog import _OnlineSourcesCatalog, SourcesCatalog
 from ._online_tools import astroquery_query, string_fix
@@ -16,6 +19,45 @@ from ..math import QFloat
 __all__ = ['GaiaDR3SourcesCatalog', 'gaiadr3']
 
 
+@contextmanager
+def _gaia_query_timeout(client, timeout=300):
+    """Limit socket waits using one budget for the whole Gaia query.
+
+    The deadline is checked when a connection is created; its remaining time
+    becomes that socket's inactivity timeout. This is not a hard wall-clock
+    limit on DNS resolution, a continuously streaming response, or parsing.
+    """
+    # Gaia can accept an async job but leave it in EXECUTING for minutes, even
+    # for a tiny result. A successful availability request does not rule this
+    # out. Astroquery polls the job without an overall deadline, and its TAP
+    # sockets have no explicit timeout, so even a status read can hang.
+    #
+    # The TAP client has no public timeout setter. Adapt the connection factory
+    # only on this catalog's deepcopy of Gaia, preserving the configured host
+    # and avoiding process-wide socket changes. Restore it on success or error.
+    handler = client._TapPlus__getconnhandler()._TapConn__connectionHandler
+    original = handler.get_connection
+    deadline = time.monotonic() + timeout
+    connections = []
+
+    def get_connection(*args, **kwargs):
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            raise TimeoutError('Gaia query timed out.')
+        connection = original(*args, **kwargs)
+        connection.timeout = remaining
+        connections.append(connection)
+        return connection
+
+    handler.get_connection = get_connection
+    try:
+        yield
+    finally:
+        handler.get_connection = original
+        for connection in connections:
+            connection.close()
+
+
 class GaiaDR3SourcesCatalog(_OnlineSourcesCatalog):
     """Sources catalog from Gaia-DR3 catalog.
 
@@ -43,10 +85,16 @@ class GaiaDR3SourcesCatalog(_OnlineSourcesCatalog):
         Maximum G-band magnitude to query. If None, no magnitude
         filtering will be performed. Default is None.
 
+    query_mode: {'async', 'sync'} (optional)
+        Use asynchronous jobs (default) or synchronous requests. Synchronous
+        queries fetch pages of at most 2000 sources and return the complete
+        result sorted by distance, without creating asynchronous jobs.
+
     Raises
     ------
     ValueError:
-        If a ``band`` not available in the filters is passed.
+        If a ``band`` not available in the filters is passed, or
+        ``query_mode`` is not ``'async'`` or ``'sync'``.
     """
 
     _available_filters = ['G', 'BP', 'RP']
@@ -58,7 +106,11 @@ class GaiaDR3SourcesCatalog(_OnlineSourcesCatalog):
                 'phot_variable_flag', 'non_single_star',
                 'in_galaxy_candidates']
 
-    def __init__(self, center, radius, band='all', max_g_mag=None):
+    def __init__(self, center, radius, band='all', max_g_mag=None, *,
+                 query_mode='async'):
+        if query_mode not in ('async', 'sync'):
+            raise ValueError("query_mode must be 'async' or 'sync'.")
+        self._query_mode = query_mode
         self._setup_catalog()
         self._max_g_mag = max_g_mag
         _OnlineSourcesCatalog.__init__(self, center, radius=radius, band=band)
@@ -103,10 +155,24 @@ class GaiaDR3SourcesCatalog(_OnlineSourcesCatalog):
         mag_err = 1.1/np.array(query[f'phot_{f}_mean_flux_over_error'])
         return QFloat(mag, mag_err, unit='mag')
 
-    def _query_object_async(self, center, radius=None, columns=None):
-        """Construct the query and launch job. Good for max_g_mag filtering."""
-        # Based on astroquery.gaia.Gaia.query_object_async
+    def _query_object(self, center, radius=None, columns=None):
+        """Query a cone using the selected TAP mode and sort by distance."""
+        # Based on astroquery.gaia.Gaia.query_object_async. Sync mode bypasses
+        # async job execution/polling, which was slow even when the same SQL
+        # completed promptly through /sync. It can still suffer network or
+        # server timeouts; it is an alternative path, not a timeout guarantee.
+        sync = self._query_mode == 'sync'
+        # Astroquery's synchronous launcher limits results to 2000 rows, even
+        # with Gaia.ROW_LIMIT = -1. Page by unique source_id to avoid truncation.
+        # Distance is not a safe cursor because multiple sources can tie.
+        # Keep IDs as integers (Gaia IDs exceed float's exact-integer range),
+        # and remove this extra column unless the caller requested it.
+        include_id = sync and 'source_id' not in columns
         columns = ','.join(map(str, columns))
+        if include_id:
+            columns += ',source_id'
+        row_limit = 'TOP 2000' if sync else ''
+        order = 'source_id ASC' if sync else 'dist ASC'
 
         ra = center.ra.degree
         dec = center.dec.degree
@@ -117,7 +183,7 @@ class GaiaDR3SourcesCatalog(_OnlineSourcesCatalog):
             mag_filtering = ''
 
         query = f"""
-            SELECT
+            SELECT {row_limit}
                 {columns},
                 DISTANCE(
                     POINT('ICRS', {self._g.MAIN_GAIA_TABLE_RA},
@@ -132,18 +198,51 @@ class GaiaDR3SourcesCatalog(_OnlineSourcesCatalog):
                       CIRCLE('ICRS', {ra}, {dec}, {radius})
                   )
                   {mag_filtering}
+                  {{page_filter}}
                 ORDER BY
-                  dist ASC
+                  {order}
         """
 
-        return self._g.launch_job_async(query,
-                                        dump_to_file=False).get_results()
+        if not sync:
+            return self._g.launch_job_async(query.format(page_filter=''),
+                                            dump_to_file=False).get_results()
+
+        pages = []
+        last_id = None
+        while True:
+            page_filter = ('' if last_id is None else
+                           f'AND source_id > {last_id}')
+            page = self._g.launch_job(query.format(page_filter=page_filter),
+                                      dump_to_file=False).get_results()
+            if page is None:
+                raise RuntimeError('No online catalog result found.')
+            if len(page):
+                next_id = int(page['source_id'][-1])
+                if last_id is not None and next_id <= last_id:
+                    raise RuntimeError('Gaia synchronous pagination stalled.')
+                last_id = next_id
+            pages.append(page)
+            # A full page does not prove that the result is complete. An exact
+            # multiple of 2000 therefore needs one final, empty request.
+            if len(page) < 2000:
+                break
+        result = vstack(pages, join_type='exact') if len(pages) > 1 else pages[0]
+        # Page order is by ID; the catalog API promises angular-distance order.
+        result.sort('dist')
+        if include_id:
+            result.remove_column('source_id')
+        return result
 
     def _do_query(self):
-        self._query = astroquery_query(self._query_object_async,
-                                       self._center,
-                                       radius=self._radius.to(u.deg).value,
-                                       columns=self._columns)
+        # Keep the deadline outside astroquery_query: its timeout retries must
+        # not each get a fresh five-minute budget. In sync mode this same budget
+        # covers every page. An exception propagates instead of exposing a
+        # partial catalog or silently switching back to the slow async path.
+        with _gaia_query_timeout(self._g):
+            self._query = astroquery_query(self._query_object,
+                                           self._center,
+                                           radius=self._radius.to(u.deg).value,
+                                           columns=self._columns)
         sk = SkyCoord(self._query['ra'], self._query['dec'],
                       obstime=Time(self._query['ref_epoch'], format='jyear'),
                       pm_ra_cosdec=self._query['pmra'],