Read a connected source in Python

A source is a table your project reads from an upstream system — for example a SQL table of wells your organisation keeps. Once you have selected it in the Workspace, you can read its rows from Python or the ophiolite command line with a project access key: no database credential, no HTTP or checksum code of your own. client is an ophiolite.Client for your project — see Build on Ophiolite for a key and the SDK.

A source row is not a project well. How the two relate, and which fields each gives you, is in Source rows and project wells.

List the sources you selected

for source in client.sources():
    print(source.id, source.name, source.profile, source.state, source.revision[:12])

You see the selections you made yourself; a selection another member made is not listed. Every kind of source is listed; this release reads SQL well tables (sql-wells/1).

Read one, verified

Pick a source by its id from the listing (a name never selects one):

source = client.source(source_id)
snapshot = source.read(expect_revision=source.revision)
frame = snapshot.to_frame()
print(len(frame), "rows in", frame.attrs["crs"], "at revision", frame.attrs["revision"][:12])

Before any row is returned, the SDK checks that the server returned the source you selected and that the payload’s SHA-256 equals both the manifest’s checksum and the revision. With expect_revision, a different revision is refused and no rows are given — useful when you must work on exactly the version you reviewed. Coordinates are in the CRS the source declares (frame.attrs["crs"]); nothing is converted.

to_frame() gives the mapped view (well identifier, name, operator and depth when they are mapped, x and y); to_frame(original=True) gives every column of the table with its values as stored.

Keep a copy

frame.to_csv("wells-from-source.csv", index=False)

The file is your own copy: it is not shared with anyone and not kept up to date.

From the command line

ophiolite sources list
ophiolite sources describe SOURCE_ID --json
ophiolite sources read SOURCE_ID --expect-revision REVISION --out wells.csv

describe shows the columns, the mapping, the CRS and the row count; it reads the whole table once to verify it. read --json prints the rows without needing pandas; --out writes a .csv or .json file and will not replace an existing one unless you add --force. The exit codes and JSON shapes are in the command line reference.

When a read is refused

You see	What it means	What to do
source-revision-differs	The source changed since the revision you expected	Read it again, and decide whether the new revision is the one you want
SOURCE_REVISION_UNAVAILABLE	The table changed upstream and the revision you hold can no longer be read	Read it again when the Workspace shows the new version
SOURCE_NEEDS_REVIEW	The mapping needs review, or the table is over the server’s size bound (the message says which)	Review the source’s mapping in the Workspace
SOURCE_DETACHED	The selection was removed from the project	Ask a project administrator to resume it
source-not-supported	Not a SQL well table	List it; reading other kinds comes later

The full list, with each remedy, is in Source rows and project wells.