kadi-apy-helper 0.1.0__tar.gz

kadi_apy_helper-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Reupert
+
+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.

kadi_apy_helper-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: kadi-apy-helper
+Version: 0.1.0
+Summary: Contains a set of functions and helper scripts to ease the usage and interaction with Kadi4mat through the Kadi-APY / Kadi CLI manager.
+Keywords: kadi,kadi4mat,kadi-apy
+Author: Adam Reupert
+Author-email: Adam Reupert <adam.reupert@kit.edu>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Requires-Dist: kadi-apy>=0.51.0
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# Kadi-APY Helper
+
+A lightweight Python package for simplified management of users, groups, collections, and records in **Kadi4Mat** based on `kadi-apy`.
+
+## Installation
+
+Install the package in your project via `uv`:
+
+```bash
+uv add kadi-apy-helper
+```
+
+Alternatively, you can install the package traditionally via `pip`:
+
+```bash
+pip install kadi-apy-helper
+```
+
+## Setup (One-Time)
+
+Before you can access Kadi4Mat, the local configuration file must be created with your instance URL (host) and your Personal Access Token (PAT):
+
+```python
+from kadi_apy_helper import setup_kadi_apy
+
+setup_kadi_apy(
+    host_info="https://your-institution.edu",
+    pat_token="YOUR_PERSONAL_ACCESS_TOKEN"
+)
+```
+
+## Quickstart & Usage
+
+### 1. Load and Manage Elements
+
+Use `create_kadi_elements()` to set up a structured dictionary for your loaded objects:
+
+```python
+from kadi_apy_helper import (
+    create_kadi_elements,
+    load_users,
+    load_groups,
+    load_records,
+    load_collections,
+    print_loaded_elements,
+)
+
+# Initialize empty structure for elements
+elements = create_kadi_elements()
+
+# Load existing elements from Kadi4mat by their identifiers
+load_users(user_ids=["jdoe"], kadi_elements=elements)
+load_groups(group_ids=["research_group_xy"], kadi_elements=elements)
+load_collections(collection_ids=["project-2026"], kadi_elements=elements)
+load_records(record_ids=["measurement-series-01"], kadi_elements=elements)
+
+# Print loaded elements clearly
+print_loaded_elements(elements)
+```
+
+### 2. Create New Groups, Collections, and Records
+
+```python
+from kadi_apy_helper import add_group, add_collection, add_record
+
+# Create a new group
+group = add_group(
+    identifier="new-group",
+    title="My Research Group",
+    description="Description of the group",
+    users=[("jdoe", "member")]
+)
+
+# Create a new collection
+collection = add_collection(
+    identifier="new-collection",
+    title="Measurement Campaign 2026",
+    description="All datasets of the measurement campaign",
+    add_tags=["experiment", "2026"]
+)
+
+# Create a new record and upload files
+record = add_record(
+    identifier="measurement-001",
+    title="First Test Run",
+    record_type="dataset",
+    description="Raw data of the first test run",
+    add_tags=["raw-data"],
+    fileloc=["./data/measurement.csv"],
+    filedesc=["Measurement data as CSV"],
+    collection_link=[collection.id]
+)
+```
+
+### 3. Use a Custom `KadiManager` Instance (Optional)
+
+By default, all functions use the locally stored configuration file (`~/.kadi-apy.cfg`). If you want to work with multiple Kadi4Mat instances in parallel, you can pass your own `KadiManager` instance to any function:
+
+```python
+from kadi_apy import KadiManager
+from kadi_apy_helper import add_group
+
+custom_manager = KadiManager(
+    host="https://demo-kadi4mat.iam.kit.edu/",
+    pat="ANOTHER_TOKEN"
+)
+
+add_group(
+    identifier="test-group",
+    title="Test Group",
+    description="Created via custom manager",
+    manager=custom_manager
+)
+```
+
+## Requirements
+
+* Python >= 3.14
+* kadi-apy >= 0.51.0

kadi_apy_helper-0.1.0/README.md

