xian-tech-py 0.4.8__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,156 @@
1
+ Metadata-Version: 2.4
2
+ Name: xian-tech-py
3
+ Version: 0.4.8
4
+ Summary: Python SDK for interacting with the Xian blockchain
5
+ Author: endogen
6
+ License-Expression: MIT
7
+ Requires-Python: >=3.11
8
+ Description-Content-Type: text/markdown
9
+ Requires-Dist: aiohttp<4,>=3.9.0
10
+ Requires-Dist: pynacl<2,>=1.5.0
11
+ Requires-Dist: xian-tech-accounts<0.2,>=0.1.0
12
+ Requires-Dist: xian-tech-runtime-types<0.2,>=0.1.0
13
+ Provides-Extra: hd
14
+ Requires-Dist: bip-utils<3,>=2.9.3; extra == "hd"
15
+ Provides-Extra: eth
16
+ Requires-Dist: eth-account<0.14,>=0.13.4; extra == "eth"
17
+ Requires-Dist: eth-utils<6,>=5.2.0; extra == "eth"
18
+ Provides-Extra: app
19
+ Requires-Dist: fastapi<0.117,>=0.116.0; extra == "app"
20
+ Requires-Dist: uvicorn<0.36,>=0.35.0; extra == "app"
21
+
22
+ # xian-py
23
+
24
+ `xian-py` is the Python SDK for talking to Xian nodes from applications,
25
+ workers, automation jobs, and operator tooling.
26
+
27
+ ## Quick Start
28
+
29
+ Install the SDK:
30
+
31
+ ```bash
32
+ pip install xian-tech-py
33
+ ```
34
+
35
+ The published PyPI package name is `xian-tech-py`. The import package remains
36
+ `xian_py`.
37
+
38
+ Read state and send a transaction:
39
+
40
+ ```python
41
+ from xian_py import Wallet, Xian
42
+
43
+ wallet = Wallet()
44
+
45
+ with Xian("http://127.0.0.1:26657") as client:
46
+ balance = client.token().balance_of(wallet.public_key)
47
+ receipt = client.token().transfer("bob", 5, wallet=wallet, mode="checktx")
48
+ print(balance, receipt.code)
49
+ ```
50
+
51
+ Watch indexed events from a BDS-enabled node:
52
+
53
+ ```python
54
+ import asyncio
55
+
56
+ from xian_py import XianAsync
57
+
58
+
59
+ async def main() -> None:
60
+ async with XianAsync("http://127.0.0.1:26657") as client:
61
+ async for event in client.token().transfers().watch(after_id=0):
62
+ print(event.id, event.data)
63
+
64
+
65
+ asyncio.run(main())
66
+ ```
67
+
68
+ ## Principles
69
+
70
+ - The SDK keeps sync and async clients aligned so the same concepts work in
71
+ scripts, services, and workers.
72
+ - Transaction submission is explicit. Choose a broadcast mode deliberately
73
+ instead of relying on hidden retry or blocking behavior.
74
+ - Read models and projector loops belong in application code, but the SDK owns
75
+ the repetitive plumbing for event polling, cursors, and decoding.
76
+ - Reference apps and examples live in this repo because they demonstrate how to
77
+ integrate Xian into Python systems, but they are not part of the published
78
+ wheel.
79
+
80
+ ## Key Directories
81
+
82
+ - `src/xian_py/`: clients, wallet helpers, transactions, models, and projector primitives
83
+ - `examples/`: service, worker, and automation examples built on the SDK
84
+ - `tests/`: SDK transport, decoding, and integration-shape coverage
85
+ - `docs/`: repo-local notes such as compatibility and backlog items
86
+
87
+ ## What It Can Do
88
+
89
+ - read current state from ABCI query paths and simulate readonly contract calls
90
+ - retrieve the preferred contract source and the canonical runtime code separately
91
+ - create, sign, and broadcast transactions with explicit `async`, `checktx`,
92
+ and `commit` modes
93
+ - wait for final receipts and work with typed transaction, event, block, and
94
+ status models
95
+ - query indexed blocks, transactions, events, state-history, and developer
96
+ reward aggregates from BDS-backed nodes
97
+ - watch blocks and indexed events with resumable cursors
98
+ - use thin helper clients for common patterns such as contract, token, event,
99
+ and state-key access
100
+ - build SQLite-backed read models with the shared projector primitives
101
+
102
+ Indexed event/history queries and projector loops require a BDS-enabled node.
103
+
104
+ ## Core API Layers
105
+
106
+ - `Xian` and `XianAsync`: the primary sync and async clients
107
+ - `client.contract(...)`, `client.token(...)`, `client.events(...)`,
108
+ `client.state_key(...)`: thin helper clients for common application patterns
109
+ - typed models and error classes: predictable result handling instead of raw
110
+ dictionaries everywhere
111
+ - `EventProjector`, `EventSource`, `SQLiteProjectionState`:
112
+ reusable polling/order/checkpoint primitives for local projections
113
+ - `Wallet`: Ed25519 signing helper for Xian transactions
114
+
115
+ ## Typical Use Cases
116
+
117
+ - backend APIs that read state and submit transactions
118
+ - background workers that react to indexed events
119
+ - automation jobs that reconcile or administer contracts
120
+ - local projections that mirror chain activity into an application-owned SQLite
121
+ read model
122
+ - operator or integration scripts that need a clean Python surface over node
123
+ RPCs and indexed queries
124
+
125
+ Optional extras:
126
+
127
+ ```bash
128
+ pip install "xian-tech-py[app]"
129
+ pip install "xian-tech-py[eth]"
130
+ pip install "xian-tech-py[hd]"
131
+ ```
132
+
133
+ Use the `app` extra for the included FastAPI-based examples.
134
+
135
+ ## Example Paths
136
+
137
+ - general SDK examples: [examples/README.md](examples/README.md)
138
+ - credits-ledger reference app: [examples/credits_ledger/README.md](examples/credits_ledger/README.md)
139
+ - registry-approval reference app: [examples/registry_approval/README.md](examples/registry_approval/README.md)
140
+ - workflow-backend reference app: [examples/workflow_backend/README.md](examples/workflow_backend/README.md)
141
+
142
+ ## Validation
143
+
144
+ ```bash
145
+ uv sync --group dev
146
+ uv run ruff check .
147
+ uv run ruff format --check .
148
+ uv run pytest
149
+ ```
150
+
151
+ ## Related Docs
152
+
153
+ - [AGENTS.md](AGENTS.md)
154
+ - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
155
+ - [docs/BACKLOG.md](docs/BACKLOG.md)
156
+ - [docs/API_COMPATIBILITY.md](docs/API_COMPATIBILITY.md)
@@ -0,0 +1,135 @@
1
+ # xian-py
2
+
3
+ `xian-py` is the Python SDK for talking to Xian nodes from applications,
4
+ workers, automation jobs, and operator tooling.
5
+
6
+ ## Quick Start
7
+
8
+ Install the SDK:
9
+
10
+ ```bash
11
+ pip install xian-tech-py
12
+ ```
13
+
14
+ The published PyPI package name is `xian-tech-py`. The import package remains
15
+ `xian_py`.
16
+
17
+ Read state and send a transaction:
18
+
19
+ ```python
20
+ from xian_py import Wallet, Xian
21
+
22
+ wallet = Wallet()
23
+
24
+ with Xian("http://127.0.0.1:26657") as client:
25
+ balance = client.token().balance_of(wallet.public_key)
26
+ receipt = client.token().transfer("bob", 5, wallet=wallet, mode="checktx")
27
+ print(balance, receipt.code)
28
+ ```
29
+
30
+ Watch indexed events from a BDS-enabled node:
31
+
32
+ ```python
33
+ import asyncio
34
+
35
+ from xian_py import XianAsync
36
+
37
+
38
+ async def main() -> None:
39
+ async with XianAsync("http://127.0.0.1:26657") as client:
40
+ async for event in client.token().transfers().watch(after_id=0):
41
+ print(event.id, event.data)
42
+
43
+
44
+ asyncio.run(main())
45
+ ```
46
+
47
+ ## Principles
48
+
49
+ - The SDK keeps sync and async clients aligned so the same concepts work in
50
+ scripts, services, and workers.
51
+ - Transaction submission is explicit. Choose a broadcast mode deliberately
52
+ instead of relying on hidden retry or blocking behavior.
53
+ - Read models and projector loops belong in application code, but the SDK owns
54
+ the repetitive plumbing for event polling, cursors, and decoding.
55
+ - Reference apps and examples live in this repo because they demonstrate how to
56
+ integrate Xian into Python systems, but they are not part of the published
57
+ wheel.
58
+
59
+ ## Key Directories
60
+
61
+ - `src/xian_py/`: clients, wallet helpers, transactions, models, and projector primitives
62
+ - `examples/`: service, worker, and automation examples built on the SDK
63
+ - `tests/`: SDK transport, decoding, and integration-shape coverage
64
+ - `docs/`: repo-local notes such as compatibility and backlog items
65
+
66
+ ## What It Can Do
67
+
68
+ - read current state from ABCI query paths and simulate readonly contract calls
69
+ - retrieve the preferred contract source and the canonical runtime code separately
70
+ - create, sign, and broadcast transactions with explicit `async`, `checktx`,
71
+ and `commit` modes
72
+ - wait for final receipts and work with typed transaction, event, block, and
73
+ status models
74
+ - query indexed blocks, transactions, events, state-history, and developer
75
+ reward aggregates from BDS-backed nodes
76
+ - watch blocks and indexed events with resumable cursors
77
+ - use thin helper clients for common patterns such as contract, token, event,
78
+ and state-key access
79
+ - build SQLite-backed read models with the shared projector primitives
80
+
81
+ Indexed event/history queries and projector loops require a BDS-enabled node.
82
+
83
+ ## Core API Layers
84
+
85
+ - `Xian` and `XianAsync`: the primary sync and async clients
86
+ - `client.contract(...)`, `client.token(...)`, `client.events(...)`,
87
+ `client.state_key(...)`: thin helper clients for common application patterns
88
+ - typed models and error classes: predictable result handling instead of raw
89
+ dictionaries everywhere
90
+ - `EventProjector`, `EventSource`, `SQLiteProjectionState`:
91
+ reusable polling/order/checkpoint primitives for local projections
92
+ - `Wallet`: Ed25519 signing helper for Xian transactions
93
+
94
+ ## Typical Use Cases
95
+
96
+ - backend APIs that read state and submit transactions
97
+ - background workers that react to indexed events
98
+ - automation jobs that reconcile or administer contracts
99
+ - local projections that mirror chain activity into an application-owned SQLite
100
+ read model
101
+ - operator or integration scripts that need a clean Python surface over node
102
+ RPCs and indexed queries
103
+
104
+ Optional extras:
105
+
106
+ ```bash
107
+ pip install "xian-tech-py[app]"
108
+ pip install "xian-tech-py[eth]"
109
+ pip install "xian-tech-py[hd]"
110
+ ```
111
+
112
+ Use the `app` extra for the included FastAPI-based examples.
113
+
114
+ ## Example Paths
115
+
116
+ - general SDK examples: [examples/README.md](examples/README.md)
117
+ - credits-ledger reference app: [examples/credits_ledger/README.md](examples/credits_ledger/README.md)
118
+ - registry-approval reference app: [examples/registry_approval/README.md](examples/registry_approval/README.md)
119
+ - workflow-backend reference app: [examples/workflow_backend/README.md](examples/workflow_backend/README.md)
120
+
121
+ ## Validation
122
+
123
+ ```bash
124
+ uv sync --group dev
125
+ uv run ruff check .
126
+ uv run ruff format --check .
127
+ uv run pytest
128
+ ```
129
+
130
+ ## Related Docs
131
+
132
+ - [AGENTS.md](AGENTS.md)
133
+ - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
134
+ - [docs/BACKLOG.md](docs/BACKLOG.md)
135
+ - [docs/API_COMPATIBILITY.md](docs/API_COMPATIBILITY.md)
@@ -0,0 +1,59 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "xian-tech-py"
7
+ version = "0.4.8"
8
+ description = "Python SDK for interacting with the Xian blockchain"
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ authors = [{ name = "endogen" }]
12
+ requires-python = ">=3.11"
13
+ dependencies = [
14
+ "aiohttp>=3.9.0,<4",
15
+ "pynacl>=1.5.0,<2",
16
+ "xian-tech-accounts>=0.1.0,<0.2",
17
+ "xian-tech-runtime-types>=0.1.0,<0.2",
18
+ ]
19
+
20
+ [project.optional-dependencies]
21
+ hd = [
22
+ "bip-utils>=2.9.3,<3",
23
+ ]
24
+ eth = [
25
+ "eth-account>=0.13.4,<0.14",
26
+ "eth-utils>=5.2.0,<6",
27
+ ]
28
+ app = [
29
+ "fastapi>=0.116.0,<0.117",
30
+ "uvicorn>=0.35.0,<0.36",
31
+ ]
32
+
33
+ [dependency-groups]
34
+ dev = [
35
+ "pytest>=9.0.2,<10",
36
+ "pytest-cov>=7.0.0,<8",
37
+ "ruff>=0.15.6,<0.16",
38
+ ]
39
+
40
+ [tool.setuptools]
41
+ package-dir = {"" = "src"}
42
+
43
+ [tool.setuptools.packages.find]
44
+ where = ["src"]
45
+
46
+ [tool.pytest.ini_options]
47
+ testpaths = ["tests"]
48
+
49
+ [tool.ruff]
50
+ line-length = 80
51
+ target-version = "py311"
52
+
53
+ [tool.ruff.lint]
54
+ select = ["E", "F", "I"]
55
+ ignore = ["E501"]
56
+
57
+ [tool.uv.sources]
58
+ xian-tech-accounts = { path = "../xian-contracting/packages/xian-accounts", editable = true }
59
+ xian-tech-runtime-types = { path = "../xian-contracting/packages/xian-runtime-types", editable = true }
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,96 @@
1
+ from xian_runtime_types.time import to_contract_time
2
+
3
+ from xian_py.application_clients import (
4
+ AsyncContractClient,
5
+ AsyncEventClient,
6
+ AsyncStateKeyClient,
7
+ AsyncTokenClient,
8
+ ContractClient,
9
+ EventClient,
10
+ StateKeyClient,
11
+ TokenClient,
12
+ )
13
+ from xian_py.config import (
14
+ RetryPolicy,
15
+ SubmissionConfig,
16
+ TransportConfig,
17
+ WatcherConfig,
18
+ XianClientConfig,
19
+ )
20
+ from xian_py.exception import (
21
+ AbciError,
22
+ RpcError,
23
+ SimulationError,
24
+ TransactionError,
25
+ TransportError,
26
+ TxTimeoutError,
27
+ XianException,
28
+ )
29
+ from xian_py.models import (
30
+ BdsStatus,
31
+ DeveloperRewardSummary,
32
+ IndexedBlock,
33
+ IndexedEvent,
34
+ IndexedTransaction,
35
+ NodeStatus,
36
+ PerformanceStatus,
37
+ StateEntry,
38
+ TransactionReceipt,
39
+ TransactionSubmission,
40
+ )
41
+ from xian_py.projectors import (
42
+ EventProjector,
43
+ EventProjectorError,
44
+ EventSource,
45
+ SQLiteProjectionState,
46
+ indexed_event_sort_key,
47
+ merged_event_payload,
48
+ )
49
+ from xian_py.run_sync import run_sync
50
+ from xian_py.wallet import Wallet
51
+ from xian_py.xian import Xian
52
+ from xian_py.xian_async import XianAsync
53
+
54
+ __all__ = [
55
+ "AbciError",
56
+ "AsyncContractClient",
57
+ "AsyncEventClient",
58
+ "AsyncStateKeyClient",
59
+ "AsyncTokenClient",
60
+ "BdsStatus",
61
+ "DeveloperRewardSummary",
62
+ "ContractClient",
63
+ "EventClient",
64
+ "EventProjector",
65
+ "EventProjectorError",
66
+ "EventSource",
67
+ "IndexedBlock",
68
+ "IndexedEvent",
69
+ "IndexedTransaction",
70
+ "NodeStatus",
71
+ "PerformanceStatus",
72
+ "RpcError",
73
+ "RetryPolicy",
74
+ "SimulationError",
75
+ "SQLiteProjectionState",
76
+ "StateEntry",
77
+ "SubmissionConfig",
78
+ "TransactionError",
79
+ "TransactionReceipt",
80
+ "TransactionSubmission",
81
+ "TransportConfig",
82
+ "TransportError",
83
+ "TxTimeoutError",
84
+ "WatcherConfig",
85
+ "Xian",
86
+ "XianAsync",
87
+ "XianClientConfig",
88
+ "StateKeyClient",
89
+ "TokenClient",
90
+ "Wallet",
91
+ "XianException",
92
+ "indexed_event_sort_key",
93
+ "merged_event_payload",
94
+ "run_sync",
95
+ "to_contract_time",
96
+ ]