b24api 2.2.0__tar.gz → 2.4.2__tar.gz

{b24api-2.2.0 → b24api-2.4.2}/PKG-INFO

@@ -1,16 +1,35 @@
 Metadata-Version: 2.4
 Name: b24api
-Version: 2.2.0
+Version: 2.4.2
 Summary: Bitrix24 API
+Author-email: Shkarupa Alex <shkarupa.alex@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/shkarupa-alex/b24api
+Project-URL: Repository, https://github.com/shkarupa-alex/b24api
+Project-URL: Issues, https://github.com/shkarupa-alex/b24api/issues
+Keywords: bitrix24,rest,api,client,async,httpx,batch,pagination
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: httpx[http2]>=0.28.1
-Requires-Dist: pydantic>=2.11.7
+Requires-Dist: httpx[http2]<0.29,>=0.28.1
+Requires-Dist: h2<4.5,>=4.3.0
+Requires-Dist: hpack<4.3,>=4.1.0
+Requires-Dist: pydantic>=2.12.0
 Requires-Dist: pydantic-settings>=2.10.1
 Dynamic: license-file
 
-# b24api 2.x
+# b24api 3.x
 
 `b24api` is a thin asynchronous Bitrix24 REST client for Python 3.12+. It knows how to send
 requests, split logical batches, traverse lists, retry safely, preserve caller correlation and
@@ -27,16 +46,42 @@ export BITRIX24_API_WEBHOOK_URL='https://portal.example/rest/.../'
 Keep the webhook out of source, logs and command arguments. Reuse one client for a related unit of
 work so its HTTP/2 connection pool and rate state are reused.
 
-<!-- tested: tests/client_v2_test.py::test_call_and_call_response_have_stable_detached_types -->
+## Quickstart
+
+<!-- tested: tests/readme_test.py::test_quickstart_runs_exactly_against_a_scripted_portal -->
 ```python
+import os
+
 from b24api import Bitrix24, Request
 
-async with Bitrix24() as client:
-    profile = await client.call(Request("profile"))
+async with Bitrix24.from_webhook(os.environ["BITRIX24_API_WEBHOOK_URL"]) as client:
+    deals = client.iter_list(Request.bare("crm.deal.list", {"select": ["ID", "TITLE"]}))
+    async for deal in deals:
+        print(deal["ID"], deal["TITLE"])
+    print(deals.report.state)
+```
+
+Four things are at work:
+
+- **The client.** `Bitrix24.from_webhook()` checks the URL and owns the connection pool it opens;
+  `async with` closes it. `Bitrix24()` reads the same URL from the environment.
+- **The request.** `Request.bare()` names a REST method and its parameters and sends them to the
+  classic `/rest/` endpoint. The route is always explicit: `Request.v3()` targets the V3 API.
+- **`iter_list()`.** It walks the list page by page and reads one more, empty, page to confirm
+  the end.
+- **The report.** `deals.report` says how the traversal ended. `completed` means every page was
+  read; a traversal that stops early or fails records why.
+
+A single call returns the decoded `result`:
+
+<!-- tested: tests/readme_test.py::test_quickstart_runs_exactly_against_a_scripted_portal -->
+```python
+users = await client.call(Request.bare("user.get", {"ID": 1}))
 ```
 
