Document the Python API and API tokens - #24
Open
krokicki wants to merge 6 commits into
Open
Conversation
Documents the fileglancer package's Python client (API tokens, scopes, path operations, data links, Neuroglancer links, jobs, and errors) and wires the new page into the Features sidebar. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Replace the site-specific /nearline/... placeholder with a neutral /data/alice/... path, document the 401 token-expiry behavior (message format, Expired badge, no renewal), and note that mkdir and write require an existing parent directory. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
jobs:write runs pre_run/post_run shell and the job command as the user, so it isn't confined by files:read/files:write the way the scope list might imply. State that plainly in the scope table instead of leaving it to be discovered. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The /api/jobs prefix covers the job list, each job's full record, and its log files, so "List jobs" understated the scope. Matches the wording now shown in the token creation dialog. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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
1 participant
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.
Documents the Python client and API tokens added in JaneliaSciComp/fileglancer#435. Merge alongside that PR — this page describes a feature that does not exist until it lands.
Adds
features/python-api.mdxplus its sidebar entry: creating a token in the web UI, the scope table, the two environment variables, working with absolute paths, data links, the Neuroglancer workflow, jobs, and error handling.What to check
Every code example and factual claim was verified against the implementation rather than the design doc, because the two diverged during the build. Specifically worth confirming:
API_SCOPESinfileglancer/auth.py, andjobs:readis described as reaching each job's full record and log files — the/api/jobsprefix covers/{job_id}and/{job_id}/files/{file_type}, so "list jobs" understated it considerably.files:writeandjobs:writeare documented as not enabled by default, with a note to contact an administrator. That mirrors theapi_token_scopesdefault in the server PR.jobs:writeis described as full-account access. It accepts free-formpre_run/post_runshell that runs as the user, so it reaches every file regardless of thefiles:*scopes granted. The page says so plainly rather than implying containment it does not have.ls()raises rather than returning an empty list for a non-directory, andsubmit_jobneedsparameters(defaulted to{}client-side). Both are easy to document backwards.Conventions
Prose is one line per paragraph, unwrapped, matching the rest of the site. All example paths are neutral placeholders (
/data/alice/...) with no institution-specific mount names.astro.config.mjsgains one line, since this site's sidebar is hand-curated rather than autogenerated — without it the page builds but is unreachable.npm run buildpasses and the page renders in the Features section.@StephanPreibisch @JaneliaSciComp/fileglancer