@@ -0,0 +1,119 @@
+# Kadi-APY Helper
+
+A lightweight Python package for simplified management of users, groups, collections, and records in **Kadi4Mat** based on `kadi-apy`.
+
+## Installation
+
+Install the package in your project via `uv`:
+
+```bash
+uv add kadi-apy-helper
+```
+
+Alternatively, you can install the package traditionally via `pip`:
+
+```bash
+pip install kadi-apy-helper
+```
+
+## Setup (One-Time)
+
+Before you can access Kadi4Mat, the local configuration file must be created with your instance URL (host) and your Personal Access Token (PAT):
+
+```python
+from kadi_apy_helper import setup_kadi_apy
+
+setup_kadi_apy(
+    host_info="https://your-institution.edu",
+    pat_token="YOUR_PERSONAL_ACCESS_TOKEN"
+)
+```
+
+## Quickstart & Usage
+
+### 1. Load and Manage Elements
+
+Use `create_kadi_elements()` to set up a structured dictionary for your loaded objects:
+
+```python
+from kadi_apy_helper import (
+    create_kadi_elements,
+    load_users,
+    load_groups,
+    load_records,
+    load_collections,
+    print_loaded_elements,
+)
+
+# Initialize empty structure for elements
+elements = create_kadi_elements()
+
+# Load existing elements from Kadi4mat by their identifiers
+load_users(user_ids=["jdoe"], kadi_elements=elements)
+load_groups(group_ids=["research_group_xy"], kadi_elements=elements)
+load_collections(collection_ids=["project-2026"], kadi_elements=elements)
+load_records(record_ids=["measurement-series-01"], kadi_elements=elements)
+
+# Print loaded elements clearly
+print_loaded_elements(elements)
+```
+
+### 2. Create New Groups, Collections, and Records
+
+```python
+from kadi_apy_helper import add_group, add_collection, add_record
+
+# Create a new group
+group = add_group(
+    identifier="new-group",
+    title="My Research Group",
+    description="Description of the group",
+    users=[("jdoe", "member")]
+)
+
+# Create a new collection
+collection = add_collection(
+    identifier="new-collection",
+    title="Measurement Campaign 2026",
+    description="All datasets of the measurement campaign",
+    add_tags=["experiment", "2026"]
+)
+
+# Create a new record and upload files
+record = add_record(
+    identifier="measurement-001",
+    title="First Test Run",
+    record_type="dataset",
+    description="Raw data of the first test run",
+    add_tags=["raw-data"],
+    fileloc=["./data/measurement.csv"],
+    filedesc=["Measurement data as CSV"],
+    collection_link=[collection.id]
+)
+```
+
+### 3. Use a Custom `KadiManager` Instance (Optional)
+
+By default, all functions use the locally stored configuration file (`~/.kadi-apy.cfg`). If you want to work with multiple Kadi4Mat instances in parallel, you can pass your own `KadiManager` instance to any function:
+
+```python
+from kadi_apy import KadiManager
+from kadi_apy_helper import add_group
+
+custom_manager = KadiManager(
+    host="https://demo-kadi4mat.iam.kit.edu/",
+    pat="ANOTHER_TOKEN"
+)
+
+add_group(
+    identifier="test-group",
+    title="Test Group",
+    description="Created via custom manager",
+    manager=custom_manager
+)
+```
+
+## Requirements
+
+* Python >= 3.14
+* kadi-apy >= 0.51.0

kadi_apy_helper-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "kadi-apy-helper"
+version = "0.1.0"
+description = "Contains a set of functions and helper scripts to ease the usage and interaction with Kadi4mat through the Kadi-APY / Kadi CLI manager."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.14"
+dependencies = ["kadi-apy>=0.51.0"]
+keywords = [
+    "kadi",
+    "kadi4mat",
+    "kadi-apy",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+]
+
+[[project.authors]]
+name = "Adam Reupert"
+email = "adam.reupert@kit.edu"
+
+[build-system]
+requires = ["uv_build>=0.13.7,<0.14.0"]
+build-backend = "uv_build"

