Skip to main content

fragment-python

Fragment is the Ledger API for engineers that move money. Stop wrangling payment tables, debugging balance errors, and hacking together data pipelines. Start shipping the features that make a difference.

See CHANGELOG.md for release notes and upgrade guidance.

Installation

Using pip:

pip install fragment-python

Using poetry:

poetry add fragment-python

Usage

Get started by instantiating a Client from fragment.sdk.client. You can generate credentials using the Fragment dashboard

from fragment.sdk.client import Client

graphql_client = Client(
    client_id="<client id from the dashboard>",
    client_secret="<client secret from the dashboard>",
    api_url="<api url from the dashboard>",
    auth_url="<auth url from the dashboard>",
    auth_scope="<auth scope from the dashboard>",
  )

async def print_schema():
  get_schema_result = await graphql_client.get_schema("<Your schema key here>")
  print(get_schema_result.schema_.json())

import asyncio
loop = asyncio.get_event_loop()
loop.run_until_complete(print_schema())

Read the Using custom queries section to learn how to use your own GraphQL queries with the SDK.

Using a synchronous client

If you prefer using a synchronous client instead of an async one, then:

from fragment.sync_sdk.client import Client

graphql_client = Client(
    client_id="<client id from the dashboard>",
    client_secret="<client secret from the dashboard>",
    api_url="<api url from the dashboard>",
    auth_url="<auth url from the dashboard>",
    auth_scope="<auth scope from the dashboard>",
  )

get_schema_result = graphql_client.get_schema("<Your schema key here>")
print(get_schema_result.schema_.json())

Examples

Post a Ledger Entry

To post a Ledger Entry defined in your Schema:

await graphql_client.add_ledger_entry(
  ik="some-ik",
  ledger_ik="your-ledger-ik",
  type_="user_funds_account",
  posted="1968-01-01T16:45:00Z",
  parameters=dict(
    user_id="user-1",
    funding_amount="20000",
  )
)

Post a batch of Ledger Entries

To post a batch of Ledger Entries atomically:

from fragment.sdk.typed_entries import UserFundsAccountV1

await graphql_client.add_ledger_entries(
  entries=[
    UserFundsAccountV1(
      ik="some-ik-1",
      ledger_ik="your-ledger-ik",
      posted="1968-01-01T16:45:00Z",
      user_id="user-1",
      funding_amount="20000",
    ),
    UserFundsAccountV1(
      ik="some-ik-2",
      ledger_ik="your-ledger-ik",
      posted="1968-01-01T16:45:00Z",
      user_id="user-2",
      funding_amount="20000",
    ),
  ]
)

Construct the entries in the batch using the strongly-typed models for your Schema in the typed_entries module of your generated client.

Read a Ledger Account's Balance

To read a Ledger Account's balance:

from fragment.sdk.enums import CurrencyCode
from fragment.sdk.input_types import CurrencyMatchInput

await graphql_client.get_ledger_account_balance(
  ledger_ik="your-ledger-ik",
  path="liabilities/user:user-1/available",
  balance_currency=CurrencyMatchInput(code=CurrencyCode.USD),
)

Using custom queries

While the SDK comes with GraphQL queries out of the box, you may want to customize these queries for your product. In order to do that:

  1. Define your custom GraphQL queries in a GraphQL file. For example, in queries/custom-queries.graphql:
query getSchemaName($key: SafeString!) {
  schema(schema: { key: $key }) {
    key
    name
  }
}
  1. Run fragment-python-client-codegen to generate the GraphQL SDK client. GraphQL named queries are converted to snake_case to conform to Python's code conventions. Optionally, pass the --sync flag to generate a synchronous client instead of the default async GraphQL client.
fragment-python-client-codegen \
  --input-dir libs/fragment/queries/ \
  --target-package-name=custom_queries_package \
  --output-dir=libs/fragment
  1. Use the client from the generated package in your product! Apart from the custom query methods, this client is functionally identical to fragment.sdk.client.Client
from .libs.fragment.custom_queries_package.client import Client

graphql_client = Client(
    client_id="<client id from the dashboard>",
    client_secret="<client secret from the dashboard>",
    api_url="<api url from the dashboard>",
    auth_url="<auth url from the dashboard>",
    auth_scope="<auth scope from the dashboard>",
  )

async def print_schema_name():
  # Note that getSchemaName is converted to snake_case automatically
  response = await graphql_client.get_schema_name("<Your Schema Key>")
  print(response.schema_.key)

import asyncio
loop = asyncio.get_event_loop()
loop.run_until_complete(print_schema_name())

Metadata

Release files for fragment-python 1.4.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fragment-python 1.4.3
File Size Uploaded Provenance Actions
fragment_python-1.4.3.tar.gz 98.9 kB Without provenance Details for fragment_python-1.4.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fragment-python 1.4.3
File Interpreter ABI Platform Actions
fragment_python-1.4.3-py3-none-any.whl Python 3 none any Details for fragment_python-1.4.3-py3-none-any.whl

Total release size: 249.5 kB

Release files / fragment_python-1.4.3.tar.gz

Download URL fragment_python-1.4.3.tar.gz
Size 98.9 kB
Tags Source
SHA-256 checksum
How to use checksums
0e53d40c103d7e4f3fbf0042a0c242eab376dadb78f162b1e1db1824e1033c37
BLAKE2b-256 checksum
How to use checksums
43c53c18a904495de82a46f230572e4d5d29aa3a733a1c5bacac287a205b40d2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.5.1 CPython/3.10.14 Linux/6.17.0-1022-azure

Release files / fragment_python-1.4.3-py3-none-any.whl

Download URL fragment_python-1.4.3-py3-none-any.whl
Size 150.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b7598596ba47c34839ada3b6512e216d25401ff4cd681c10c888856916b1cb1a
BLAKE2b-256 checksum
How to use checksums
df14b45f9242b24745b46780f97eda100f94d4bee81c2525a83e81b20adb970c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.5.1 CPython/3.10.14 Linux/6.17.0-1022-azure

Security for fragment-python 1.4.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page