b1sl-python 0.2.0__tar.gz → 0.4.0__tar.gz

b1sl_python-0.4.0/CLAUDE.md

@@ -0,0 +1,114 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+`b1sl-python` — an async-first, metadata-driven Python SDK for the SAP Business One Service Layer (OData v4). Published to PyPI. Optional `saphdb` subpackage wraps SAP HANA via `hdbcli`.
+
+## Tooling and commands
+
+- **Package manager: `uv` exclusively.** `uv sync` (or `uv sync --all-extras --dev`) for installs. The venv lives at `.venv/`.
+- **Python: 3.11–3.12** (`requires-python = ">=3.11,<3.13"`).
+- Common targets (see `Makefile`):
+  - `make test` — unit tests only, no network (`pytest -m "not (integration or vcr)"`).
+  - `make test-vcr` — replay recorded cassettes offline (`--record-mode=none`). Requires the `vcr` marker.
+  - `make test-record` — re-record cassettes against a real SAP server. Requires `.env`.
+  - `make test-demo` — live integration tests, `APP_ENV=demo`, requires `.env`.
+  - `make test-ci` — full CI suite with coverage XML.
+  - `make lint` — `ruff check .` + `mypy .` (CI parity).
+- **Single test**: `PYTHONPATH=src:. .venv/bin/pytest tests/unit/test_odata_builder.py::test_name -xvs`. The `PYTHONPATH=src:.` prefix matters — the package lives at `src/b1sl/` and tests import via `b1sl.b1sl.…`.
+- CI (`.github/workflows/ci.yml`) runs only `uv run ruff check .` + `uv run pytest tests/unit/`. `mypy` is enforced locally via `make lint`, not in CI.
+- Release: `make release v=X.Y.Z` commits, tags, pushes; `publish.yml` then publishes to PyPI on tag.
+
+## Architecture
+
+### Three-layer model code: generated / overrides / entities
+
+The SDK is **metadata-driven**. Most of `src/b1sl/b1sl/models/` and `src/b1sl/b1sl/resources/` is autogenerated from SAP's OData `$metadata` XML, service document JSON, and API reference HTML (sources versioned under `metadata/<version>/`).
+
+- `models/_generated/`, `resources/_generated/` — **NEVER edit**. Wiped on every regeneration. Any structural fix belongs in the generator at `scripts/b1sl_metadata_generator/` (run via `./scripts/generate_models.sh <version>`).
+- `models/_overrides/` — hand-written extensions, calculated properties, `model_rebuild()` calls, metadata quirk fixes.
+- `entities/__init__.py` — the public facade. Blends generated + overridden models. **All public consumption goes through `from b1sl.b1sl import entities as en`**, never from `_generated/` directly.
+
+Production metadata should not be committed: place it as `metadata/<version>/metadata_document.real.xml` / `service_document.real.json`. The generator prioritizes `.real.*` over the public files; `.real.*` is gitignored.
+
+### `B1Model` base class
+
+Every entity inherits from `B1Model` (`models/base.py`), which provides:
+- Boolean coercion (SAP `"tYES"`/`"tNO"` ↔ Python `bool`).
+- Date handling (`/Date(ms)/` ↔ `date`).
+- `.to_api_payload()` uses `exclude_unset=True` — this is the foundation of the **Surgical Delta** pattern. PATCH payloads must contain only the fields the caller explicitly set; never `GET` an entity and resend it.
+- `.udfs` proxy: mapping-like accessor for User-Defined Fields. **Enforces the `U_` prefix** to prevent overwriting SAP core fields.
+
+### Elite vs Generic resource access
+
+The client exposes ~16 "Elite" aliases as direct properties (`client.items`, `client.business_partners`, `client.orders`, …) — these are the entities with verified ETag concurrency support. Everything else (~1000 endpoints) requires explicit binding:
+
+```python
+res = client.get_resource(en.User, "Users")
+```
+
+The explicit `get_resource` call is a deliberate safety signal: ETag protection is **not guaranteed** for these endpoints. When adding a new alias, only promote to Elite if SAP supports ETag for that endpoint.
+
+### Async/Sync symmetry
+
+`B1Client` / `AsyncB1Client`, `RestAdapter` / `AsyncRestAdapter`, `GenericResource` / `AsyncGenericResource`, `QueryBuilder` / `AsyncQueryBuilder` — every sync class has an async counterpart. Both surfaces must support the same parameters and methods. When changing one, change the other.
+
+### ETag concurrency — proactive invalidation
+
+SAP returns `204 No Content` on PATCH/DELETE without a fresh `ETag` header. The adapter's contract is:
+
+1. GET caches `ETag`.
+2. PATCH/DELETE sends it as `If-Match`.
+3. **On success, the adapter immediately clears the cached ETag** (proactive invalidation). Skipping this step makes a subsequent DELETE-after-UPDATE use a stale ETag and silently break under load.
+4. 412 → `SAPConcurrencyError`.
+
+Adapters map HTTP status to semantic exceptions via a standardized dict: 400 → `B1ValidationError`, 401 → `B1AuthError`, 404 → `B1NotFoundError`, 412 → `SAPConcurrencyError`, else `B1Exception`.
+
+### Batch / changesets
+
+`src/b1sl/b1sl/batch/` implements `$batch` via a `RecordingAdapter` proxy pattern: `batch.items.create(...)` reuses the exact same resource API but enqueues into `_pending` instead of executing.
+
+- `changeset()` blocks → atomic (all-or-nothing).
+- Top-level batch ops → independent (partial success allowed).
+- **`batch.execute()` must NOT raise on individual op failures.** Callers inspect `results.all_ok` / `results.failed`. Each result preserves `r.index` for traceability.
+
+### Pagination
+
+`.execute()` returns one page. `.stream()` follows `odata.nextLink` via generators (async generators for the async client). `.top(N)` is a global hard cap; `page_size` and `max_pages` are independent safety knobs. Filters survive page boundaries.
+
+### Configuration
+
+`B1Environment.load()` loads with precedence: env vars > `.env` > `configs/<env>.json`. JSON profiles hold non-sensitive test data only — credentials must come from env/`.env`. `B1SL_ENV` controls `dev` (human logs) vs `test` vs `prod` (structured JSON logs). `B1SL_DRY_RUN=1` (or `with b1.dry_run():` — `ContextVar`-scoped, task-safe) intercepts all writes and returns a fake 204.
+
+## Rules and gotchas
+
+- **English only** in code, comments, commits, docs.
+- **Never `pip install`** — use `uv add` / `uv sync`.
+- **Never edit `_generated/`**. Fix the generator or add a `_overrides/` file.
+- **Run `make lint` before proposing changes** — it covers the whole repo (CI only runs ruff, so mypy regressions slip past unless you run it locally).
+- **Surgical deltas only**: write `client.items.update("A001", en.Item(item_name="New"))`, never round-trip a fetched object.
+- **Don't promote endpoints to Elite without verifying ETag support** — Elite aliases imply concurrency safety.
+- **VCR cassette hygiene**: `tests/conftest.py` redacts hosts, sessions, credentials, and OData context URLs. Before pushing recorded cassettes, sanity-check with `grep -r "B1SESSION" tests/integration/cassettes/`.
+- **`hdbcli` is mocked at top-level in `tests/conftest.py`** so HANA tests don't require the SAP driver. Don't import `hdbcli` outside the `saphdb` subpackage.
+- Pytest markers: `integration` (live SAP), `vcr` (cassette playback). Default `make test` excludes both.
+
+## Where things live
+
+- `src/b1sl/b1sl/` — Service Layer SDK (the main product).
+- `src/b1sl/saphdb/` — optional HANA direct-SQL adapter (gated by `hana` extra).
+- `src/b1sl/contrib/` — framework integrations (Django, etc.).
+- `src/b1sl/contrib/mcp/` — MCP helper toolkit (framework-agnostic, no MCP SDK import).
+  Seven modules: `discovery.py` (Elite resource catalog + field introspection),
+  `grammar.py` / `odata_grammar.py` (SQL and OData grammar constraints + system prompts),
+  `schemas.py` / `odata_schemas.py` (tool-definition builders for SQL and OData CRUD),
+  `formatters.py` / `odata_formatters.py` (result/error formatters).
+  Guide: `docs/16-mcp-helpers.md`. Example: `examples/23_mcp_odata_server.py`.
+- `scripts/b1sl_metadata_generator/` — the generator engine.
+- `scripts/generate_models.sh <version>` — regen entry point.
+- `docs/` — long-form architecture/API guides (excluded from the wheel).
+- `docs/reference/sl/` — verbatim SAP Service Layer reference extracts (e.g. `sql-queries.md`). Read these before guessing endpoint semantics.
+- `examples/`, `skills/`, `agents.md`, `metadata/` — also excluded from the wheel (see `pyproject.toml [tool.hatch.build]`).
+- `src/b1sl/b1sl/resources/sql_queries.py` — specialized resource with bounded function (`/List`) support; the reference implementation for resources that go beyond generic CRUD.
+- `src/b1sl/b1sl/pagination.py` — contains `extract_next_link()` which handles both OData v3 (`odata.nextLink`) and v4 (`@odata.nextLink`) response formats.