kadi_apy_helper-0.1.0/pyproject.toml.orig

@@ -0,0 +1,24 @@
+[project]
+name = "kadi-apy-helper"
+version = "0.1.0"
+description = "Contains a set of functions and helper scripts to ease the usage and interaction with Kadi4mat through the Kadi-APY / Kadi CLI manager."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Adam Reupert", email = "adam.reupert@kit.edu" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "kadi-apy>=0.51.0",
+]
+keywords = ["kadi", "kadi4mat", "kadi-apy"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+]
+
+[build-system]
+requires = ["uv_build>=0.13.7,<0.14.0"]
+build-backend = "uv_build"

kadi_apy_helper-0.1.0/src/kadi_apy_helper/__init__.py

@@ -0,0 +1,25 @@
+from .main import (
+    setup_kadi_apy,
+    create_kadi_elements,
+    add_collection,
+    add_group,
+    add_record,
+    load_users,
+    load_groups,
+    load_collections,
+    load_records,
+    print_loaded_elements,
+)
+
+__all__ = [
+    "setup_kadi_apy",
+    "create_kadi_elements",
+    "add_collection",
+    "add_group",
+    "add_record",
+    "load_users",
+    "load_groups",
+    "load_collections",
+    "load_records",
+    "print_loaded_elements",
+]

kadi_apy_helper-0.1.0/src/kadi_apy_helper/main.py