-The client owns its default transport. An injected transport remains caller-owned. `aclose()` is
-idempotent and closes active streams before the owned transport.
+The client owns the transport it creates. An injected transport remains caller-owned. `aclose()` is
+idempotent and closes active streams before the owned transport. To prove that no row is missing or
+repeated, give the traversal an identity (see [Choosing a list operation](#choosing-a-list-operation)).
 
 ## Direct calls
 
@@ -48,15 +93,17 @@ The operation is explicit and never hides malformed JSON by falling back to byte
 
 <!-- tested: tests/client_findings_3_test.py::test_binary_call_returns_every_success_byte_without_json_sniffing -->
 ```python
-archive = await client.call_bytes(Request("example.export.download", replay_safety=ReplaySafety.SAFE))
+from b24api import RouteKind
+archive = await client.call_bytes(Request("example.export.download", replay_safety=ReplaySafety.SAFE, route=RouteKind.BARE))
 payload = archive.body
 ```
 
 <!-- tested: tests/client_v2_test.py::test_call_and_call_response_have_stable_detached_types -->
 ```python
+from b24api import RouteKind
 from b24api import ReplaySafety
 
-request = Request("example.item.get", {"id": 7}, ReplaySafety.SAFE)
+request = Request("example.item.get", {"id": 7}, ReplaySafety.SAFE, route=RouteKind.BARE)
 decoded = await client.call(request)
 response = await client.call_response(request)
 ```
@@ -69,10 +116,17 @@ may already have reached Bitrix:
 | Value | Meaning | After possible dispatch |
 |---|---|---|
 | `SAFE` | Repeating the request cannot create a second business effect. Typical reads and explicitly idempotent operations belong here. | Automatic retry is allowed within policy budgets. |
-| `UNSAFE` | Repeating the request is known to risk a duplicate effect, for example creating an entity without an idempotency key. | No automatic replay; the caller receives an ambiguous-execution error and reconciles state. |
+| `UNSAFE` | Repeating the request is known to risk a duplicate effect, for example creating an entity without an idempotency key. | No automatic replay; the caller receives an ambiguous-execution error and reconciles state. It is retried only when the failure proves it did not run. |
 | `UNKNOWN` | The caller has not established whether replay is safe. This is the default. | Same conservative behavior as `UNSAFE`, while diagnostics preserve that safety was unknown rather than known unsafe. |
 
-A failure proved to occur before dispatch may still be retried. Method names never imply safety;
+A failure that proves the request did not run is retried whatever its safety: a transport failure
+before dispatch, or a refusal listed in `AmbiguityPolicy`, which by default is an unstructured 423, 425
+or 429 (`refusal_http_statuses`) or a `QUERY_LIMIT_EXCEEDED` / `OPERATION_TIME_LIMIT` refusal
+(`refusal_api_codes`). A code or status added only to `RetryPolicy` is retried for `SAFE` work alone.
+A physical batch applies these rules to each command: after a failure, only the commands that
+may run again are sent again, in a smaller batch, and an `UNSAFE` command of a batch that may have run
+arrives as unknown. Replay rounds spend the same attempt and retry-time budget as the sends before
+them. Method names never imply safety;
 mark a request `SAFE` only when the operation's semantics justify it.
 
 Use `ExecutionPolicy` to narrow attempts or resource budgets for one operation:
@@ -85,6 +139,22 @@ one_attempt = ExecutionPolicy(max_attempts_per_request=1)
 result = await client.call(request, policy=one_attempt)
 ```
 
+A `policy=` argument replaces the client's default policy wholesale; fields are never merged. The
+client default is `ExecutionPolicy.from_settings(settings)`: the library defaults with
+`max_retry_elapsed_per_request` taken from `Settings.http_timeout` (30 s by default, while a bare
+`ExecutionPolicy()` allows 120 s). To change one field and keep the configured timeout, derive the
+per-call policy from that default:
+
+<!-- tested: tests/settings_test.py::test_a_per_call_policy_replaces_the_client_default_without_merging -->
+```python
+import dataclasses
+
+from b24api import ExecutionPolicy
+
+one_attempt = dataclasses.replace(ExecutionPolicy.from_settings(settings), max_attempts_per_request=1)
+result = await client.call(request, policy=one_attempt)
+```
+
 ## Logical batch and correlation
 
 `batch()` accepts an arbitrary-length synchronous or asynchronous command source. It consumes the
@@ -97,11 +167,12 @@ matching a result to the object, file, chat or database row that produced its re
 
 <!-- tested: tests/client_v2_test.py::test_logical_batch_is_unbounded_ordered_and_correlation_is_strictly_off_wire -->
 ```python
-from b24api import Command, CommandSuccess
+from b24api import RouteKind
+from b24api.contracts import Command, CommandSuccess
 
 commands = (
     Command(
-        Request("example.item.get", {"id": item_id}, ReplaySafety.SAFE),
+        Request("example.item.get", {"id": item_id}, ReplaySafety.SAFE, route=RouteKind.BARE),
         correlation=item_id,
     )
     for item_id in source_ids
@@ -118,7 +189,7 @@ async with client.batch(commands, batch_size=25) as stream:
 
 <!-- tested: tests/client_v2_test.py::test_batch_outcomes_retains_typed_failure_without_halting_later_commands -->
 ```python
-from b24api import CommandFailure, CommandNotExecuted, CommandOutcomeUnknown
+from b24api.contracts import CommandFailure, CommandNotExecuted, CommandOutcomeUnknown
 
 async with client.batch_outcomes(commands) as stream:
     async for outcome in stream:
@@ -151,7 +222,16 @@ exact `limit_path`; the client never guesses method-specific parameter names.
 
 ### List traversal comparison
 
-![List traversal comparison](list-traversal-comparison.svg)
+![List traversal comparison](https://raw.githubusercontent.com/shkarupa-alex/b24api/master/list-traversal-comparison.svg)
+
+The animation replays traces executed against a scripted portal with 1,000 dense IDs at 50 rows
+per page. `iter_list` sends 20 pages and one empty confirmation (21 HTTP). `iter_list_counted` sends
+the head and one batch of 19 pages (2 HTTP). `iter_list_keyset` in auto mode selects range
+execution: it reads both ends of the range in one batch, the 19 ranges between them in a second, and
+confirms the end with one call for `ID > 1000` (3 HTTP). A `BoundedIdentityRange` with a qualified
+upper ID needs no confirmation: sequential execution stops when it receives that ID. On a real portal
+auto chooses from the observed geometry, so the plan and its request count can differ; the report's
+`keyset_selection` says which plan ran.
 
 ### Sequential offset
 
@@ -166,6 +246,7 @@ control this strategy's completion. Exact database implementation is endpoint-sp
 
 <!-- tested: tests/client_v2_test.py::test_iter_list_is_sequential_mechanics_only_and_report_is_post_cleanup -->
 ```python
+from b24api import RouteKind
 from b24api import IdentityCoercion, IdentitySpec, ResultSelector
 
 identity = IdentitySpec(
@@ -176,7 +257,7 @@ identity = IdentitySpec(
 )
 
 stream = client.iter_list(
-    Request("example.item.list", replay_safety=ReplaySafety.SAFE),
+    Request("example.item.list", replay_safety=ReplaySafety.SAFE, route=RouteKind.BARE),
     selector=ResultSelector(("items",)),
     identity=identity,
 )
@@ -194,10 +275,11 @@ sequence and records that degradation in the operation report.
 
 <!-- tested: tests/client_findings_3_test.py::test_shape_rejection_is_retained_as_zero_admission_page_evidence -->
 ```python
-from b24api import ResultCollectionShape
+from b24api import RouteKind
+from b24api.contracts import ResultCollectionShape
 
 stream = client.iter_list(
-    Request("example.dictionary.list", replay_safety=ReplaySafety.SAFE),
+    Request("example.dictionary.list", replay_safety=ReplaySafety.SAFE, route=RouteKind.BARE),
     selector=ResultSelector(("items",)),
     collection_shape=ResultCollectionShape.MAPPING_VALUES,
 )
@@ -214,8 +296,9 @@ bounded physical batches.
 
 <!-- tested: tests/client_v2_test.py::test_counted_traversal_preserves_frozen_request_shape_and_exact_identity -->
 ```python
+from b24api import RouteKind
 stream = client.iter_list_counted(
-    Request("example.item.list", replay_safety=ReplaySafety.SAFE),
+    Request("example.item.list", replay_safety=ReplaySafety.SAFE, route=RouteKind.BARE),
     selector=ResultSelector(("items",)),
     identity=identity,
     page_size=50,
@@ -226,6 +309,16 @@ stream = client.iter_list_counted(
 Use it only when `total` is exact for the supplied filter and offset pages are stable. Any missing
 range, overlap, duplicate identity or total contradiction raises `IncompleteTraversalError`.
 
+A filtered call that matches nothing may omit `total` entirely, as `user.get` does with
+`result: []`. A first page with no rows, no `next` and no usable `total` (missing, `null`, or the
+`-1` unknown sentinel) therefore completes as an observed empty source after that one request: the
+report is `completed` and `exhausted`, but its assurance is `mechanics_only` (`identity_exact` with an
+identity), never a count-matched claim, and no total is invented. A first page that reports
+`total: 0` keeps the count-matched result. Rows without a usable total, a remaining `next`, a
+positive total with no rows, a fixed step, or a `ConsistencyPolicy` whose `confirmation_policy` is
+`QUALIFIED_TOTAL` (from `b24api.contracts.policy.ConfirmationPolicy`) stay strict and raise
+`IncompleteTraversalError`.
+
 Physical batching reduces HTTP exchanges, but does not suppress server-side COUNT in ordinary
 counted list subrequests. Each command still performs its own offset page retrieval and associated
 total calculation on the server. Do not confuse batching these commands with a no-count traversal.
@@ -249,14 +342,19 @@ Static incompatibility with the auto contract raises `CapabilityError` from the
 `iter_list_keyset(...)` call before iteration begins. A portal that accepts but contradicts the
 declared controls fails before emission with `IncompleteTraversalError`; auto never restarts that
 operation silently. `KeysetTraversal` inside reference traversal remains sequential-only. The
-terminal report now includes `keyset_execution` for omitted-execution keyset calls so consumers can
-see the requested and selected plan.
+terminal report carries a compact `keyset_selection` (`requested_kind`, `selected_kind`, `reason`)
+for every keyset traversal. A `page_stop` callback needs the ordered page stream, so auto reports
+`AUTO`, `SEQUENTIAL`, `PAGE_STOP`; an explicit `SequentialKeysetExecution()` reports
+`EXPLICIT_SEQUENTIAL`. The detailed `keyset_execution` report is present only when the fast path ran.
 
 Use `await client.verify_keyset_capability(...)` as a development/CI/staging guard on a stable
 representative fixture. It performs five strict-bound checks and returns only a `VERIFIED` report;
 unsupported and inconclusive verdicts raise `KeysetCapabilityError`. The ordinary
 `iter_list_keyset()` remains a separate caller-asserted operation with zero verifier canaries and
 may emit a partial prefix before a late endpoint contradiction is detected.
+Keep the guard beside the traversal, for example under
+`if os.environ.get("ENV") != "PROD":`; set `ENV=PROD` only after qualifying the exact portal,
+credentials, method, request/filter, identity, ordering representation, and page cap.
 
 Every list operation also accepts an immutable `PageAdapter` strategy. The adapter synchronously
 maps selected frozen items using sibling result metadata while preserving cardinality, order and
@@ -269,16 +367,33 @@ record the selected strategy and reason: unbounded auto continuation has the sam
 
 <!-- tested: tests/keyset_fast_test.py::test_omitted_execution_defaults_to_auto -->
 ```python
-from b24api import KeysetSpec, ParameterPath
+import os
+
+from b24api import KeysetSpec, ParameterPath, ReplaySafety, Request, ResultSelector, RouteKind
+
+request = Request("example.item.list", replay_safety=ReplaySafety.SAFE, route=RouteKind.BARE)
+selector = ResultSelector(("items",))
+keyset = KeysetSpec(
+    filter_path=ParameterPath(("filter",)),
+    order_path=ParameterPath(("order",)),
+)
+
+if os.environ.get("ENV") != "PROD":
+    # Accepting an ID filter does not prove strict bounds or ordering.
+    await client.verify_keyset_capability(
+        request,
+        selector=selector,
+        identity=identity,
+        page_size=50,
+        keyset=keyset,
+    )
 
 stream = client.iter_list_keyset(
-    Request("example.item.list", replay_safety=ReplaySafety.SAFE),
-    selector=ResultSelector(("items",)),
+    request,
+    selector=selector,
     identity=identity,
-    keyset=KeysetSpec(
-        filter_path=ParameterPath(("filter",)),
-        order_path=ParameterPath(("order",)),
-    ),
+    page_size=50,
+    keyset=keyset,
 )
 ```
 
@@ -289,10 +404,11 @@ message-list methods.
 
 <!-- tested: tests/client_v2_test.py::test_keyset_and_cursor_are_explicit_strict_alternatives -->
 ```python
+from b24api import RouteKind
 from b24api import CursorSpec, ParameterPath
 
 stream = client.iter_list_cursor(
-    Request("example.message.list", replay_safety=ReplaySafety.SAFE),
+    Request("example.message.list", replay_safety=ReplaySafety.SAFE, route=RouteKind.BARE),
     selector=ResultSelector(("items",)),
     cursor=CursorSpec(
         parameter_path=ParameterPath(("LAST_ID",)),
@@ -310,10 +426,10 @@ boundary, use an application-owned direct-call workflow or supply a unique tie-b
 For multiple parent-bound cursor chains, `iter_cursors()` keeps cursor progress and correlation
 isolated per binding while ready pages share the physical batch queue.
 
-![Cursor batching across independent chats](cursor-batching.svg)
+![Cursor batching across independent chats](https://raw.githubusercontent.com/shkarupa-alex/b24api/master/cursor-batching.svg)
 
-See [architecture](docs/architecture.md), [migration](docs/migration.md),
-[performance](docs/performance.md), and [endpoint recipes](docs/recipes.md) for the complete
+See [architecture](https://github.com/shkarupa-alex/b24api/blob/master/docs/architecture.md), [migration](https://github.com/shkarupa-alex/b24api/blob/master/docs/migration.md),
+[performance](https://github.com/shkarupa-alex/b24api/blob/master/docs/performance.md), and [endpoint recipes](https://github.com/shkarupa-alex/b24api/blob/master/docs/recipes.md) for the complete
 contracts and selection guidance.
 
 ### One list method across many parent entities
@@ -322,19 +438,13 @@ contracts and selection guidance.
 client remains unaware of entity types: a binding can represent a deal, lead, chat or any other
 caller-defined parent.
 
-![Reference batching across leads and deals](references-batching.svg)
+![Reference batching across leads and deals](https://raw.githubusercontent.com/shkarupa-alex/b24api/master/references-batching.svg)
 
 <!-- tested: tests/client_v2_test.py::test_bound_references_apply_nested_updates_off_wire_and_emit_exact_completion -->
 ```python
-from b24api import (
-    BatchDispatch,
-    Binding,
-    ParameterPath,
-    ParameterUpdate,
-    ReferenceComplete,
-    ReferenceItem,
-    SequentialTraversal,
-)
+from b24api import RouteKind
+from b24api import BatchDispatch, Binding, ParameterPath, ParameterUpdate, SequentialTraversal
+from b24api.contracts import ReferenceComplete, ReferenceItem
 
 bindings = (
     Binding(
@@ -346,7 +456,7 @@ bindings = (
 )
 
 stream = client.iter_references(
-    Request("example.comment.list", replay_safety=ReplaySafety.SAFE),
+    Request("example.comment.list", replay_safety=ReplaySafety.SAFE, route=RouteKind.BARE),
     bindings,
     traversal=SequentialTraversal(selector=ResultSelector(("items",)), identity=identity),
     dispatch=BatchDispatch(batch_size=25, concurrency=2),
@@ -366,6 +476,7 @@ under different parents are not conflated.
 
 <!-- tested: tests/client_v2_test.py::test_bound_references_apply_nested_updates_off_wire_and_emit_exact_completion -->
 ```python
+from b24api import RouteKind
 from b24api import (
     Binding,
     CursorSpec,
@@ -387,7 +498,7 @@ chat_bindings = (
 )
 
 messages = client.iter_references(
-    Request("example.message.list", replay_safety=ReplaySafety.SAFE),
+    Request("example.message.list", replay_safety=ReplaySafety.SAFE, route=RouteKind.BARE),
     chat_bindings,
     traversal=CursorTraversal(
         selector=ResultSelector(("items",)),
@@ -430,13 +541,19 @@ and publish the same final report where the Python exception type permits it.
 ## Resource boundaries
 
 `ExecutionPolicy` bounds requests, pages, elapsed time, attempts, decompressed response bytes,
-buffered commands and rows, direct concurrency and active references. The default response ceiling
-is 16 MiB and is enforced while streaming, before JSON decoding.
-
-Sequential and counted exact traversal retain observed identities in memory. There is no database,
-spill file or identity-count refusal. Crossing 100,000 distinct identities emits one
-`RuntimeWarning`; exact tracking continues. Strict keyset and cursor traversal retain only
-monotonic progression state when sufficient.
+buffered commands and rows, retained unordered identity keys, direct concurrency and active
+references. The default response ceiling is 16 MiB and is enforced while streaming, before JSON
+decoding.
+
+Sequential, counted, and multi-reference exact traversal retain at most `max_identity_keys`
+observed identities per operation in memory (100,000 by default). All active reference bindings
+share that ceiling. A page that would exceed it is rejected atomically with typed budget evidence.
+Set a larger finite ceiling when the expected aggregate cardinality is known, or pass
+`identity_store=` to `iter_list`/`iter_list_counted` so a caller-owned `IdentityStore` (for example a
+SQLite table keyed by `identity_store_key(...)`) proves uniqueness while in-process identity memory
+stays bounded by one page; the client never closes that store. Repeated-page detection still keeps
+one short fingerprint per page, so raise `max_pages` deliberately for very long traversals.
+Strict keyset and cursor traversal retain only monotonic progression state when sufficient.
 
 ## CLI
 
@@ -445,10 +562,10 @@ errors go to stderr. Credentials come only from `Settings` and cannot be passed
 
 <!-- tested-console: tests/cli_test.py::test_call_routes_replay_safety_and_keeps_success_data_on_stdout -->
 ```console
-b24api call profile
-b24api call example.item.get --params '{"id":7}' --raw --replay-safety safe
-b24api list example.item.list --params @params.json
-b24api list example.item.list --strategy counted --contract @counted-contract.json
+b24api call profile --route bare
+b24api call example.item.get --route bare --params '{"id":7}' --raw --replay-safety safe
+b24api list example.item.list --route bare --params @params.json
+b24api list example.item.list --route bare --strategy counted --contract @counted-contract.json
 ```
 
 The `--raw` CLI option selects the response envelope; it does not alter the Python API. Advanced
@@ -483,21 +600,22 @@ uv run --with memray memray stats /tmp/b24api.bin
 ```
 
 These deterministic fixtures characterize local resources and network shape; they are not live
-portal latency admission. See [docs/performance.md](docs/performance.md) for current measurements
-and [docs/architecture.md](docs/architecture.md) for guarantees and ownership boundaries.
+portal latency admission. See [docs/performance.md](https://github.com/shkarupa-alex/b24api/blob/master/docs/performance.md) for current measurements
+and [docs/architecture.md](https://github.com/shkarupa-alex/b24api/blob/master/docs/architecture.md) for guarantees and ownership boundaries.
 
-Projects moving from an earlier API surface can use [docs/migration.md](docs/migration.md).
+Projects moving from an earlier API surface can use [docs/migration.md](https://github.com/shkarupa-alex/b24api/blob/master/docs/migration.md).
 
 ## Verification
 
 ```console
 uv sync --frozen
-.venv/bin/pytest -q -p no:cacheprovider
-.venv/bin/ruff check . --no-fix --no-cache
-.venv/bin/ruff format --check . --no-cache
-.venv/bin/mypy --strict b24api tools/b24api_evidence
+make qc
 git diff --check
 ```
 
+`make qc` runs the lint, type and default test checks that CI blocks on. It leaves out the internal
+benches (the pytest marker `slow`: the evidence harness contracts and the 50k/100k-scale runs, which
+take several minutes). `make bench` runs them, and so does the blocking CI job `slow`.
+
 The wheel regression installs into an isolated environment, executes the `b24api` entry point and
 checks that tests, live/evidence tooling and credentials are excluded.