hac-client-core 0.1.0__tar.gz

hac_client_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SapCommerceTools
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hac_client_core-0.1.0/PKG-INFO

@@ -0,0 +1,311 @@
+Metadata-Version: 2.4
+Name: hac-client-core
+Version: 0.1.0
+Summary: Python client library for the SAP Commerce HAC (Hybris Administration Console) HTTP API
+Author: SapCommerceTools
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/SapCommerceTools/ha-client-core
+Project-URL: Documentation, https://sapcommercetools.github.io/hac-client-core/
+Project-URL: Repository, https://github.com/SapCommerceTools/ha-client-core
+Project-URL: Issues, https://github.com/SapCommerceTools/ha-client-core/issues
+Project-URL: Changelog, https://github.com/SapCommerceTools/ha-client-core/blob/main/CHANGELOG.md
+Keywords: sap,commerce,hybris,hac,administration,groovy,flexiblesearch,impex
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: beautifulsoup4>=4.12.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: responses>=0.23.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Dynamic: license-file
+
+# hac-client-core
+
+Python client library for the **SAP Commerce HAC** (Hybris Administration Console) HTTP API.
+
+Execute Groovy scripts, run FlexibleSearch queries, import Impex data, and trigger system updates — all from Python, with automatic session management and CSRF handling.
+
+## Features
+
+- **Groovy script execution** — run arbitrary Groovy in commit or rollback mode
+- **FlexibleSearch queries** — execute queries with typed result objects
+- **Impex import** — import Impex content with configurable validation
+- **System update** — trigger updates, select patches/parameters, poll logs
+- **Session management** — automatic login, CSRF tokens, session caching across runs
+- **Pluggable authentication** — ships with Basic Auth; extend `AuthHandler` for OAuth, JWT, API keys, etc.
+- **Fully typed** — complete type annotations with a `py.typed` marker (PEP 561)
+
+## Requirements
+
+- Python ≥ 3.12
+- A running SAP Commerce instance with HAC enabled
+
+## Installation
+
+Install from PyPI (once published):
+
+```bash
+pip install hac-client-core
+```
+
+Or install directly from the repository:
+
+```bash
+pip install git+https://github.com/SapCommerceTools/ha-client-core.git
+```
+
+For development:
+
+```bash
+git clone https://github.com/SapCommerceTools/ha-client-core.git
+cd hac-client-core
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+```python
+from hac_client_core import HacClient, BasicAuthHandler
+
+# 1. Create an auth handler
+auth = BasicAuthHandler("admin", "nimda")
+
+# 2. Create the client
+client = HacClient(
+    base_url="https://localhost:9002",
+    auth_handler=auth,
+    ignore_ssl=True,           # skip certificate verification (dev only)
+    session_persistence=True,  # cache sessions between runs
+)
+
+# 3. Login (or let it happen automatically on the first call)
+client.login()
+
+# 4. Execute a Groovy script
+result = client.execute_groovy("return 'Hello from HAC'")
+print(result.execution_result)  # "Hello from HAC"
+```
+
+## Usage
+
+### Groovy script execution
+
+```python
+result = client.execute_groovy(
+    script="return de.hybris.platform.core.Registry.applicationContext",
+    commit=False,  # rollback mode (default)
+)
+
+if result.success:
+    print(result.output_text)       # stdout output
+    print(result.execution_result)  # return value
+else:
+    print(result.stacktrace_text)   # error details
+```
+
+Set `commit=True` to execute in commit mode — changes will be persisted to the database.
+
+### FlexibleSearch queries
+
+```python
+result = client.execute_flexiblesearch(
+    query="SELECT {pk}, {code} FROM {Product} WHERE {code} LIKE '%camera%'",
+    max_count=50,
+    locale="en",
+)
+
+if result.success:
+    print(f"Columns: {result.headers}")
+    print(f"Rows returned: {result.result_count}")
+    for row in result.rows:
+        print(row)
+else:
+    print(f"Query error: {result.exception}")
+```
+
+### Impex import
+
+```python
+impex = """
+INSERT_UPDATE Product; code[unique=true]; name[lang=en]
+; testProduct001 ; Test Product
+"""
+
+result = client.import_impex(impex, validation_mode="import_strict")
+
+if result.success:
+    print("Import completed")
+else:
+    print(f"Import failed: {result.error}")
+```
+
+### System update
+
+```python
+# Fetch available extensions and their parameters
+update_data = client.get_update_data()
+
+for ext in update_data.extensions_with_parameters:
+    print(f"{ext.name}: {[p.name for p in ext.parameters]}")
+
+# Execute an update with specific patches
+result = client.execute_update(
+    patches={"Patch_MVP": "yes"},
+    create_essential_data=True,
+    create_project_data=True,
+)
+
+print(f"Success: {result.success}")
+print(result.log_text)
+```
+
+Poll the update log while a long-running update is in progress:
+
+```python
+import time
+
+while True:
+    log = client.get_update_log()
+    print(log.log_text)
+    if log.is_complete:
+        break
+    time.sleep(5)
+```
+
+### Session management
+
+Sessions are cached to `~/.cache/hac-client/` by default so subsequent runs skip authentication:
+
+```python
+# Sessions are cached per (base_url, username, environment) tuple
+client = HacClient(
+    base_url="https://localhost:9002",
+    auth_handler=auth,
+    environment="local",          # tag sessions by environment
+    session_persistence=True,     # enable caching (default)
+)
+```
+
+Manage the session cache directly:
+
+```python
+from hac_client_core import SessionManager
+
+mgr = SessionManager()
+
+# List all cached sessions
+for s in mgr.list_sessions():
+    print(f"{s.environment}  {s.base_url}  created={s.created_at_formatted}")
+
+# Clear all sessions
+mgr.clear_all_sessions()
+```
+
+### Custom authentication
+
+Implement `AuthHandler` to support any authentication scheme:
+
+```python
+from hac_client_core import AuthHandler
+import requests
+
+class BearerTokenAuth(AuthHandler):
+    def __init__(self, token: str, username: str):
+        self._token = token
+        self._username = username
+
+    def apply_auth(self, request: requests.PreparedRequest) -> requests.PreparedRequest:
+        request.headers["Authorization"] = f"Bearer {self._token}"
+        return request
+
+    def get_initial_credentials(self) -> dict[str, str]:
+        return {"j_username": self._username, "j_password": self._token}
+```
+
+## API reference
+
+### `HacClient`
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `base_url` | `str` | — | HAC base URL (e.g. `https://localhost:9002`) |
+| `auth_handler` | `AuthHandler` | — | Authentication handler |
+| `environment` | `str` | `"local"` | Environment name for session caching |
+| `timeout` | `int` | `30` | HTTP timeout in seconds |
+| `ignore_ssl` | `bool` | `False` | Skip SSL certificate verification |
+| `session_persistence` | `bool` | `True` | Cache sessions to disk |
+| `quiet` | `bool` | `False` | Suppress informational messages on stderr |
+
+**Methods:**
+
+| Method | Returns | Description |
+|---|---|---|
+| `login()` | `None` | Authenticate and establish a session |
+| `execute_groovy(script, commit=False)` | `GroovyScriptResult` | Execute a Groovy script |
+| `execute_flexiblesearch(query, max_count=200, locale="en")` | `FlexibleSearchResult` | Run a FlexibleSearch query |
+| `import_impex(impex_content, validation_mode="import_strict")` | `ImpexResult` | Import Impex data |
+| `get_update_data()` | `UpdateData` | Fetch available update extensions and parameters |
+| `execute_update(...)` | `UpdateResult` | Trigger a system update |
+| `get_pending_patches()` | `dict` | Fetch pending system patches |
+| `get_update_log()` | `UpdateLog` | Poll the current update log |
+
+### Result models
+
+All result dataclasses are importable from `hac_client_core`:
+
+| Model | Key fields |
+|---|---|
+| `GroovyScriptResult` | `output_text`, `execution_result`, `stacktrace_text`, `success` |
+| `FlexibleSearchResult` | `headers`, `rows`, `result_count`, `exception`, `success` |
+| `ImpexResult` | `success`, `output`, `error` |
+| `UpdateData` | `is_initializing`, `project_datas`, `extensions_with_parameters` |
+| `UpdateResult` | `success`, `log_text`, `is_finished` |
+| `UpdateLog` | `log_text`, `is_complete`, `has_errors` |
+
+### Exceptions
+
+| Exception | Description |
+|---|---|
+| `HacClientError` | Base exception for all client errors |
+| `HacAuthenticationError` | Authentication or session errors |
+
+## Security considerations
+
+- **Credentials in memory** — `BasicAuthHandler` clears its password reference on garbage collection. For stronger guarantees, implement a custom `AuthHandler` backed by a secrets manager.
+- **CSRF protection** — the client automatically extracts and sends CSRF tokens on every request.
+- **Session cache** — cached sessions are stored as JSON files in `~/.cache/hac-client/` with filesystem permissions of the current user. The cache contains session IDs and CSRF tokens — not passwords.
+- **SSL verification** — `ignore_ssl=True` disables certificate checks. Use it only for local development with self-signed certificates.
+
+## Development
+
+```bash
+# Install in editable mode with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Type checking
+mypy src/
+
+# Lint
+ruff check src/
+```
+
+## License
+
+[MIT](LICENSE)

