Skip to content

Latest commit

 

History

History
124 lines (101 loc) · 6.81 KB

reference.md

File metadata and controls

124 lines (101 loc) · 6.81 KB

API reference

← Python SDK guide

Every name import syfthub exports, with the first line of its docstring. The docstrings are the reference: help(syfthub.SearchPlan) prints the full one, with its arguments, return values, errors and examples. The sync twin's names are the same classes; see syfthub.sync.

Generated by sdk/python/scripts/gen_api_reference.py; do not edit by hand.

Client

Name Kind What it is
syfthub.AsyncHub class One session with a SyftHub: the catalogue, a search over it, and the money.
syfthub.Hub class Sync twin of AsyncHub: same names, no await.
syfthub.sync module Names for annotating code that uses the sync Hub.

Session and options

Name Kind What it is
syfthub.Budget class Per session, across searches: one cap per currency, and spend tracked per currency.
syfthub.CircuitBreaker class When a Space host is left alone: after failures in a row, for cooldown seconds.
syfthub.Identity class Who is signed in: the Hub user's name and email.
syfthub.Options class One per AsyncHub; applies to the whole client.
syfthub.Retry class Network errors and 5xx only; never a 403 rate limit.
syfthub.Timeout class How long the SDK waits on the network, in seconds.

Sources

Name Kind What it is
syfthub.Access class What the source's access policies say about one caller.
syfthub.Connection class One entry of EndpointPublicResponse.connect[].
syfthub.Policy class One entry of EndpointPublicResponse.policies[].
syfthub.Price class One payment policy's price: an amount per request or per document.
syfthub.Pricing class Read off a source's payment policies; nothing added.
syfthub.QuerySchema class What a query may carry, as the publisher declared it.
syfthub.Source class One endpoint in the Hub catalogue.
syfthub.SourceList class What hub.sources.list() returns.

Plans and pre-flight

Name Kind What it is
syfthub.AccessDenied class The sources' access policy shuts this caller out; rule is the pattern that did.
syfthub.Action class Base: one per cause, not per source. steps are plain-English steps to resolve it.
syfthub.CircuitOpen class The sources' host is cooling down after failures, until reopens_at.
syfthub.OverBudget class The estimate crosses the session's cap for its currency; hub.set_budget lifts it.
syfthub.PlanRow class One source as pre-flight saw it.
syfthub.Preflight class What plan.preflight() found.
syfthub.SearchPlan class What hub.search composes and execute sends.
syfthub.TopUp class A prepaid wallet is short.

Filters

Name Kind What it is
syfthub.Condition class One test on one field: field op value.
syfthub.F class A field to filter on. Apply an operator to get a Condition.
syfthub.FieldFilterSpec class What a query may do with one field: its published type and operators.
syfthub.Filter alias A Condition or a Group: anything F builds.
syfthub.FilterSchema class query_schema.filters as the Space published it.
syfthub.Group class Conditions or groups joined by and or or.
syfthub.SourceSelection class A source named in a plan, with the filter it is queried with.

Results

Name Kind What it is
syfthub.Document class One passage a source returned, with its score and metadata.
syfthub.Results class What plan.execute() returns: one SourceResult per source, and views over them.
syfthub.SourceResult class One source's row in Results: what came back, or why nothing did, and what it cost.

Money

Name Kind What it is
syfthub.Bundle class One purchasable top-up, from the payment policy's bundles[].
syfthub.Money class An exact amount in one currency.

Wallets

Name Kind What it is
syfthub.Charge class One MPP 402 challenge.
syfthub.ChargeEntry class One policy_metadata.entries[] item from a Space response.
syfthub.Invoice class A top-up invoice from the Space's payment route.
syfthub.RateLimit class From the Space's rate-limit policy entry (details) or response headers.
syfthub.Wallet class A prepaid wallet with a publisher. Not frozen: refresh() updates the balance in place.

Enums

Name Kind What it is
syfthub.ActionKind enum The cause an Action resolves.
syfthub.AuthMethod enum How a session signed in.
syfthub.InvoiceStatus enum The Space's invoice lifecycle: pending -> (processing ->) paid, or expired / cancelled.
syfthub.Outcome enum Execute, per row.
syfthub.PolicyType enum Policy types the SDK knows. Policy.type stays a string so unknown types still parse.
syfthub.PriceUnit enum What one price covers: a request, or a document returned.
syfthub.Rail enum How a source is paid; read off its payment policy.
syfthub.Reason enum Why a row was held, rejected or failed.
syfthub.ReturnKind enum What a Results holds: passages, summaries, both, or nothing.
syfthub.SourceType enum What a source answers with. Values are the Hub's endpoint types.
syfthub.Verdict enum Pre-flight, per row. The first two are sent; the rest are held.

Errors

Name Kind What it is
syfthub.ActionRequired exception execute(strict=True) with open actions. Carries .actions.
syfthub.AuthError exception Login failed, or the token expired and could not be re-minted.
syfthub.ConfigurationError exception Bad URL, no token and no credentials, or invalid Options.
syfthub.FilterError exception A filter the source's published schema refuses: which field, and why.
syfthub.HubUnreachable exception The Hub itself could not be reached after retries.
syfthub.PaymentError exception Base class for payment faults.
syfthub.PaymentFailed exception The Hub wallet pay call or the Space invoice route returned an error.
syfthub.PaymentTimeout exception invoice.wait_paid ran out of time.
syfthub.SourceNotFound exception hub.sources.get on a path the Hub does not know.
syfthub.StaleSnapshot exception from_dict on a dict written by an incompatible SDK version.
syfthub.SyftHubError exception Base class for every error the SDK raises.
syfthub.ValidationError exception A caller-supplied value is out of range or malformed.