b1sl-python 0.1.1__tar.gz → 0.1.2__tar.gz

b1sl_python-0.1.2/.env.example

@@ -0,0 +1,33 @@
+# SAP B1 - Configuración de Credenciales (Capa 2)
+# COPIAR ESTE ARCHIVO A .env.test PARA PRUEBAS REALES
+
+# Service Layer
+B1SL_BASE_URL=https://localhost:50000/b1s/v2
+B1SL_COMPANY_DB=SBODemoMX
+B1SL_USERNAME=manager
+B1SL_PASSWORD=sap
+B1SL_SSL_VERIFY=0
+
+# Entorno de ejecución del SDK
+# Valores válidos: dev | test | prod
+# - dev  → logs en texto legible (default)
+# - test → igual a dev, indica aislamiento de pruebas
+# - prod → logs en JSON estructurado (para ELK, Datadog, etc.)
+B1SL_ENV=dev
+
+# Control de ejecución de tests de integración
+# 1 = Ejecuta integración real (tests/integration/)
+# 0 = Solo mocks (tests/unit/) o salta los marcados con @pytest.mark.integration
+SAP_B1_INTEGRATION=0
+
+# --- Advanced Tuning (Opcional) ---
+# B1SL_REUSE_TOKEN=1
+# B1SL_TOKEN_TIMEOUT=900
+# B1SL_MAX_PAGE_SIZE=20
+# B1SL_ETAG_CACHE_SIZE=256
+# B1SL_CONNECT_TIMEOUT=10
+# B1SL_READ_TIMEOUT=60
+
+# --- Safety & Debugging ---
+# Set to 1 to intercept all write requests (POST, PATCH, DELETE) without hitting SAP.
+B1SL_DRY_RUN=0