hac_client_core-0.1.0/README.md

@@ -0,0 +1,276 @@
+# hac-client-core
+
+Python client library for the **SAP Commerce HAC** (Hybris Administration Console) HTTP API.
+
+Execute Groovy scripts, run FlexibleSearch queries, import Impex data, and trigger system updates — all from Python, with automatic session management and CSRF handling.
+
+## Features
+
+- **Groovy script execution** — run arbitrary Groovy in commit or rollback mode
+- **FlexibleSearch queries** — execute queries with typed result objects
+- **Impex import** — import Impex content with configurable validation
+- **System update** — trigger updates, select patches/parameters, poll logs
+- **Session management** — automatic login, CSRF tokens, session caching across runs
+- **Pluggable authentication** — ships with Basic Auth; extend `AuthHandler` for OAuth, JWT, API keys, etc.
+- **Fully typed** — complete type annotations with a `py.typed` marker (PEP 561)
+
+## Requirements
+
+- Python ≥ 3.12
+- A running SAP Commerce instance with HAC enabled
+
+## Installation
+
+Install from PyPI (once published):
+
+```bash
+pip install hac-client-core
+```
+
+Or install directly from the repository:
+
+```bash
+pip install git+https://github.com/SapCommerceTools/ha-client-core.git
+```
+
+For development:
+
+```bash
+git clone https://github.com/SapCommerceTools/ha-client-core.git
+cd hac-client-core
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+```python
+from hac_client_core import HacClient, BasicAuthHandler
+
+# 1. Create an auth handler
+auth = BasicAuthHandler("admin", "nimda")
+
+# 2. Create the client
+client = HacClient(
+    base_url="https://localhost:9002",
+    auth_handler=auth,
+    ignore_ssl=True,           # skip certificate verification (dev only)
+    session_persistence=True,  # cache sessions between runs
+)
+
+# 3. Login (or let it happen automatically on the first call)
+client.login()
+
+# 4. Execute a Groovy script
+result = client.execute_groovy("return 'Hello from HAC'")
+print(result.execution_result)  # "Hello from HAC"
+```
+
+## Usage
+
+### Groovy script execution
+
+```python
+result = client.execute_groovy(
+    script="return de.hybris.platform.core.Registry.applicationContext",
+    commit=False,  # rollback mode (default)
+)
+
+if result.success:
+    print(result.output_text)       # stdout output
+    print(result.execution_result)  # return value
+else:
+    print(result.stacktrace_text)   # error details
+```
+
+Set `commit=True` to execute in commit mode — changes will be persisted to the database.
+
+### FlexibleSearch queries
+
+```python
+result = client.execute_flexiblesearch(
+    query="SELECT {pk}, {code} FROM {Product} WHERE {code} LIKE '%camera%'",
+    max_count=50,
+    locale="en",
+)
+
+if result.success:
+    print(f"Columns: {result.headers}")
+    print(f"Rows returned: {result.result_count}")
+    for row in result.rows:
+        print(row)
+else:
+    print(f"Query error: {result.exception}")
+```
+
+### Impex import
+
+```python
+impex = """
+INSERT_UPDATE Product; code[unique=true]; name[lang=en]
+; testProduct001 ; Test Product
+"""
+
+result = client.import_impex(impex, validation_mode="import_strict")
+
+if result.success:
+    print("Import completed")
+else:
+    print(f"Import failed: {result.error}")
+```
+
+### System update
+
+```python
+# Fetch available extensions and their parameters
+update_data = client.get_update_data()
+
+for ext in update_data.extensions_with_parameters:
+    print(f"{ext.name}: {[p.name for p in ext.parameters]}")
+
+# Execute an update with specific patches
+result = client.execute_update(
+    patches={"Patch_MVP": "yes"},
+    create_essential_data=True,
+    create_project_data=True,
+)
+
+print(f"Success: {result.success}")
+print(result.log_text)
+```
+
+Poll the update log while a long-running update is in progress:
+
+```python
+import time
+
+while True:
+    log = client.get_update_log()
+    print(log.log_text)
+    if log.is_complete:
+        break
+    time.sleep(5)
+```
+
+### Session management
+
+Sessions are cached to `~/.cache/hac-client/` by default so subsequent runs skip authentication:
+
+```python
+# Sessions are cached per (base_url, username, environment) tuple
+client = HacClient(
+    base_url="https://localhost:9002",
+    auth_handler=auth,
+    environment="local",          # tag sessions by environment
+    session_persistence=True,     # enable caching (default)
+)
+```
+
+Manage the session cache directly:
+
+```python
+from hac_client_core import SessionManager
+
+mgr = SessionManager()
+
+# List all cached sessions
+for s in mgr.list_sessions():
+    print(f"{s.environment}  {s.base_url}  created={s.created_at_formatted}")
+
+# Clear all sessions
+mgr.clear_all_sessions()
+```
+
+### Custom authentication
+
+Implement `AuthHandler` to support any authentication scheme:
+
+```python
+from hac_client_core import AuthHandler
+import requests
+
+class BearerTokenAuth(AuthHandler):
+    def __init__(self, token: str, username: str):
+        self._token = token
+        self._username = username
+
+    def apply_auth(self, request: requests.PreparedRequest) -> requests.PreparedRequest:
+        request.headers["Authorization"] = f"Bearer {self._token}"
+        return request
+
+    def get_initial_credentials(self) -> dict[str, str]:
+        return {"j_username": self._username, "j_password": self._token}
+```
+
+## API reference
+
+### `HacClient`
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `base_url` | `str` | — | HAC base URL (e.g. `https://localhost:9002`) |
+| `auth_handler` | `AuthHandler` | — | Authentication handler |
+| `environment` | `str` | `"local"` | Environment name for session caching |
+| `timeout` | `int` | `30` | HTTP timeout in seconds |
+| `ignore_ssl` | `bool` | `False` | Skip SSL certificate verification |
+| `session_persistence` | `bool` | `True` | Cache sessions to disk |
+| `quiet` | `bool` | `False` | Suppress informational messages on stderr |
+
+**Methods:**
+
+| Method | Returns | Description |
+|---|---|---|
+| `login()` | `None` | Authenticate and establish a session |
+| `execute_groovy(script, commit=False)` | `GroovyScriptResult` | Execute a Groovy script |
+| `execute_flexiblesearch(query, max_count=200, locale="en")` | `FlexibleSearchResult` | Run a FlexibleSearch query |
+| `import_impex(impex_content, validation_mode="import_strict")` | `ImpexResult` | Import Impex data |
+| `get_update_data()` | `UpdateData` | Fetch available update extensions and parameters |
+| `execute_update(...)` | `UpdateResult` | Trigger a system update |
+| `get_pending_patches()` | `dict` | Fetch pending system patches |
+| `get_update_log()` | `UpdateLog` | Poll the current update log |
+
+### Result models
+
+All result dataclasses are importable from `hac_client_core`:
+
+| Model | Key fields |
+|---|---|
+| `GroovyScriptResult` | `output_text`, `execution_result`, `stacktrace_text`, `success` |
+| `FlexibleSearchResult` | `headers`, `rows`, `result_count`, `exception`, `success` |
+| `ImpexResult` | `success`, `output`, `error` |
+| `UpdateData` | `is_initializing`, `project_datas`, `extensions_with_parameters` |
+| `UpdateResult` | `success`, `log_text`, `is_finished` |
+| `UpdateLog` | `log_text`, `is_complete`, `has_errors` |
+
+### Exceptions
+
+| Exception | Description |
+|---|---|
+| `HacClientError` | Base exception for all client errors |
+| `HacAuthenticationError` | Authentication or session errors |
+
+## Security considerations
+
+- **Credentials in memory** — `BasicAuthHandler` clears its password reference on garbage collection. For stronger guarantees, implement a custom `AuthHandler` backed by a secrets manager.
+- **CSRF protection** — the client automatically extracts and sends CSRF tokens on every request.
+- **Session cache** — cached sessions are stored as JSON files in `~/.cache/hac-client/` with filesystem permissions of the current user. The cache contains session IDs and CSRF tokens — not passwords.
+- **SSL verification** — `ignore_ssl=True` disables certificate checks. Use it only for local development with self-signed certificates.
+
+## Development
+
+```bash
+# Install in editable mode with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Type checking
+mypy src/
+
+# Lint
+ruff check src/
+```
+
+## License
+
+[MIT](LICENSE)

hac_client_core-0.1.0/pyproject.toml

@@ -0,0 +1,79 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hac-client-core"
+version = "0.1.0"
+description = "Python client library for the SAP Commerce HAC (Hybris Administration Console) HTTP API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+authors = [
+    {name = "SapCommerceTools"},
+]
+keywords = [
+    "sap",
+    "commerce",
+    "hybris",
+    "hac",
+    "administration",
+    "groovy",
+    "flexiblesearch",
+    "impex",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "requests>=2.31.0",
+    "beautifulsoup4>=4.12.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "responses>=0.23.0",
+    "mypy>=1.0",
+    "ruff>=0.1.0",
+]
+docs = [
+    "mkdocs-material>=9.5",
+]
+
+[project.urls]
+Homepage = "https://github.com/SapCommerceTools/ha-client-core"
+Documentation = "https://sapcommercetools.github.io/hac-client-core/"
+Repository = "https://github.com/SapCommerceTools/ha-client-core"
+Issues = "https://github.com/SapCommerceTools/ha-client-core/issues"
+Changelog = "https://github.com/SapCommerceTools/ha-client-core/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+hac_client_core = ["py.typed"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "SIM", "TCH"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

hac_client_core-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+