Add Files API v1 and Data Sources API support#18
Merged
Conversation
Add file_new, file_job_new, file_jobs_list, file_get, file_delete, and file_job_get targeting the public Files API v1 endpoints, with File and FileJob resource classes, a FileSubmission dataclass, Idempotency-Key support, and client-side validation of custom_id/job_id constraints. file_new submits by remote URI (POST /files/v1/uri). Add the Data Sources API: onboarding_identities, data_source_new (with exist_ok conflict resolution), data_sources_list, data_source_get, data_source_test, data_source_delete, and a DataSource class. Add FilesApiError carrying the API error code and HTTP status, correct download error handling (format_not_ready vs not_found vs unsupported_format), and send a mpxpy/<version> User-Agent header on all requests. Mark the pre-release scs_file_new, list_scs_files, list_scs_jobs, and scs_job_status methods with the deprecated decorator and drop them from the README; remote submissions and job queries forward to the public endpoints. ScsFile is an alias of File. Bump version to 0.0.21.
kai-mathpix
reviewed
Jul 23, 2026
kai-mathpix
left a comment
kai-mathpix
left a comment
There was a problem hiding this comment.
Review comments are in the inline threads below.
- Raise on failed File.status() responses instead of caching error bodies as status data - Centralize Files API error-envelope parsing; raise FilesApiError only for recognized error bodies and MathpixClientError otherwise - Reject conversion_options keys that would override validated request fields in file_new and file_job_new - Drop the discarded metadata "mpxpy" marker; User-Agent covers attribution - Keep list_scs_jobs and scs_job_status on the legacy scs-jobs endpoints so deprecated callers keep the legacy response shapes - Expose filename, s3_region, and include_page_info on file_new and forward them from scs_file_new instead of dropping them - Restore ScsFile as a distinct deprecated class (minus cropped_image) and return it from scs_file_new again - Add mocked Files API unit tests and update the SCS tests for the final behavior - Fix the changelog and bump the version to 0.21.0
- file_new is the single submission entry point: exactly one of source_uri (POST /files/v1/uri) or file_path (multipart POST /files/v1); scs_file_new is now a thin deprecated wrapper that translates its legacy argument names and forwards to file_new - Rename file_jobs_list to file_job_list per the singular-resource naming convention - file_get and file_job_get now fetch the resource and return a seeded handle, matching app_token_get, and raise FilesApiError for unknown ids - Remove client-side duplicates of server-enforced constraints: the 200,000 items-per-call ceiling, the custom_id/Idempotency-Key charset and length checks, and the job file status filter enum; the server's FilesApiError is authoritative for those
kai-mathpix
reviewed
Jul 23, 2026
f-ortega-g
changed the title
…ction - Remove exist_ok from data_source_new; a registration conflict now raises through the centralized error parsing, preserving the server's conflict message - Document only observable data-source behavior: deletion removes the registration without interrupting already-started work and cloud-side grants are revoked separately; the gcp onboarding block is optional; external_id is a stable per-group value; inaccessible ids report not_found - Redact remote URIs in debug logs to scheme and host, and drop caller-controlled values that are not needed for diagnosis - Trim the changelog to the supported public surface - Add request-shape tests for Azure, GCP, and AWS access_key registration, the duplicate-name conflict, the optional gcp identity block, and log redaction
kai-mathpix
reviewed
Jul 24, 2026
mattmathpix
reviewed
Jul 24, 2026
mattmathpix
reviewed
Jul 24, 2026
Converges the escape-hatch naming with the pattern PR #19 introduces for the v3 methods, while the files methods are still unreleased. The deprecated scs_file_new keeps its legacy conversion_options argument and forwards it. The reserved-keys guard is unchanged: extra_options adds unmodeled API options but cannot override validated request fields.
mattmathpix
previously approved these changes
Jul 24, 2026
kai-mathpix
reviewed
Jul 24, 2026
kai-mathpix
reviewed
Jul 24, 2026
- file_new(file_path=...) now forwards custom_id as a multipart form field and Idempotency-Key as a header, matching the URI transport; the remote-only language is removed from the docs - Rename data_sources_list to data_source_list; remove the request-free data_source_get, with data_source_test and data_source_delete constructing the handle internally - Stop enforcing and publishing evolving server constraints: drop the provider/auth-method tables and secret pairing check (the server rejects invalid combinations), and remove the numeric limits and identifier rules from README and docstrings; keep required-value checks only - Fix the AWS access_key request-shape test to use the contract field name aws_access_key_id and assert the complete details body; document the shape in data_source_new - Add extra_options to the README's file_job_new argument list
The multipart body carries job_id under its legacy field name, which the reserved-keys guard did not cover, so a local-upload extra_options dict could smuggle a conflicting job id past validation. The guard now rejects the alias on the multipart path, and both transports treat an explicitly supplied Idempotency-Key the same way.
The multipart endpoint prefers the job_id form field (the old alias is deprecated server-side) and the options body accepts destination_uri directly, so drop the legacy-name translation: job_id travels as a form field and destination_uri keeps its public name. Verified against the endpoint's parameter handling; the deprecated scs_file_new wrapper still accepts its legacy argument names and translates them.
The docstrings promised files_api_url defaults to api_url, but the code fell back to the default host, silently sending Files API requests there for custom api_url configurations. The resolution is now explicit argument, then MATHPIX_FILES_API_URL, then the resolved api_url, with a unit test covering the precedence.
kai-mathpix
approved these changes
Jul 24, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds first-class support for the Files API v1, targeting the documented endpoint surface.
file_newtakes exactly one ofsource_uri(a remotes3://,gs://, publichttps://, or Azure Blob URI, viaPOST /files/v1/uri) orfile_path(a local file, via multipart upload). SupportsIdempotency-Keyretry safety,(job_id, custom_id)idempotency, and thefilename,s3_region, andinclude_page_infooptions. Anextra_optionsdict (also onfile_job_new) is the escape hatch for API options the SDK does not model yet, validated server-side.file_job_newsubmits documents in bulk viaPOST /files/v1/jobs, with aFileSubmissiondataclass. TheFileJobclass polls job status, lists files with a status filter and a pagination iterator, and fetches files bycustom_id.file_job_list,file_get,file_delete, andfile_job_get. The*_getmethods fetch the resource and return a handle seeded with the response, raising for unknown ids.delete(), and lazy status attributes; download errors are disambiguated per the API contract (format_not_readyvsnot_foundvsunsupported_format).onboarding_identities,data_source_new,data_source_list,data_source_test,data_source_delete, and aDataSourceclass.test()returns the probe body as-is (a failed probe is data, not an exception);secretis never logged.FilesApiErrorcarries the machine-readableerror_idandhttp_status. It is raised only for responses with a recognizable Files API error body; anything else falls back toMathpixClientError.custom_idwithin a batch) and rejectsextra_optionskeys that would override validated request fields; evolving protocol constraints (identifier charset/length, per-call ceilings, filter values) are left to the server as the authority.mpxpy/<version>.Version bumped to 0.0.21. README and changelog updated.
Deprecations
ScsFile,scs_file_new,list_scs_files,list_scs_jobs, andscs_job_statusare marked with the@deprecateddecorator (PEP 702;warnings.deprecatedon Python 3.13+,typing_extensions.deprecatedbelow that) and removed from the README. They keep their existing behavior and response shapes during the deprecation window, except thatscs_file_newis now a thin wrapper that translates its legacy argument names and forwards tofile_new.Tests
tests/test_files_api_unit.py: mocked unit tests (no credentials) covering request paths, bodies, headers, error handling and fallbacks, pagination, and every deprecated wrapper and its warning.tests/test_files_api.py: integration tests for the file and job workflows and data-source management.tests/test_scs.py: updated for the final deprecated-wrapper behavior.