b1sl_python-0.1.2/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: b1sl-python
+Version: 0.1.2
+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](https://raw.githubusercontent.com/operator-ita/b1sl-python/refs/heads/main/docs/assets/hero_banner.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 designed for the SAP B1 Service Layer, focusing on concurrency, type safety, and efficient session management.
+
+---
+
+## Key Features
+
+*   **Async-First Architecture**: Built on top of `httpx` for non-blocking I/O.
+*   **Type Safety**: Full Pydantic v2 integration for all SAP entities.
+*   **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 and type-safe fields.
+*   **Observability**: Structured logging and event hooks for performance monitoring.
+*   **Safe Development**: Global and per-request **Dry Run** mode to intercept writing requests.
+
+---
+
+## 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:
+        # Full type hints for items and major entities
+        item = await b1.items.get("I1000")
+        
+        # 1. Native Pythonic access (snake_case)
+        print(f"Item: {item.item_name}")
+        
+        # 2. Dynamic access by SAP Alias (perfect for UDFs!)
+        print(f"Stock: {item.get('QuantityOnStock')}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+
+## Pythonic Querying
+
+Experience the best way to interact with SAP Service Layer. No more string concatenation!
+
+```python
+from b1sl.b1sl.fields import Item
+from datetime import date
+
+# Fluent queries are type-safe, readable, and support IDE autocomplete
+items = await b1.items.filter(
+    (Item.quantity_on_stock > 0) & (Item.valid_from >= date(2024, 1, 1))
+).select(
+    Item.item_code, 
+    Item.item_name
+).top(5).execute()
+
+for item in items:
+    print(f"[{item.item_code}] {item.item_name}")
+```
+
+---
+
+## Advanced Usage: FastAPI Integration
+
+b1sl is optimized for modern web frameworks. We recommend using the Lifespan pattern to share a single connection pool:
+
+```python
+from fastapi import FastAPI
+from contextlib import asynccontextmanager
+from b1sl.b1sl import AsyncB1Client, B1Config
+
+b1_client = None
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    global b1_client
+    config = B1Config.from_env()
+    b1_client = AsyncB1Client(config)
+    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)
+```
+
+---
+
+## Architecture Overview
+
+| Feature | Implementation | Benefit |
+| :--- | :--- | :--- |
+| **HTTP Engine** | `httpx` (Async/Sync) | Superior performance & timeouts |
+| **Data Models** | `Pydantic v2` | Instant validation & IDE autocomplete |
+| **Auth** | Auto-retry 401 & Hydration | Zero-downtime session management |
+| **Concurrency** | Shared Connection Pool | Prevents SAP License Exhaustion |
+
+---
+
+## Why b1sl?
+
+In production environments, 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. 
+
+**b1sl** addresses these issues through:
+1. **Session Persistence**: Maintaining long-lived sessions and performing atomic re-authentication.
+2. **Resource Efficiency**: Validated Pydantic models reduce runtime exceptions and memory footprint.
+3. **Concurrency Control**: Internal locking ensures that concurrent requests wait for a single login attempt instead of triggering multiple auth calls.
+
+---
+
+## SAP Compatibility
+
+This SDK is optimized for modern Service Layer environments and defaults to **v2 (OData V4)**.
+
+*   **Verified Baseline**: Service Layer **1.27** (SAP 10.0 FP 2405).
+*   **Minimum for ETags**: Requires Service Layer **1.21+** (March 2021).
+*   **Backward Compatibility**: Supports **v1 (OData V2)** through client configuration.
+
+For a detailed history of Service Layer features and specific version support, see the [Full Compatibility Timeline](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.

b1sl_python-0.1.2/README.md

@@ -0,0 +1,158 @@
+# b1sl-python
+### Modern, async-first Python SDK for SAP Business One Service Layer.
+
+![b1sl Banner](https://raw.githubusercontent.com/operator-ita/b1sl-python/refs/heads/main/docs/assets/hero_banner.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 designed for the SAP B1 Service Layer, focusing on concurrency, type safety, and efficient session management.
+
+---
+
+## Key Features
+
+*   **Async-First Architecture**: Built on top of `httpx` for non-blocking I/O.
+*   **Type Safety**: Full Pydantic v2 integration for all SAP entities.
+*   **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 and type-safe fields.
+*   **Observability**: Structured logging and event hooks for performance monitoring.
+*   **Safe Development**: Global and per-request **Dry Run** mode to intercept writing requests.
+
+---
+
+## 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:
+        # Full type hints for items and major entities
+        item = await b1.items.get("I1000")
+        
+        # 1. Native Pythonic access (snake_case)
+        print(f"Item: {item.item_name}")
+        
+        # 2. Dynamic access by SAP Alias (perfect for UDFs!)
+        print(f"Stock: {item.get('QuantityOnStock')}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+
+## Pythonic Querying
+
+Experience the best way to interact with SAP Service Layer. No more string concatenation!
+
+```python
+from b1sl.b1sl.fields import Item
+from datetime import date
+
+# Fluent queries are type-safe, readable, and support IDE autocomplete
+items = await b1.items.filter(
+    (Item.quantity_on_stock > 0) & (Item.valid_from >= date(2024, 1, 1))
+).select(
+    Item.item_code, 
+    Item.item_name
+).top(5).execute()
+
+for item in items:
+    print(f"[{item.item_code}] {item.item_name}")
+```
+
+---
+
+## Advanced Usage: FastAPI Integration
+
+b1sl is optimized for modern web frameworks. We recommend using the Lifespan pattern to share a single connection pool:
+
+```python
+from fastapi import FastAPI
+from contextlib import asynccontextmanager
+from b1sl.b1sl import AsyncB1Client, B1Config
+
+b1_client = None
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    global b1_client
+    config = B1Config.from_env()
+    b1_client = AsyncB1Client(config)
+    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)
+```
+
+---
+
+## Architecture Overview
+
+| Feature | Implementation | Benefit |
+| :--- | :--- | :--- |
+| **HTTP Engine** | `httpx` (Async/Sync) | Superior performance & timeouts |
+| **Data Models** | `Pydantic v2` | Instant validation & IDE autocomplete |
+| **Auth** | Auto-retry 401 & Hydration | Zero-downtime session management |
+| **Concurrency** | Shared Connection Pool | Prevents SAP License Exhaustion |
+
+---
+
+## Why b1sl?
+
+In production environments, 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. 
+
+**b1sl** addresses these issues through:
+1. **Session Persistence**: Maintaining long-lived sessions and performing atomic re-authentication.
+2. **Resource Efficiency**: Validated Pydantic models reduce runtime exceptions and memory footprint.
+3. **Concurrency Control**: Internal locking ensures that concurrent requests wait for a single login attempt instead of triggering multiple auth calls.
+
+---
+
+## SAP Compatibility
+
+This SDK is optimized for modern Service Layer environments and defaults to **v2 (OData V4)**.
+
+*   **Verified Baseline**: Service Layer **1.27** (SAP 10.0 FP 2405).
+*   **Minimum for ETags**: Requires Service Layer **1.21+** (March 2021).
+*   **Backward Compatibility**: Supports **v1 (OData V2)** through client configuration.
+
+For a detailed history of Service Layer features and specific version support, see the [Full Compatibility Timeline](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.

b1sl_python-0.1.2/pyproject.toml

@@ -0,0 +1,125 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "b1sl-python"
+version = "0.1.2"
+description = "A framework-agnostic Python SDK for SAP Business One Service Layer and SAP HANA. (Unofficial)"
+readme = "README.md"
+requires-python = ">=3.11,<3.13"
+license = { text = "MIT" }
+keywords = ["sap", "sap-b1", "service-layer", "hana", "erp", "odata"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+
+    "Typing :: Typed",
+]
+authors = [
+    { name = "Eliceo Guzman" },
+]
+
+# ── Core: minimal footprint ─────────────────────────────────────────────── #
+dependencies = [
+    "pydantic>=2.0.0,<3",
+    "httpx>=0.28.1,<1",
+    "python-dotenv>=1.2.2",
+]
+
+[project.urls]
+Homepage = "https://github.com/operator-ita/b1sl-python"
+Repository = "https://github.com/operator-ita/b1sl-python"
+"Bug Tracker" = "https://github.com/operator-ita/b1sl-python/issues"
+Documentation = "https://github.com/operator-ita/b1sl-python/tree/main/docs"
+
+[project.optional-dependencies]
+hana = ["hdbcli>=2.20.0,<3"]
+django = ["django>=4.2,<6"]
+generator = [
+    "beautifulsoup4>=4.14.3",
+    "lxml>=6.0.2",
+]
+dev = [
+    "pytest>=8.0,<9.0",
+    "pytest-django",
+    "pytest-asyncio>=1.3.0",
+    "pytest-recording>=0.13.4",
+    "python-dotenv>=1.2.2",
+    "respx>=0.22.0",
+    "responses>=0.26.0",
+    "ruff",
+    "mypy",
+
+    "pytest-cov",
+]
+
+all = ["b1sl-python[hana,django,generator]"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/b1sl"]
+exclude = [
+    "/scripts",
+    "/metadata",
+    "/examples",
+    "/docs",
+    "/skills",
+    "agents.md",
+]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "/scripts",
+    "/metadata",
+    "/examples",
+    "/docs",
+    "/.env",
+    "/skills",
+    "agents.md",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"
+markers = [
+    "integration: tests that require a real SAP B1 Service Layer connection",
+    "vcr: tests that use pytest-recording to capture HTTP traffic",
+]
+addopts = "--tb=short --cov=src --cov-report=term-missing"
+
+[tool.mypy]
+files = ["src"]
+strict = false
+ignore_missing_imports = true
+exclude = ["_generated"]
+check_untyped_defs = true
+warn_unreachable = true
+disable_error_code = ["attr-defined", "misc", "override", "assignment", "call-arg", "valid-type", "type-var", "unreachable", "call-overload", "arg-type", "union-attr"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+extend-exclude = [
+    "src/b1sl/b1sl/models/_generated",
+    "src/b1sl/b1sl/resources/_generated",
+]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+ignore = ["E501", "W291", "W293"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.ruff.lint.extend-per-file-ignores]
+"src/b1sl/b1sl/entities/__init__.py" = ["F401", "F403", "F405"]
+"examples/**" = ["E402", "F841"]
+"scripts/**" = ["E701", "F401"]
+
+[tool.pyright]
+include = ["src", "scripts"]
+extraPaths = [".", "scripts"]

b1sl_python-0.1.2/scratch/investigate_enum.py

@@ -0,0 +1,56 @@
+from enum import StrEnum
+import json
+
+# Current implementation pattern
+class OldField(StrEnum):
+    ITEM_CODE = "ItemCode"
+
+# Proposed implementation pattern
+class ODataExpression(str):
+    def __and__(self, other):
+        return ODataExpression(f"({self} and {other})")
+    
+    def __or__(self, other):
+        return ODataExpression(f"({self} or {other})")
+
+class ODataField(str):
+    def __eq__(self, other):
+        val = f"'{other}'" if isinstance(other, str) else str(other)
+        return ODataExpression(f"{self} eq {val}")
+
+class NewFields:
+    ITEM_CODE = ODataField("ItemCode")
+
+def test_investigation():
+    print("--- 1. String Interoperability (F-Strings) ---")
+    print(f"Old: {OldField.ITEM_CODE}")
+    print(f"New: {NewFields.ITEM_CODE}")
+    assert str(OldField.ITEM_CODE) == str(NewFields.ITEM_CODE)
+
+    print("\n--- 2. JSON Serialization ---")
+    print(f"Old: {json.dumps(OldField.ITEM_CODE)}")
+    print(f"New: {json.dumps(NewFields.ITEM_CODE)}")
+    assert json.dumps(OldField.ITEM_CODE) == json.dumps(NewFields.ITEM_CODE)
+
+    print("\n--- 3. Equality Overloading ---")
+    old_eq = (OldField.ITEM_CODE == "ItemCode")
+    new_eq = (NewFields.ITEM_CODE == "A001")
+    print(f"Old eq 'ItemCode': {old_eq} (type: {type(old_eq)})")
+    print(f"New eq 'A001': {new_eq} (type: {type(new_eq)})")
+    
+    print("\n--- 4. Logic Composition ---")
+    try:
+        composed = (NewFields.ITEM_CODE == "A001") & (ODataField("Valid") == "tYES")
+        print(f"Composed Filter: {composed}")
+        assert composed == "(ItemCode eq 'A001' and Valid eq 'tYES')"
+    except Exception as e:
+        print(f"Failed to compose: {e}")
+
+    print("\n--- 5. Membership / Iteration ---")
+    # StrEnum is iterable
+    print(f"Old is iterable: {hasattr(OldField, '__iter__')}")
+    # Custom class needs implementation
+    print(f"New is iterable: {hasattr(NewFields, '__iter__')}")
+
+if __name__ == "__main__":
+    test_investigation()

b1sl_python-0.1.2/src/b1sl/b1sl/__init__.py

@@ -0,0 +1,56 @@
+"""
+b1sl.b1sl — SDK for SAP B1 Service Layer (OData).
+"""
+
+import logging
+import warnings
+
+from b1sl.b1sl.async_client import AsyncB1Client
+from b1sl.b1sl.async_rest_adapter import AsyncRestAdapter
+from b1sl.b1sl.base_adapter import HookContext, ObservabilityConfig
+from b1sl.b1sl.client import B1Client
+from b1sl.b1sl.config import B1Config
+from b1sl.b1sl.config_manager import B1Environment
+from b1sl.b1sl.environment import B1Env
+from b1sl.b1sl.exceptions.exceptions import SAPConcurrencyError
+from b1sl.b1sl.resources.async_base import AsyncGenericResource
+from b1sl.b1sl.resources.base import GenericResource, ODataQuery
+from b1sl.b1sl.rest_adapter import RestAdapter
+
+try:
+    from pydantic import ArbitraryTypeWarning
+
+    warnings.filterwarnings("ignore", category=ArbitraryTypeWarning, module=r"b1sl\..*")  # type: ignore
+except ImportError:
+    warnings.filterwarnings("ignore", module=r"b1sl\..*|pydantic\..*")
+
+# Standard library pattern: prevent "No handlers could be found"
+logging.getLogger("b1sl").addHandler(logging.NullHandler())
+
+try:
+    from b1sl.b1sl import entities  # type: ignore
+except ImportError:
+    entities = None  # type: ignore # Before code generation
+
+try:
+    from b1sl.b1sl import fields  # type: ignore
+except ImportError:
+    fields = None  # type: ignore
+
+__all__ = [
+    "AsyncB1Client",
+    "B1Client",
+    "B1Config",
+    "B1Environment",
+    "AsyncRestAdapter",
+    "RestAdapter",
+    "B1Env",
+    "SAPConcurrencyError",
+    "AsyncGenericResource",
+    "GenericResource",
+    "ODataQuery",
+    "entities",
+    "fields",
+    "HookContext",
+    "ObservabilityConfig",
+]