b1sl_python-0.4.0/PKG-INFO

@@ -0,0 +1,315 @@
+Metadata-Version: 2.4
+Name: b1sl-python
+Version: 0.4.0
+Summary: A framework-agnostic Python SDK for SAP Business One Service Layer and SAP HANA. (Unofficial)
+Project-URL: Homepage, https://github.com/operator-ita/b1sl-python
+Project-URL: Repository, https://github.com/operator-ita/b1sl-python
+Project-URL: Bug Tracker, https://github.com/operator-ita/b1sl-python/issues
+Project-URL: Documentation, https://github.com/operator-ita/b1sl-python/tree/main/docs
+Author: Eliceo Guzman
+License: MIT
+License-File: LICENSE
+Keywords: erp,hana,odata,sap,sap-b1,service-layer
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: <3.13,>=3.11
+Requires-Dist: httpx<1,>=0.28.1
+Requires-Dist: pydantic<3,>=2.0.0
+Requires-Dist: python-dotenv>=1.2.2
+Provides-Extra: all
+Requires-Dist: beautifulsoup4>=4.14.3; extra == 'all'
+Requires-Dist: django<6,>=4.2; extra == 'all'
+Requires-Dist: hdbcli<3,>=2.20.0; extra == 'all'
+Requires-Dist: lxml>=6.0.2; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest-django; extra == 'dev'
+Requires-Dist: pytest-recording>=0.13.4; extra == 'dev'
+Requires-Dist: pytest<9.0,>=8.0; extra == 'dev'
+Requires-Dist: python-dotenv>=1.2.2; extra == 'dev'
+Requires-Dist: responses>=0.26.0; extra == 'dev'
+Requires-Dist: respx>=0.22.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django<6,>=4.2; extra == 'django'
+Provides-Extra: generator
+Requires-Dist: beautifulsoup4>=4.14.3; extra == 'generator'
+Requires-Dist: lxml>=6.0.2; extra == 'generator'
+Provides-Extra: hana
+Requires-Dist: hdbcli<3,>=2.20.0; extra == 'hana'
+Description-Content-Type: text/markdown
+
+# b1sl-python
+### Modern, async-first Python SDK for SAP Business One Service Layer.
+
+![b1sl Banner](docs/assets/hero-banner.png.png)
+
+[![Python Version](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![Pydantic v2](https://img.shields.io/badge/Pydantic-v2-orange.svg)](https://docs.pydantic.dev/)
+[![Built with httpx](https://img.shields.io/badge/HTTP-httpx-blueviolet.svg)](https://www.python-httpx.org/)
+
+b1sl is a high-performance SDK for the SAP B1 Service Layer, designed around concurrency, type safety, and developer experience. It covers the full lifecycle of a SAP integration — from single-record reads to transactional batch operations over large paginated datasets.
+
+---
+
+## Key Features
+
+- **Async-First Architecture**: Built on `httpx` for non-blocking I/O. Full sync client parity for scripts and non-async contexts.
+- **Type Safety**: Pydantic v2 integration for all SAP entities, with IDE autocomplete and runtime validation.
+- **Smart Session Management**: Automatic 401 re-authentication with internal locking to prevent license exhaustion.
+- **Session Hydration**: Reuse existing `B1SESSION` IDs across serverless functions or Temporal activities.
+- **Optimistic Concurrency**: Automated ETag handling with smart cache invalidation on 412 conflicts.
+- **Pythonic Querying**: Fluent OData builder with operator overloading (`F.ItemCode == "A001"`) and type-safe field access.
+- **Transparent Pagination**: Automatic `nextLink` handling via Python generators — `async for item in client.items.stream()`.
+- **`$batch` Support**: Group multiple operations into a single HTTP round-trip with full changeset atomicity.
+- **Dynamic UDFs**: Schema-aware proxy for type-safe interaction with User Defined Fields, including opt-in Pydantic validation.
+- **Observability**: Structured logging and event hooks for performance monitoring.
+- **Safe Development**: Global and per-request Dry Run mode to intercept write operations without hitting SAP.
+
+---
+
+## Installation
+
+```bash
+# Using pip
+pip install b1sl-python
+
+# Using uv
+uv add b1sl-python
+```
+
+---
+
+## Quick Start
+
+```python
+import asyncio
+from b1sl.b1sl import AsyncB1Client, B1Config
+
+async def main():
+    config = B1Config.from_env()
+
+    async with AsyncB1Client(config) as b1:
+        item = await b1.items.get("I1000")
+        print(f"Item: {item.item_name}")
+
+        # UDF access via protected mapping proxy
+        print(f"Custom color: {item.udfs['U_Color']}")
+
+asyncio.run(main())
+```
+
+---
+
+## Pythonic Querying
+
+Experience a fluent OData builder that uses operator overloading. You can choose between the zero-import **`F` Proxy** (requires SAP CamelCase names) or **Static Constants** (provides Pythonic snake_case autocomplete).
+
+```python
+from b1sl.b1sl.resources.odata import F
+from b1sl.b1sl.fields import Item
+
+# 1. Dynamic F Proxy (Quick, use SAP field names)
+items = await b1.items.filter(F.QuantityOnStock > 0).top(5).execute()
+
+# 2. Static fields (Type-safe, uses Pythonic snake_case autocomplete)
+items = await b1.items.filter(Item.quantity_on_stock > 0).top(5).execute()
+
+for item in items:
+    print(f"[{item.item_code}] {item.item_name}")
+```
+
+---
+
+## Transparent Pagination
+
+`.execute()` returns only the first page SAP gives you. `.stream()` transparently follows every `odata.nextLink` until the dataset is exhausted.
+
+```python
+# Silently incomplete for large collections:
+first_page = await b1.items.execute()         # → 20 items (SAP's default page)
+
+# Full dataset, zero boilerplate:
+async for item in b1.items.stream():          # → all items, all pages
+    process(item)
+
+# .top(N) is a hard global cap — not a page size:
+async for item in b1.items.top(100).stream(page_size=20):
+    ...  # exactly 100 items, fetched in batches of 20
+
+# Safety ceiling on HTTP requests for large tables:
+async for item in b1.items.stream(page_size=50, max_pages=5):
+    ...  # at most 250 items, at most 5 requests
+
+# Filters are preserved across every page boundary:
+async for item in b1.items.filter(F.ItemType == "itItems").stream():
+    assert item.item_type == "itItems"  # guaranteed on page 2, 3, ...
+```
+
+The sync client has full parity:
+
+```python
+from itertools import islice
+from b1sl.b1sl import B1Client
+
+with B1Client(config) as b1:
+    for item in b1.items.top(50).stream(page_size=10):
+        print(item.item_code)
+
+    # islice limits consumption — not HTTP requests.
+    # Use .top(N) when you want to limit requests.
+    first_5 = list(islice(b1.items.stream(page_size=20), 5))
+```
+
+---
+
+## `$batch` Requests
+
+Group multiple operations into a single HTTP round-trip. Use changesets for atomic write transactions.
+
+```python
+from b1sl.b1sl import entities as en
+
+async with AsyncB1Client(config) as b1:
+    async with b1.batch() as batch:
+        # Reads — enqueued, not executed
+        await batch.items.top(1).execute()
+        await batch.business_partners.top(1).execute()
+
+        # Atomic changeset — all succeed or all fail
+        async with batch.changeset() as cs:
+            await cs.items.create(en.Item(item_code="B001", item_name="New Item"))
+            await cs.items.update("A001", en.Item(item_name="Renamed"))
+
+        results = await batch.execute()
+
+    if results.all_ok:
+        print(f"Created/Updated items successfully")
+    else:
+        for r in results.failed:
+            print(f"Operation {r.index} failed: {r.error}")
+```
+
+---
+
+## Dynamic UDF Handling
+
+Schema discovery, type-safe access, and opt-in Pydantic validation — no manual model extensions required.
+
+```python
+# Constructor injection
+new_item = en.Item(item_code="NEW", udfs={"U_Category": "Hardware"})
+
+# Surgical update
+await b1.items.update("A001", en.Item(udfs={"U_Status": "Active"}))
+
+# Schema discovery
+schema = await b1.items.get_udf_schema()
+print(schema)                        # UDFSchema(table='OITM', fields=12)
+print("U_Category" in schema)        # True
+print(schema["U_Category"].type)     # 'db_Alpha'
+
+# Opt-in validation — generates a scoped Pydantic model on demand
+DynamicUDFs = schema.to_pydantic_model("ItemUDFs")
+validated = DynamicUDFs.model_validate({"U_Category": "Hardware"})
+
+# Or the full shortcut: validate + serialize in one call
+payload = schema.validate_and_dump({"U_Category": "Hardware"})
+await b1.items.update("A001", en.Item(udfs=payload))
+```
+
+> [!IMPORTANT]
+> The `.udfs` proxy enforces the `U_` prefix to prevent accidental overwrites of SAP core fields.
+
+---
+
+## Advanced Usage: FastAPI Integration
+
+b1sl is optimized for modern web frameworks. Use the Lifespan pattern to share a single connection pool across all requests.
+
+```python
+from fastapi import FastAPI
+from contextlib import asynccontextmanager
+from b1sl.b1sl import AsyncB1Client, B1Config
+
+b1_client: AsyncB1Client | None = None
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    global b1_client
+    b1_client = AsyncB1Client(B1Config.from_env())
+    await b1_client.connect()
+    yield
+    await b1_client.aclose()
+
+app = FastAPI(lifespan=lifespan)
+
+@app.get("/items/{item_code}")
+async def get_item(item_code: str):
+    return await b1_client.items.get(item_code)
+
+@app.get("/items")
+async def list_items():
+    # Stream the full catalog without loading it all into memory
+    return [item async for item in b1_client.items.stream(page_size=100)]
+```
+
+---
+
+## Architecture Overview
+
+| Feature | Implementation | Benefit |
+|:---|:---|:---|
+| **HTTP Engine** | `httpx` (Async + Sync) | Superior performance, timeouts, connection pooling |
+| **Data Models** | Pydantic v2 | Runtime validation, IDE autocomplete, zero surprises |
+| **Auth** | Auto-retry 401 + Session Hydration | Zero-downtime in serverless and long-running contexts |
+| **Concurrency** | Shared connection pool + internal locking | Prevents SAP license exhaustion under concurrent load |
+| **Pagination** | Generator-based `nextLink` follower | Memory-efficient iteration over arbitrarily large datasets |
+| **Batch** | `RecordingAdapter` proxy pattern | Full SDK API reuse inside transactions, no new methods to learn |
+| **UDFs** | `UDFSchema` container + dynamic Pydantic | Schema discovery, validation, and serialization in one object |
+
+---
+
+## Why b1sl?
+
+SAP Business One Service Layer is sensitive to session limits and licensing costs. Traditional wrappers often create redundant connections, leading to overhead and frequent auth failures. Beyond auth, naive implementations silently truncate paginated results and require manual OData string construction.
+
+b1sl addresses the full stack of these concerns:
+
+1. **Session Persistence**: Long-lived sessions with atomic re-authentication and internal locking.
+2. **Complete Data Access**: `.stream()` ensures you never silently miss records due to SAP's default page size.
+3. **Transactional Integrity**: `$batch` with changesets gives you atomicity without writing multipart HTTP by hand.
+4. **Zero Learning Curve for New APIs**: The batch proxy reuses the same SDK API — `batch.items.create()` works identically to `b1.items.create()`.
+
+---
+
+## SAP Compatibility
+
+Defaults to **OData V4 (Service Layer v2)**.
+
+| Requirement | Minimum Version |
+|:---|:---|
+| Verified baseline | Service Layer 1.27 (SAP 10.0 FP 2405) |
+| ETag support | Service Layer 1.21+ (March 2021) |
+| OData V2 fallback | Configurable via client options |
+
+For the full compatibility timeline, see [docs/02-compatibility.md](https://github.com/operator-ita/b1sl-python/blob/main/docs/02-compatibility.md).
+
+---
+
+## Contributing
+
+Contributions are welcome. Please open an issue to discuss proposed changes before submitting a pull request.
+
+---
+
+## License
+
+MIT © 2026.