almaapitk 0.3.1__tar.gz

almaapitk-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hagay Bar
+
+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.

almaapitk-0.3.1/PKG-INFO

@@ -0,0 +1,266 @@
+Metadata-Version: 2.3
+Name: almaapitk
+Version: 0.3.1
+Summary: Python toolkit for the Ex Libris Alma ILS API
+License: MIT
+Keywords: alma,ils,library,api,ex-libris,acquisitions,cataloging,resource-sharing
+Author: Hagay Bar
+Author-email: hagaybar@gmail.com
+Requires-Python: >=3.12
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+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: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Typing :: Typed
+Requires-Dist: beautifulsoup4 (>=4.14.3,<5.0.0)
+Requires-Dist: boto3 (>=1.35.0,<2.0.0)
+Requires-Dist: lxml (>=6.0.2,<7.0.0)
+Requires-Dist: openpyxl (>=3.1.0,<4.0.0)
+Requires-Dist: pandas (>=2.0.0,<3.0.0)
+Requires-Dist: pypdf2 (>=3.0.0,<4.0.0)
+Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
+Requires-Dist: requests (>=2.32.0,<3.0.0)
+Project-URL: Documentation, https://github.com/hagaybar/AlmaAPITK#readme
+Project-URL: Homepage, https://github.com/hagaybar/AlmaAPITK
+Project-URL: Issues, https://github.com/hagaybar/AlmaAPITK/issues
+Project-URL: Repository, https://github.com/hagaybar/AlmaAPITK
+Description-Content-Type: text/markdown
+
+# almaapitk
+
+A Python toolkit for interacting with the Ex Libris Alma ILS (Integrated Library System) API.
+
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- **Simple API Client**: Easy-to-use HTTP client with automatic authentication and error handling
+- **Domain Classes**: High-level abstractions for common Alma operations
+  - `Acquisitions` - POL operations, invoicing, item receiving
+  - `Analytics` - Analytics reports with pagination support
+  - `Users` - User management, email updates
+  - `BibliographicRecords` - Bib records, holdings, items
+  - `Admin` - Sets management (BIB_MMS, USER)
+  - `ResourceSharing` - Lending/borrowing via Partners API
+- **Environment Support**: Seamless switching between Sandbox and Production
+- **Response Wrapper**: Consistent response handling with `AlmaResponse`
+- **Comprehensive Logging**: Built-in logging with automatic API key redaction
+
+## Installation
+
+```bash
+pip install almaapitk
+```
+
+Or with Poetry:
+
+```bash
+poetry add almaapitk
+```
+
+## Quick Start
+
+### Setup
+
+Set your Alma API keys as environment variables:
+
+```bash
+export ALMA_SB_API_KEY="your-sandbox-api-key"
+export ALMA_PROD_API_KEY="your-production-api-key"
+```
+
+### Basic Usage
+
+```python
+from almaapitk import AlmaAPIClient, AlmaAPIError
+
+# Initialize client (uses ALMA_SB_API_KEY)
+client = AlmaAPIClient('SANDBOX')
+
+# Make API calls
+try:
+    response = client.get('almaws/v1/conf/libraries')
+    if response.success:
+        libraries = response.json()
+        for lib in libraries.get('library', []):
+            print(f"Library: {lib['name']}")
+except AlmaAPIError as e:
+    print(f"API error: {e} (status: {e.status_code})")
+```
+
+### Using Domain Classes
+
+```python
+from almaapitk import AlmaAPIClient, Acquisitions, Users
+
+client = AlmaAPIClient('SANDBOX')
+
+# Acquisitions operations
+acq = Acquisitions(client)
+# Note: Acquisitions.get_pol returns a plain dict directly
+pol = acq.get_pol("POL-12345")
+print(f"POL Status: {pol['status']['value']}")
+
+# User operations
+# Note: get_user takes a primary ID (NOT email) and returns an AlmaResponse
+users = Users(client)
+user_response = users.get_user("PRIMARY_ID_12345")
+user_data = user_response.json()
+print(f"User: {user_data['full_name']}")
+```
+
+### Working with Bibliographic Records
+
+```python
+from almaapitk import AlmaAPIClient, BibliographicRecords
+
+client = AlmaAPIClient('SANDBOX')
+bibs = BibliographicRecords(client)
+
+# Get a bib record (signature: get_record(mms_id, view="full", expand=None))
+record = bibs.get_record("99123456789")
+
+# Get holdings for a bib
+holdings = bibs.get_holdings("99123456789")
+```
+
+### Resource Sharing
+
+```python
+from almaapitk import AlmaAPIClient, ResourceSharing
+
+client = AlmaAPIClient('SANDBOX')
+rs = ResourceSharing(client)
+
+# Create a lending request
+# Mandatory: partner_code, external_id, owner, format_type, title
+# (citation_type is required unless mms_id is supplied)
+result = rs.create_lending_request(
+    partner_code="PARTNER_CODE",
+    external_id="EXT-2025-001",
+    owner="MAIN",                  # resource sharing library code
+    format_type="PHYSICAL",
+    title="Introduction to Python",
+    citation_type="BOOK",
+    author="Smith, John",
+)
+```
+
+### Analytics Reports
+
+```python
+from almaapitk import AlmaAPIClient, Analytics
+
+# Analytics API only works with PRODUCTION
+client = AlmaAPIClient('PRODUCTION')
+analytics = Analytics(client)
+
+# Get column headers for a report
+report_path = "/shared/University/Reports/MyReport"
+headers = analytics.get_report_headers(report_path)
+print(f"Columns: {headers}")
+
+# Fetch rows with pagination (limit must be 25-1000)
+rows = analytics.fetch_report_rows(report_path, limit=100, max_rows=500)
+for row in rows:
+    print(row)  # Dict with Column0, Column1, etc.
+
+# Optional: pass a progress_callback to track progress for large reports.
+# The callback receives one argument: the cumulative row count fetched so far.
+def show_progress(rows_so_far: int) -> None:
+    print(f"  fetched {rows_so_far} rows...")
+
+rows = analytics.fetch_report_rows(
+    report_path,
+    limit=100,
+    max_rows=500,
+    progress_callback=show_progress,
+)
+```
+
+## API Reference
+
+### Core Classes
+
+| Class | Description |
+|-------|-------------|
+| `AlmaAPIClient` | Main HTTP client for Alma API |
+| `AlmaResponse` | Response wrapper with `.data`, `.json()`, `.success`, `.status_code` |
+| `AlmaAPIError` | Base exception for API errors |
+| `AlmaValidationError` | Exception for validation failures |
+
+### Domain Classes
+
+| Class | Description |
+|-------|-------------|
+| `Acquisitions` | POL operations, invoicing, item receiving |
+| `Analytics` | Analytics reports with pagination (ResumptionToken) |
+| `Users` | User management, email updates |
+| `BibliographicRecords` | Bib records, holdings, items, scan-in |
+| `Admin` | Sets management (BIB_MMS, USER sets) |
+| `ResourceSharing` | Lending/borrowing via Partners API |
+
+### Utilities
+
+| Class | Description |
+|-------|-------------|
+| `TSVGenerator` | TSV file generation utilities |
+| `CitationMetadataError` | Exception for citation metadata errors |
+
+## Environment Configuration
+
+See [Quick Start → Setup](#setup) for environment variable setup. The client
+automatically picks `ALMA_SB_API_KEY` for `'SANDBOX'` and `ALMA_PROD_API_KEY`
+for `'PRODUCTION'`.
+
+## Error Handling
+
+```python
+from almaapitk import AlmaAPIClient, AlmaAPIError, AlmaValidationError
+
+client = AlmaAPIClient('SANDBOX')
+
+try:
+    response = client.get('almaws/v1/users/invalid-user')
+except AlmaValidationError as e:
+    # Input validation failed
+    print(f"Validation error: {e}")
+except AlmaAPIError as e:
+    # API returned an error
+    print(f"API error: {e}")
+    print(f"Status code: {e.status_code}")
+    print(f"Response: {e.response}")
+```
+
+## Requirements
+
+- Python 3.12+
+- requests
+- pandas
+- openpyxl
+- boto3
+- pypdf2
+- pyyaml
+- beautifulsoup4
+- lxml
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Links
+
+- [Alma API Documentation](https://developers.exlibrisgroup.com/alma/apis/)
+- [GitHub Repository](https://github.com/hagaybar/AlmaAPITK)
+

almaapitk-0.3.1/README.md

@@ -0,0 +1,231 @@
+# almaapitk
+
+A Python toolkit for interacting with the Ex Libris Alma ILS (Integrated Library System) API.
+
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- **Simple API Client**: Easy-to-use HTTP client with automatic authentication and error handling
+- **Domain Classes**: High-level abstractions for common Alma operations
+  - `Acquisitions` - POL operations, invoicing, item receiving
+  - `Analytics` - Analytics reports with pagination support
+  - `Users` - User management, email updates
+  - `BibliographicRecords` - Bib records, holdings, items
+  - `Admin` - Sets management (BIB_MMS, USER)
+  - `ResourceSharing` - Lending/borrowing via Partners API
+- **Environment Support**: Seamless switching between Sandbox and Production
+- **Response Wrapper**: Consistent response handling with `AlmaResponse`
+- **Comprehensive Logging**: Built-in logging with automatic API key redaction
+
+## Installation
+
+```bash
+pip install almaapitk
+```
+
+Or with Poetry:
+
+```bash
+poetry add almaapitk
+```
+
+## Quick Start
+
+### Setup
+
+Set your Alma API keys as environment variables:
+
+```bash
+export ALMA_SB_API_KEY="your-sandbox-api-key"
+export ALMA_PROD_API_KEY="your-production-api-key"
+```
+
+### Basic Usage
+
+```python
+from almaapitk import AlmaAPIClient, AlmaAPIError
+
+# Initialize client (uses ALMA_SB_API_KEY)
+client = AlmaAPIClient('SANDBOX')
+
+# Make API calls
+try:
+    response = client.get('almaws/v1/conf/libraries')
+    if response.success:
+        libraries = response.json()
+        for lib in libraries.get('library', []):
+            print(f"Library: {lib['name']}")
+except AlmaAPIError as e:
+    print(f"API error: {e} (status: {e.status_code})")
+```
+
+### Using Domain Classes
+
+```python
+from almaapitk import AlmaAPIClient, Acquisitions, Users
+
+client = AlmaAPIClient('SANDBOX')
+
+# Acquisitions operations
+acq = Acquisitions(client)
+# Note: Acquisitions.get_pol returns a plain dict directly
+pol = acq.get_pol("POL-12345")
+print(f"POL Status: {pol['status']['value']}")
+
+# User operations
+# Note: get_user takes a primary ID (NOT email) and returns an AlmaResponse
+users = Users(client)
+user_response = users.get_user("PRIMARY_ID_12345")
+user_data = user_response.json()
+print(f"User: {user_data['full_name']}")
+```
+
+### Working with Bibliographic Records
+
+```python
+from almaapitk import AlmaAPIClient, BibliographicRecords
+
+client = AlmaAPIClient('SANDBOX')
+bibs = BibliographicRecords(client)
+
+# Get a bib record (signature: get_record(mms_id, view="full", expand=None))
+record = bibs.get_record("99123456789")
+
+# Get holdings for a bib
+holdings = bibs.get_holdings("99123456789")
+```
+
+### Resource Sharing
+
+```python
+from almaapitk import AlmaAPIClient, ResourceSharing
+
+client = AlmaAPIClient('SANDBOX')
+rs = ResourceSharing(client)
+
+# Create a lending request
+# Mandatory: partner_code, external_id, owner, format_type, title
+# (citation_type is required unless mms_id is supplied)
+result = rs.create_lending_request(
+    partner_code="PARTNER_CODE",
+    external_id="EXT-2025-001",
+    owner="MAIN",                  # resource sharing library code
+    format_type="PHYSICAL",
+    title="Introduction to Python",
+    citation_type="BOOK",
+    author="Smith, John",
+)
+```
+
+### Analytics Reports
+
+```python
+from almaapitk import AlmaAPIClient, Analytics
+
+# Analytics API only works with PRODUCTION
+client = AlmaAPIClient('PRODUCTION')
+analytics = Analytics(client)
+
+# Get column headers for a report
+report_path = "/shared/University/Reports/MyReport"
+headers = analytics.get_report_headers(report_path)
+print(f"Columns: {headers}")
+
+# Fetch rows with pagination (limit must be 25-1000)
+rows = analytics.fetch_report_rows(report_path, limit=100, max_rows=500)
+for row in rows:
+    print(row)  # Dict with Column0, Column1, etc.
+
+# Optional: pass a progress_callback to track progress for large reports.
+# The callback receives one argument: the cumulative row count fetched so far.
+def show_progress(rows_so_far: int) -> None:
+    print(f"  fetched {rows_so_far} rows...")
+
+rows = analytics.fetch_report_rows(
+    report_path,
+    limit=100,
+    max_rows=500,
+    progress_callback=show_progress,
+)
+```
+
+## API Reference
+
+### Core Classes
+
+| Class | Description |
+|-------|-------------|
+| `AlmaAPIClient` | Main HTTP client for Alma API |
+| `AlmaResponse` | Response wrapper with `.data`, `.json()`, `.success`, `.status_code` |
+| `AlmaAPIError` | Base exception for API errors |
+| `AlmaValidationError` | Exception for validation failures |
+
+### Domain Classes
+
+| Class | Description |
+|-------|-------------|
+| `Acquisitions` | POL operations, invoicing, item receiving |
+| `Analytics` | Analytics reports with pagination (ResumptionToken) |
+| `Users` | User management, email updates |
+| `BibliographicRecords` | Bib records, holdings, items, scan-in |
+| `Admin` | Sets management (BIB_MMS, USER sets) |
+| `ResourceSharing` | Lending/borrowing via Partners API |
+
+### Utilities
+
+| Class | Description |
+|-------|-------------|
+| `TSVGenerator` | TSV file generation utilities |
+| `CitationMetadataError` | Exception for citation metadata errors |
+
+## Environment Configuration
+
+See [Quick Start → Setup](#setup) for environment variable setup. The client
+automatically picks `ALMA_SB_API_KEY` for `'SANDBOX'` and `ALMA_PROD_API_KEY`
+for `'PRODUCTION'`.
+
+## Error Handling
+
+```python
+from almaapitk import AlmaAPIClient, AlmaAPIError, AlmaValidationError
+
+client = AlmaAPIClient('SANDBOX')
+
+try:
+    response = client.get('almaws/v1/users/invalid-user')
+except AlmaValidationError as e:
+    # Input validation failed
+    print(f"Validation error: {e}")
+except AlmaAPIError as e:
+    # API returned an error
+    print(f"API error: {e}")
+    print(f"Status code: {e.status_code}")
+    print(f"Response: {e.response}")
+```
+
+## Requirements
+
+- Python 3.12+
+- requests
+- pandas
+- openpyxl
+- boto3
+- pypdf2
+- pyyaml
+- beautifulsoup4
+- lxml
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Links
+
+- [Alma API Documentation](https://developers.exlibrisgroup.com/alma/apis/)
+- [GitHub Repository](https://github.com/hagaybar/AlmaAPITK)

almaapitk-0.3.1/docs/releases/0.3.1.md

@@ -0,0 +1,38 @@
+# almaapitk 0.3.1
+
+**Release date:** 2026-04-27
+
+First publish of `almaapitk` to PyPI.
+
+> **Note:** 0.3.0 was uploaded to TestPyPI during pre-publish verification but
+> never released — README content corrections caught during the TestPyPI gate
+> required a version bump to 0.3.1. There is no 0.3.0 release on PyPI.
+
+## What's new since 0.2.0 (built locally on 2026-03-16, never published)
+
+- **`Analytics` domain class.** Supports Alma Analytics reports via `get_report_headers()` and `fetch_report_rows()` with built-in pagination. Note: Alma Analytics is backed by a single shared database accessible only via PRODUCTION credentials; SANDBOX has no analytics endpoint.
+- **`progress_callback` hook on `Analytics.fetch_report_rows()`.** Invoked after each page so callers can display progress for long-running fetches.
+- **Documentation moved out of the package.** Three internal docs files that previously lived in `src/almaapitk/alma_logging/` were moved to `docs/alma_logging/` so the published wheel contains zero non-Python content.
+- **Audit-driven hardening.** `process_users_batch` now documents `max_workers` honestly as a no-op pending a future concurrency feature; all `requests` calls in `AlmaAPIClient` have a generous `timeout=300` to prevent indefinite hangs.
+
+## Public API
+
+```python
+from almaapitk import (
+    AlmaAPIClient,
+    AlmaResponse,
+    AlmaAPIError, AlmaValidationError,
+    Admin, Users, BibliographicRecords, Acquisitions, ResourceSharing, Analytics,
+    TSVGenerator, CitationMetadataError,
+)
+```
+
+## Installation
+
+```bash
+pip install almaapitk
+```
+
+## Repository
+
+`https://github.com/hagaybar/AlmaAPITK`

almaapitk-0.3.1/pyproject.toml

@@ -0,0 +1,77 @@
+[project]
+name = "almaapitk"
+version = "0.3.1"
+description = "Python toolkit for the Ex Libris Alma ILS API"
+authors = [
+    {name = "Hagay Bar", email = "hagaybar@gmail.com"}
+]
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.12"
+keywords = [
+    "alma",
+    "ils",
+    "library",
+    "api",
+    "ex-libris",
+    "acquisitions",
+    "cataloging",
+    "resource-sharing"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+    "Typing :: Typed"
+]
+dependencies = [
+    "requests>=2.32.0,<3.0.0",
+    "pandas>=2.0.0,<3.0.0",
+    "openpyxl>=3.1.0,<4.0.0",
+    "boto3>=1.35.0,<2.0.0",
+    "pypdf2>=3.0.0,<4.0.0",
+    "pyyaml (>=6.0.3,<7.0.0)",
+    "beautifulsoup4 (>=4.14.3,<5.0.0)",
+    "lxml (>=6.0.2,<7.0.0)"
+]
+
+[project.urls]
+Homepage = "https://github.com/hagaybar/AlmaAPITK"
+Repository = "https://github.com/hagaybar/AlmaAPITK"
+Documentation = "https://github.com/hagaybar/AlmaAPITK#readme"
+Issues = "https://github.com/hagaybar/AlmaAPITK/issues"
+
+[tool.poetry]
+packages = [{ include = "almaapitk", from = "src" }]
+include = [
+    { path = "README.md", format = "sdist" },
+    { path = "LICENSE", format = "sdist" },
+    { path = "docs/releases/0.3.1.md", format = "sdist" },
+]
+exclude = [
+    "tests/**",
+    "scripts/**",
+    "docs/**",
+    "logs/**",
+    "backups/**",
+    ".a5c/**",
+    "config/**",
+    "AGENTS.md",
+    "CLAUDE.md",
+    "CLAUDE_tmp.html",
+    "ALMA_DIGITAL_DOCUMENTATION_EVALUATION.md",
+]
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0.0"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"