dspace-api-toolkit 0.1.1__py3-none-any.whl

dspace_api_toolkit-0.1.1.dist-info/METADATA

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: dspace-api-toolkit
+Version: 0.1.1
+Summary: Python toolkit for the DSpace 7+ and DSpace-CRIS REST API: items, submissions, bitstreams (streamed large uploads), access control, communities, collections, versioning
+Author: Stefan Szepe
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/sszepe/dspace-api-toolkit
+Project-URL: Documentation, https://github.com/sszepe/dspace-api-toolkit#readme
+Project-URL: Changelog, https://github.com/sszepe/dspace-api-toolkit/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/sszepe/dspace-api-toolkit/issues
+Project-URL: Compatibility matrix, https://github.com/sszepe/dspace-api-toolkit/actions/workflows/integration-matrix.yml
+Keywords: dspace,dspace-cris,repository,rest-api,institutional-repository,open-access
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31
+Requires-Dist: python-dotenv>=1.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.4; extra == "test"
+Requires-Dist: pytest-cov>=4.1; extra == "test"
+Requires-Dist: responses>=0.23; extra == "test"
+Provides-Extra: integration
+Requires-Dist: pytest>=7.4; extra == "integration"
+Requires-Dist: responses>=0.23; extra == "integration"
+Requires-Dist: pyyaml>=6.0; extra == "integration"
+Provides-Extra: dev
+Requires-Dist: dspace-api-toolkit[integration,test]; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Dynamic: license-file
+
+# dspace-api-toolkit
+
+[![CI](https://github.com/sszepe/dspace-api-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/sszepe/dspace-api-toolkit/actions/workflows/ci.yml)
+[![Compatibility matrix](https://github.com/sszepe/dspace-api-toolkit/actions/workflows/integration-matrix.yml/badge.svg)](https://github.com/sszepe/dspace-api-toolkit/actions/workflows/integration-matrix.yml)
+[![PyPI](https://img.shields.io/pypi/v/dspace-api-toolkit.svg)](https://pypi.org/project/dspace-api-toolkit/)
+[![Python](https://img.shields.io/pypi/pyversions/dspace-api-toolkit.svg)](https://pypi.org/project/dspace-api-toolkit/)
+[![License](https://img.shields.io/pypi/l/dspace-api-toolkit.svg)](LICENSE)
+
+A Python toolkit for the REST API of **DSpace 7+** and **DSpace-CRIS**, built
+for repository administrators and integration scripts: batch imports,
+submissions, files of any size, access control, collection setup, versioning -
+and long unattended runs that survive token expiry, rate limits and restarts.
+
+Every feature is tested against mocked HTTP with pytest with a target 
+100% coverage **and** against real DSpace / DSpace-CRIS installations started 
+with Docker Compose; the results form a [compatibility matrix](#compatibility).
+
+```bash
+pip install dspace-api-toolkit
+```
+
+Requires Python 3.10+. The import name of the dspace-api-toolkit in python code 
+using it is `dspace_api`.
+
+## Quick start
+
+```python
+from dspace_api import DSpaceClient, MetadataPatch
+
+client = DSpaceClient("https://repo.example.org/server/api", "admin@example.org", "secret")
+
+# Submit an item through the submission process, with an embargoed file
+result = client.workspace.submit(
+    collection_uuid,
+    {"dc.title": "My thesis", "dc.contributor.author": ["Doe, Jane"], "dc.date.issued": "2026"},
+    files=["thesis.pdf"],
+    file_access_conditions=[{"name": "embargo", "startDate": "2027-01-01"}],
+)
+item_uuid = result["item_uuid"]
+
+# Upload a large file - streamed, constant memory, MD5 verified
+bundle = client.bundles.get_or_create_bundle(item_uuid, "ORIGINAL")
+client.bundles.upload_bitstream(bundle["uuid"], "dataset.zip",
+                                progress=lambda done, total: print(f"{done / total:.0%}"))
+
+# Precise metadata edits
+client.metadata.patch_metadata("item", item_uuid,
+                               MetadataPatch().append("dc.subject", "music").move("dc.contributor.author", 1, 0))
+
+# Check permissions before acting
+if client.authorizations.can(("item", item_uuid), "withdrawItem"):
+    ...
+
+client.close()
+```
+
+More scripts will be added in the [`examples/`](examples/) folder.
+
+## What's covered
+
+| Area | Manager | Highlights |
+|---|---|---|
+| Items | `client.items` | create, read, update, delete; `upsert_metadata`, position-aware upserts, move, mapped collections |
+| Metadata | `client.metadata` | `MetadataPatch` builder (archived items, submission sections, files), PATCH any object, schema/field registry, `ensure_fields()` |
+| Submissions | `client.workspace` | create (empty / external source / BibTeX-RIS file), fill forms by field, upload, file & item access conditions, license, CC license, deposit, one-call `submit()` with validation errors |
+| Bundles & files | `client.bundles` | bundles, streamed uploads of any size, replace, download, primary bitstream, move, format registry |
+| Access control | `client.permissions` | resource policies, remove / grant / restore group access with CSV reports, bulk access control script |
+| Permission checks | `client.authorizations` | `can`, `features_on`, `require`, batch checks, admin scope |
+| Versioning | `client.versions` | create versions, `new_version()` flow, histories, drafts |
+| Communities | `client.communities` | create, hierarchy and tree walk, admin group, logo, *Authorized searches |
+| Collections | `client.collections` | role groups (admin, submitters, item/bitstream read, workflow), read restrictions, submission policies, license, item template, mapped items, harvesting, logo |
+| People & groups | `client.epersons`, `client.groups` | users, registration, end-user agreement, groups and members |
+| Site & config | `client.site`, `client.entity_types` | Terms of Use per language, entity types |
+| Search & browse | `client.discovery` | search configuration, `f.<filter>` filters, paged `iter_search`, `count`, facets with all values (`facet_counts`), browse indexes, entries and items |
+| Review workflow | `client.workflow` | workflow items, `pending_tasks`, claim / approve / reject / unclaim, `review()` in one call, `approve_all_steps`, workflow definitions, steps and actions, supervision orders |
+| Relationships | `client.relationships` | configurable entities (plain DSpace): relationship types, `relate` / `unrelate` by label, `related_items` in order, `reorder`, name variants, `ensure_related` |
+| Vocabularies | `client.vocabulary` | vocabularies and authorities, exact `lookup`, `invalid_values` for import validation, form-field vocabularies, hierarchical trees, `to_metadata_value` |
+
+Every read accepts `all_languages=`, `projection=` and `embed=` (including
+nested embeds with sizes) to shape the response.
+
+## Configuration
+
+Arguments win over environment variables, which win over a `.env` file in the
+working directory (see [`.env.example`](.env.example)):
+
+| Variable | Default | |
+|---|---|---|
+| `DSPACE_URL` | `http://localhost:8080/server/api` | REST API root |
+| `DSPACE_TIMEOUT` | `30` | seconds per request |
+| `DSPACE_MAX_RETRIES` | `3` | retries for 429 / 502 / 503 / 504 and connection errors (idempotent requests; 429 for all) |
+| `DSPACE_RETRY_BACKOFF`, `DSPACE_RETRY_MAX_WAIT` | `1.0`, `30` | exponential backoff with jitter, honours `Retry-After` |
+| `DSPACE_TOKEN_REFRESH_MARGIN` | `60` | refresh the login token this many seconds before it expires |
+| `DSPACE_REAUTHENTICATE` | `true` | log in again after a 401 |
+| `DSPACE_ACCEPT_USER_AGREEMENT` | `false` | DSpace-CRIS: accept the end-user agreement for the logged-in user when the server demands it |
+| `DSPACE_ALL_LANGUAGES` | `false` | default for `projection=allLanguages` (DSpace-CRIS, DSpace 10; left out automatically on DSpace 8/9) |
+
+`DSpaceConfig(env_file=False)` ignores `.env`; `env_file="prod.env"` reads another file.
+
+## Large files
+
+Uploads (`upload_bitstream`, `replace_bitstream`, `workspace.upload_file`)
+stream the multipart body from disk with an exact `Content-Length`: memory
+use stays at one chunk (8 MiB) regardless of file size, the MD5 is computed
+while sending and compared with DSpace's checksum afterwards, and the read
+timeout grows with the file size. The server must allow large requests too:
+
+- DSpace `config/application.properties`: `spring.servlet.multipart.max-file-size`
+  and `max-request-size` (default 512MB)
+- reverse proxy: nginx `client_max_body_size`, `proxy_request_buffering off`, `proxy_read_timeout`
+- Tomcat connector timeout
+
+## Compatibility
+
+The integration suite runs against these Docker Compose stacks (upstream
+compose files of each branch):
+
+| Target | |
+|---|---|
+| DSpace 8.x, 9.x, 10.x | `dspace/dspace` images |
+| DSpace-CRIS 2024.02, 2025.02 | `4science/dspace-cris` images |
+
+You can run the same suite against your own **test** installation, from a
+clone of the repository:
+
+```bash
+git clone https://github.com/sszepe/dspace-api-toolkit && cd dspace-api-toolkit
+pip install -e ".[integration]"
+DSPACE_IT_PASSWORD=... python -m integration.run_matrix --existing \
+    --url https://dspace-test.example.org/server/api --user admin@example.org --name my-test-server
+```
+
+The integration tests require an administrator account. They create and delete test 
+data. 
+
+WARNING: never point the integration matrix to a production instancce!
+
+## Development
+
+```bash
+git clone https://github.com/sszepe/dspace-api-toolkit && cd dspace-api-toolkit
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest                                        # unit tests, 100% coverage gate
+python -m integration.run_matrix -t dspace-9  # regression tests against a Docker stack
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the regression test workflow and
+[integration/README.md](integration/README.md) for the matrix details.
+
+## Related projects
+
+- [dspace-rest-client](https://pypi.org/project/dspace-rest-client/) - the
+  DSpace community's general-purpose Python client.
+
+We are very grateful to the team behind dspace-rest-client. Their work inspired this 
+project, and we learned a great deal from their approach and implementation. As our 
+requirements and goals evolved, we eventually reached a point where we needed to take 
+a different direction and develop our own solution. We sincerely appreciate the 
+foundation they provided and the work they continue to contribute to the DSpace 
+community.
+
+## License
+
+BSD 3-Clause, see [LICENSE](LICENSE).

dspace_api_toolkit-0.1.1.dist-info/RECORD

@@ -0,0 +1,32 @@
+dspace_api/__init__.py,sha256=hQ2NozrMopwqhO8qCy0hEA-sqvFfe_Y3t9BS8ZO-L3c,3162
+dspace_api/_base.py,sha256=XbxAQamgpE5OCpczSh1_w6MIECKBBQTaPrZ4gixEPzU,17817
+dspace_api/_containers.py,sha256=M_Wey1_9TfOtz-xFt9lgSOsNHd_jy1-BgTH0ig4_91k,9455
+dspace_api/_version.py,sha256=SQ28QZrV0H9EAMO0c5auOMcGNbDOqDFVROu23L9M5YY,141
+dspace_api/auth.py,sha256=OnfcakZYqTyHWmq2Wrmy4xhwAl6P9_yq4u5BhLyrexk,16946
+dspace_api/authorizations.py,sha256=FCllHqNGpe1PtuL0vy-CSmy5KDLQVjXaYI4H-JZ-_CU,21637
+dspace_api/bundles.py,sha256=sIqC2OkWkhqZZiZJHDCVGumLSEYLMTkP_EG61ZDs-2g,53024
+dspace_api/collections.py,sha256=6Eg1an772tBrHEOkoHjjAg8yfEUIDlYcJQEQ7Tv2PqE,47200
+dspace_api/communities.py,sha256=efx4_8n06JxuuJHIpBwr-ftAZS_Hb_Mx-vQItTgncBI,16568
+dspace_api/config.py,sha256=TaE5RwptaY1noxBOLeAcnLG0OufZ5OCnSSahDITZE5g,9805
+dspace_api/discovery.py,sha256=xUWnGQzr4SJHhKubhOvINk1M7LaGmDa_VXxkEszdJZk,43071
+dspace_api/entity_types.py,sha256=7AwR9wpgb7ahe5sXcHlLkrvdijMoJLk_-AtIag0AGuA,5717
+dspace_api/epersons.py,sha256=WysnatG4MMa9MCaFbMdtmhVM_WbSV2boYot9W_VIMAQ,31193
+dspace_api/exceptions.py,sha256=sMCO32aedUlA9CDly3zUkifj6iHGa3Q-nLMmecNOSOc,3613
+dspace_api/groups.py,sha256=_hYHeNlTUxhbb6Wamh5gBdZ5vHLjK2zFnF9nFO-bkV8,28597
+dspace_api/items.py,sha256=QADNE8pQle_iMAAq2aigwHWToDCcoOiPmO3kHfHOWJ4,20407
+dspace_api/metadata.py,sha256=YYUM902tYsQGH92TfuaDKgUvC6CyH3Ca6vEVESYobpY,32164
+dspace_api/permissions.py,sha256=6IHCCicOhWe6_5gBJ4LvzbttWkRxuW0EP7MdWu3o2ZY,50569
+dspace_api/projection.py,sha256=KIhrO5RDib4Cjp6WbZ0gqXwC-TGhPbCmkDbsRFrZlr4,11570
+dspace_api/relationships.py,sha256=wwAwP2I2HrExXny-KzYyVWmdZYNyYOBPnmQbZnHsPsA,34087
+dspace_api/session.py,sha256=8pkbrk00sPTOPaELHCTfgAGdtmkJrn_MNWkRIqWSdck,22845
+dspace_api/site.py,sha256=cxsSGHS43AP0Ofr4tdaItcD3076Kscm4q9hrK7fL_ss,4014
+dspace_api/utils.py,sha256=SLcvNrX2zKG91kQhl8LBWMBHlbH7I8Pyf6f83H7B_3A,14747
+dspace_api/versions.py,sha256=W8m0LBjjTWth93huPcfY7usbWIMAsTO-2jgbcL-xDMA,12504
+dspace_api/vocabulary.py,sha256=NyjiUgZXP6uLTqz7Wh2YHjrvbotrJhWcN67ZfLzHqj8,15545
+dspace_api/workflow.py,sha256=QzNm-GKR8VpKUzlwZkNl90tINekZeQtrjtmkjvLmLjs,37398
+dspace_api/workspaces.py,sha256=V1ffWNEC7ruVousgeJrWcmmUp5x-J7BtNPJSNT7bVwM,61538
+dspace_api_toolkit-0.1.1.dist-info/licenses/LICENSE,sha256=cGdr2cpxWWiTzXPtXKHgjt4taK_Sa5q_5IqKo6HZA7Q,1516
+dspace_api_toolkit-0.1.1.dist-info/METADATA,sha256=Ic2llT6RpxEon8GLJTvMm-JLi1g1hRYcejO1x6khQ5Y,11078
+dspace_api_toolkit-0.1.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+dspace_api_toolkit-0.1.1.dist-info/top_level.txt,sha256=3r1x-M8dFCKtGBoM3xmO51XqD7bUQHh2ezP-GBh1Q04,11
+dspace_api_toolkit-0.1.1.dist-info/RECORD,,

dspace_api_toolkit-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

dspace_api_toolkit-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Stefan Szepe and contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

dspace_api_toolkit-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+dspace_api