@@ -0,0 +1,191 @@
+import subprocess
+from typing import Optional
+from kadi_apy import KadiManager
+from kadi_apy.lib.resources.groups import Group
+from kadi_apy.lib.resources.records import Record
+from kadi_apy.lib.resources.collections import Collection
+
+
+def _get_manager(manager: Optional[KadiManager] = None) -> KadiManager:
+    return manager if manager is not None else KadiManager()
+
+
+def setup_kadi_apy(host_info: str, pat_token: str) -> None:
+    subprocess.run(['kadi-apy', 'config', 'create'], encoding="utf-8")
+    subprocess.run(['kadi-apy', 'config', 'set-host'], input=host_info + "\n", encoding="utf-8")
+    subprocess.run(['kadi-apy', 'config', 'set-pat'], input=pat_token, encoding="utf-8")
+    subprocess.run(['kadi-apy', 'config', 'get-kadi-info'], encoding="utf-8")
+
+def create_kadi_elements() -> dict[str, dict]:
+    return {
+        "users": {},
+        "groups": {},
+        "collections": {},
+        "records": {},
+    }
+
+
+def add_group(
+    identifier: str,
+    title: str,
+    description: str,
+    users: Optional[list] = None,
+    manager: Optional[KadiManager] = None
+    ) -> Group:
+    mgr = _get_manager(manager)
+    group = mgr.group(create_kadi_elementsidentifier=identifier, title=title, create=True)
+    group.edit(description=description)
+    if users:
+        for i in users:
+            group.add_user(i[0], permission_new=i[1])
+    print("Sample group created/updated successfully.")
+    return group
+
+
+def add_record(
+    identifier: str,
+    title: str,
+    record_type: str,
+    description: Optional[str] = None,
+    add_tags: Optional[list] = None,
+    remove_tags: Optional[list] = None,
+    fileloc: Optional[list] = None,
+    filedesc: Optional[list] = None,
+    metadata: Optional[list] = None,
+    collection_link: Optional[list] = None,
+    record_link: Optional[list] = None,
+    users: Optional[list] = None,
+    groups: Optional[list] = None,
+    manager: Optional[KadiManager] = None
+    ) -> Record:
+    mgr = _get_manager(manager)
+    record = mgr.record(identifier=identifier, title=title, create=True)
+    record.edit(type=record_type, description=description)
+    if add_tags:
+        for i in add_tags:
+            record.add_tag(i)
+    if remove_tags:
+        for i in remove_tags:
+            record.remove_tag(i)
+    if fileloc and filedesc:
+        for file_number, loc in enumerate(fileloc):
+            print(f"Upload {filedesc[file_number]} from {loc}")
+            record.upload_file(loc, file_description=filedesc[file_number])
+    if metadata:
+        record.add_metadata(metadata, force=True)
+    if collection_link:
+        for i in collection_link:
+            record.add_collection_link(i)
+    if record_link:
+        for i in record_link:
+            i[0].link_record(record, name=i[1])
+    if users:
+        for i in users:
+            record.add_user(i[0], permission_new=i[1])
+    if groups:
+        for i in groups:
+            record.add_group_role(i[0], permission_new=i[1])
+    return record
+
+
+def add_collection(
+    identifier: str,
+    title: str,
+    description: str,
+    add_tags: Optional[list] = None,
+    remove_tags: Optional[list] = None,
+    users: Optional[list] = None,
+    groups: Optional[list] = None,
+    manager: Optional[KadiManager] = None
+    ) -> Collection:
+    mgr = _get_manager(manager)
+    collection = mgr.collection(identifier=identifier, title=title, create=True)
+    collection.edit(description=description)
+
+    if add_tags:
+        for i in add_tags:
+            collection.add_tag(i)
+    if remove_tags:
+        for i in remove_tags:
+            collection.remove_tag(i)
+    if users:
+        for i in users:
+            collection.add_user(i)
+    if groups:
+        for i in groups:
+            collection.add_group_role(i[0], permission_new=i[1])
+    print("Sample collection created/updated successfully.")
+    return collection
+
+
+def load_users(
+    user_ids: list,
+    kadi_elements: Optional[dict] = None,
+    manager: Optional[KadiManager] = None
+    ) -> dict:
+    mgr = _get_manager(manager)
+    user_dict: dict = {}
+    for identifier in user_ids:
+        user_obj = mgr.user(username=identifier, identity_type="ldap")
+        user_dict[identifier] = user_obj.id
+        if kadi_elements is not None:
+            kadi_elements.setdefault("users", {})[identifier] = user_obj
+    return user_dict
+
+
+def load_groups(
+    group_ids: list,
+    kadi_elements: Optional[dict] = None,
+    manager: Optional[KadiManager] = None
+) -> dict:
+    mgr = _get_manager(manager)
+    group_dict: dict = {}
+    for identifier in group_ids:
+        group_obj = mgr.group(identifier=identifier)
+        group_dict[identifier] = group_obj.id
+        if kadi_elements is not None:
+            kadi_elements.setdefault("groups", {})[identifier] = group_obj
+    return group_dict
+
+
+def load_records(
+    record_ids: list,
+    kadi_elements: Optional[dict] = None,
+    manager: Optional[KadiManager] = None
+) -> dict:
+    mgr = _get_manager(manager)
+    record_dict: dict = {}
+    for identifier in record_ids:
+        record_obj = mgr.record(identifier=identifier)
+        record_dict[identifier] = record_obj.id
+        if kadi_elements is not None:
+            kadi_elements.setdefault("records", {})[identifier] = record_obj
+    return record_dict
+
+
+def load_collections(
+    collection_ids: list,
+    kadi_elements: Optional[dict] = None,
+    manager: Optional[KadiManager] = None
+) -> dict:
+    mgr = _get_manager(manager)
+    collection_dict: dict = {}
+    for identifier in collection_ids:
+        collection_obj = mgr.collection(identifier=identifier)
+        collection_dict[identifier] = collection_obj.id
+        if kadi_elements is not None:
+            kadi_elements.setdefault("collections", {})[identifier] = collection_obj
+    return collection_dict
+
+
+def print_loaded_elements(kadi_elements: dict) -> None:
+    for category, label in [
+        ("users", "User:"),
+        ("groups", "Groups:"),
+        ("records", "Records:"),
+        ("collections", "Collections:")
+    ]:
+        print(label)
+        for identifier, obj in kadi_elements.get(category, {}).items():
+            print(f"{obj.id}: {identifier}")
+        print("")