entitysdk 0.0.1__tar.gz → 0.1.0__tar.gz

{entitysdk-0.0.1 → entitysdk-0.1.0}/.gitignore

@@ -165,7 +165,10 @@ cython_debug/
 #  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/
+.idea/
 
 # PyPI configuration file
 .pypirc
+
+examples/*.md
+examples/*.h5

entitysdk-0.1.0/CHANGELOG.rst

@@ -0,0 +1,5 @@
+# Changelog
+
+## Version 0.0.1
+
+- Initial preliminary version.

entitysdk-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,105 @@
+# Contribution Guide
+
+We would love for you to contribute to the project and help make it better than it is today.
+As a contributor, here are the guidelines we would like you to follow:
+
+ - [Question or Problem?](#got-a-question)
+ - [Issues and Bugs](#found-a-bug)
+ - [Feature Requests](#missing-a-feature)
+ - [Submissions](#submission-guidelines)
+
+# Got a Question?
+
+Please do not hesitate to raise an issue on [github project page][github].
+
+# Found a Bug?
+
+If you find a bug in the source code, you can help us by [submitting an issue](#issues)
+to our [GitHub Repository][github]. Even better, you can [submit a Pull Request](#pull-requests) with a fix.
+
+#  Missing a Feature?
+
+You can *request* a new feature by [submitting an issue](#issues) to our GitHub Repository.
+If you would like to *implement* a new feature, please submit an issue with a proposal for your 
+work first, to be sure that we can use it.
+
+Please consider what kind of change it is:
+
+* For a **Major Feature**, first open an issue and outline your proposal so that it can be
+discussed. This will also allow us to better coordinate our efforts, prevent duplication of work,
+and help you to craft the change so that it is successfully accepted into the project.
+* **Small Features** can be crafted and directly [submitted as a Pull Request](#pull-requests).
+
+# Submission Guidelines
+
+## Issues
+
+Before you submit an issue, please search the issue tracker, maybe an issue for your problem
+already exists and the discussion might inform you of workarounds readily available.
+
+We want to fix all the issues as soon as possible, but before fixing a bug we need to reproduce
+and confirm it. In order to reproduce bugs we will need as much information as possible, and
+preferably with an example.
+
+## Pull Requests
+
+When you wish to contribute to the code base, please consider the following guidelines:
+
+* Make a [fork](https://guides.github.com/activities/forking/) of this repository.
+* Make your changes in your fork, in a new git branch:
+
+     ```shell
+     git checkout -b my-fix-branch main
+     ```
+* Create your patch, **including appropriate Python test cases**.
+* Run the full test suite, and ensure that all tests pass.
+* Commit your changes using a descriptive commit message.
+
+     ```shell
+     git commit -a
+     ```
+* Push your branch to GitHub:
+
+    ```shell
+    git push origin my-fix-branch
+    ```
+* In GitHub, send a Pull Request to the `main` branch of the upstream repository of the relevant component.
+* If we suggest changes then:
+  * Make the required updates.
+  * Re-run the test suites to ensure tests are still passing.
+  * Rebase your branch and force push to your GitHub repository (this will update your Pull Request):
+
+       ```shell
+        git rebase main -i
+        git push -f
+       ```
+
+That’s it! Thank you for your contribution!
+
+### After your pull request is merged
+
+After your pull request is merged, you can safely delete your branch and pull the changes from
+the main (upstream) repository:
+
+* Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows:
+
+    ```shell
+    git push origin --delete my-fix-branch
+    ```
+* Check out the main branch:
+
+    ```shell
+    git checkout main -f
+    ```
+* Delete the local branch:
+
+    ```shell
+    git branch -D my-fix-branch
+    ```
+* Update your main with the latest upstream version:
+
+    ```shell
+    git pull --ff upstream main
+    ```
+
+[github]: https://github.com/openbraininstitute/entitysdk

entitysdk-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: entitysdk
+Version: 0.1.0
+Summary: Python library for interacting with the entitycore service
+Author-email: Open Brain Institute <info@openbraininstitute.org>
+Maintainer-email: Open Brain Institute <info@openbraininstitute.org>
+License: Apache-2.0
+Project-URL: documentation, https://entitysdk.readthedocs.io/en/stable
+Project-URL: repository, https://github.com/openbraininstitute/entitysdk
+Project-URL: changelog, https://github.com/openbraininstitute/entitysdk/CHANGELOG.md
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: httpx
+Requires-Dist: pydantic
+Requires-Dist: pydantic-settings
+Dynamic: license-file
+
+[![Build status][build_status_badge]][build_status_target]
+[![License][license_badge]][license_target]
+[![Code coverage][coverage_badge]][coverage_target]
+[![CodeQL][codeql_badge]][codeql_target]
+[![PyPI][pypi_badge]][pypi_target]
+
+# entitysdk
+
+entitysdk is a Python library for interacting with the [entitycore service][entitycore], providing a type-safe and intuitive interface for managing scientific entities, and their associated assets.
+
+## Requirements
+
+- Python 3.11 or higher
+- Network access to entitycore service endpoints
+
+## Installation
+
+```bash
+pip install entitysdk
+```
+## Quick Start
+
+```python
+from uuid import UUID
+from entitysdk.client import Client
+from entitysdk.common import ProjectContext
+from entitysdk.models.morphology import ReconstructionMorphology
+
+# Initialize client
+client = Client(
+    api_url="http://api.example.com",
+    project_context=ProjectContext(
+        project_id=UUID("your-project-id"),
+        virtual_lab_id=UUID("your-lab-id")
+    )
+)
+
+# Search for morphologies
+iterator = client.search(
+    entity_type=ReconstructionMorphology,
+    query={"mtype__pref_label": "L5_TPC:A"},
+    token=token,
+    limit=1,
+)
+morphology = next(iterator)
+
+# Upload an asset
+client.upload_file(
+    entity_id=morphology.id,
+    entity_type=ReconstructionMorphology,
+    file_path="path/to/file.swc",
+    file_content_type="application/swc",
+    token="your-token"
+)
+```
+
+### Authentication
+- Valid Keycloak access token
+- Project context with:
+  - Valid project ID (UUID)
+  - Valid virtual lab ID (UUID)
+
+Example configuration:
+```python
+from uuid import UUID
+from entitysdk.common import ProjectContext
+
+project_context = ProjectContext(
+    project_id=UUID("12345678-1234-1234-1234-123456789012"),
+    virtual_lab_id=UUID("87654321-4321-4321-4321-210987654321")
+)
+```
+
+## Development
+
+### Requirements
+- tox/tox-uv
+
+### Clone and run tests
+
+```bash
+# Clone the repository
+git clone https://github.com/your-org/entitysdk.git
+
+# Run linting, tests, and check-packaging
+tox
+```
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+## License
+
+Copyright (c) 2025 Open Brain Institute
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+
+[entitycore]: https://github.com/openbraininstitute/entitycore
+
+[build_status_badge]: https://github.com/openbraininstitute/entitysdk/actions/workflows/tox.yml/badge.svg
+[build_status_target]: https://github.com/openbraininstitute/entitysdk/actions
+[license_badge]: https://img.shields.io/pypi/l/entitysdk
+[license_target]: https://github.com/openbraininstitute/entitysdk/blob/main/LICENSE.txt
+[coverage_badge]: https://codecov.io/github/openbraininstitute/entitysdk/coverage.svg?branch=main
+[coverage_target]: https://codecov.io/github/openbraininstitute/entitysdk?branch=main
+[codeql_badge]: https://github.com/openbraininstitute/entitysdk/actions/workflows/github-code-scanning/codeql/badge.svg
+[codeql_target]: https://github.com/openbraininstitute/entitysdk/actions/workflows/github-code-scanning/codeql
+[pypi_badge]: https://github.com/openbraininstitute/entitysdk/actions/workflows/sdist.yml/badge.svg
+[pypi_target]: https://pypi.org/project/entitysdk/
+

entitysdk-0.1.0/README.md

@@ -0,0 +1,122 @@
+[![Build status][build_status_badge]][build_status_target]
+[![License][license_badge]][license_target]
+[![Code coverage][coverage_badge]][coverage_target]
+[![CodeQL][codeql_badge]][codeql_target]
+[![PyPI][pypi_badge]][pypi_target]
+
+# entitysdk
+
+entitysdk is a Python library for interacting with the [entitycore service][entitycore], providing a type-safe and intuitive interface for managing scientific entities, and their associated assets.
+
+## Requirements
+
+- Python 3.11 or higher
+- Network access to entitycore service endpoints
+
+## Installation
+
+```bash
+pip install entitysdk
+```
+## Quick Start
+
+```python
+from uuid import UUID
+from entitysdk.client import Client
+from entitysdk.common import ProjectContext
+from entitysdk.models.morphology import ReconstructionMorphology
+
+# Initialize client
+client = Client(
+    api_url="http://api.example.com",
+    project_context=ProjectContext(
+        project_id=UUID("your-project-id"),
+        virtual_lab_id=UUID("your-lab-id")
+    )
+)
+
+# Search for morphologies
+iterator = client.search(
+    entity_type=ReconstructionMorphology,
+    query={"mtype__pref_label": "L5_TPC:A"},
+    token=token,
+    limit=1,
+)
+morphology = next(iterator)
+
+# Upload an asset
+client.upload_file(
+    entity_id=morphology.id,
+    entity_type=ReconstructionMorphology,
+    file_path="path/to/file.swc",
+    file_content_type="application/swc",
+    token="your-token"
+)
+```
+
+### Authentication
+- Valid Keycloak access token
+- Project context with:
+  - Valid project ID (UUID)
+  - Valid virtual lab ID (UUID)
+
+Example configuration:
+```python
+from uuid import UUID
+from entitysdk.common import ProjectContext
+
+project_context = ProjectContext(
+    project_id=UUID("12345678-1234-1234-1234-123456789012"),
+    virtual_lab_id=UUID("87654321-4321-4321-4321-210987654321")
+)
+```
+
+## Development
+
+### Requirements
+- tox/tox-uv
+
+### Clone and run tests
+
+```bash
+# Clone the repository
+git clone https://github.com/your-org/entitysdk.git
+
+# Run linting, tests, and check-packaging
+tox
+```
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+## License
+
+Copyright (c) 2025 Open Brain Institute
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+
+[entitycore]: https://github.com/openbraininstitute/entitycore
+
+[build_status_badge]: https://github.com/openbraininstitute/entitysdk/actions/workflows/tox.yml/badge.svg
+[build_status_target]: https://github.com/openbraininstitute/entitysdk/actions
+[license_badge]: https://img.shields.io/pypi/l/entitysdk
+[license_target]: https://github.com/openbraininstitute/entitysdk/blob/main/LICENSE.txt
+[coverage_badge]: https://codecov.io/github/openbraininstitute/entitysdk/coverage.svg?branch=main
+[coverage_target]: https://codecov.io/github/openbraininstitute/entitysdk?branch=main
+[codeql_badge]: https://github.com/openbraininstitute/entitysdk/actions/workflows/github-code-scanning/codeql/badge.svg
+[codeql_target]: https://github.com/openbraininstitute/entitysdk/actions/workflows/github-code-scanning/codeql
+[pypi_badge]: https://github.com/openbraininstitute/entitysdk/actions/workflows/sdist.yml/badge.svg
+[pypi_target]: https://pypi.org/project/entitysdk/
+

entitysdk-0.1.0/examples/contribution.ipynb

@@ -0,0 +1,201 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "143211ec-83e7-46c2-84bd-ce61f77ba1d0",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "\n",
+    "from rich import print as rprint\n",
+    "\n",
+    "from entitysdk.client import Client\n",
+    "from entitysdk.common import ProjectContext\n",
+    "from entitysdk.models.agent import Organization\n",
+    "from entitysdk.models.contribution import Contribution, Role\n",
+    "from entitysdk.models.morphology import ReconstructionMorphology\n",
+    "\n",
+    "entitycore_api_url = \"http://127.0.0.1:8000\"\n",
+    "project_context = ProjectContext(\n",
+    "    virtual_lab_id=\"a98b7abc-fc46-4700-9e3d-37137812c730\",\n",
+    "    project_id=\"0dbced5f-cc3d-488a-8c7f-cfb8ea039dc6\",\n",
+    ")\n",
+    "client = Client(api_url=entitycore_api_url, project_context=project_context)\n",
+    "token = os.getenv(\"ACCESS_TOKEN\", \"XXX\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "bebd0bea-8d87-4fe5-adcb-b897198aaba6",
+   "metadata": {},
+   "source": [
+    "## Create a Contribution object"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "fd9e9356-0570-41f0-adc3-7ca859d1437b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "agent = client.search_entity(entity_type=Organization, token=token, limit=1).one()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2ef91588-bc83-493e-b90c-2298f814f15e",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rprint(agent)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "0458e9bc-481b-4129-a206-60c546307411",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "role = client.search_entity(entity_type=Role, token=token, limit=1).one()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "0d493ec1-044f-46a0-8310-5e6f00347836",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rprint(role)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "fa2c555c-22d5-41aa-8bf3-86fd87921dc1",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "morphology = client.search_entity(\n",
+    "    entity_type=ReconstructionMorphology, token=token, limit=1\n",
+    ").first()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "efcfdee2-7679-4ae9-90d6-7e70637459ea",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rprint(morphology)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d3daa96f-4acc-46ef-83b4-375d42ab611c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "contribution = Contribution(\n",
+    "    agent=agent,\n",
+    "    role=role,\n",
+    "    entity=morphology,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "653628d2-5ad9-44fb-be9c-8c7488d664ba",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rprint(contribution)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "7ba44524-7710-4643-8a13-ca9575c179e7",
+   "metadata": {},
+   "source": [
+    "## Register it"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "24076fd8-879b-49a7-af65-f0836b6703c2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "registered = client.register_entity(entity=contribution, token=token)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "20859296-1d8c-43a1-ab31-8ad9284ec8eb",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rprint(registered)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3c7ad61f-c2cf-467a-9624-211b0f06efbc",
+   "metadata": {},
+   "source": [
+    "## Retrieve it"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5d904513-4534-450e-8b97-3a0f185f7f6c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "retrieved = client.get_entity(entity_type=Contribution, entity_id=registered.id, token=token)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "891df12c-a76a-42f4-b0e4-bbfae0ab6d72",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rprint(retrieved)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.9"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}