Skip to main content

dspace-api-toolkit

CI Compatibility matrix PyPI Python 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.

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

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/ 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.

Acting as another user ("login as")

An administrator's session can send requests as another eperson with the X-On-Behalf-Of header. DSpace then applies that user's permissions and, for example, records them as the submitter:

with client.on_behalf_of("jane@example.org"):          # UUID, email or eperson dict
    client.authorizations.can(item, Feature.CAN_EDIT_METADATA)   # Jane's permissions
    client.workspace.submit(collection_uuid, {"dc.title": "..."})  # Jane is the submitter

The server needs webui.user.assumelogin = true (off by default in plain DSpace, on in DSpace-CRIS). The logged-in user must be an administrator, and the target must not be one. DSpace-CRIS allows administrators as targets with webui.user.assumelogin.admin = true.

On entering the block, the toolkit checks once that the server accepts the header. If it doesn't, it raises OnBehalfOfError with the actual reason: the feature is off, the eperson is unknown, the target is an administrator, or you are not an administrator. DSpace itself only answers "400 Authentication request is invalid". Pass verify=False to skip the check.

Only requests of this client in the current thread or asyncio task carry the header. The toolkit's own login, token refresh and status requests never do. A 403 inside the block stays an AuthorizationError: the other user is not allowed to do that.

Configuration

Arguments win over environment variables, which win over a .env file in the working directory (see .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:

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

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 for the regression test workflow and integration/README.md for the matrix details.

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.

Metadata

Release files for dspace-api-toolkit 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for dspace-api-toolkit 0.2.0
File Size Uploaded Provenance Actions
dspace_api_toolkit-0.2.0.tar.gz 238.4 kB With provenance Details for dspace_api_toolkit-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for dspace-api-toolkit 0.2.0
File Interpreter ABI Platform Actions
dspace_api_toolkit-0.2.0-py3-none-any.whl Python 3 none any Details for dspace_api_toolkit-0.2.0-py3-none-any.whl

Total release size: 393.2 kB

Release files / dspace_api_toolkit-0.2.0.tar.gz

Download URL dspace_api_toolkit-0.2.0.tar.gz
Size 238.4 kB
Tags Source
SHA-256 checksum
How to use checksums
b810420d74d258d0ab3a8ee7f4558b5cb4813fdfe2261b9a3494d6cf8b02fa76
BLAKE2b-256 checksum
How to use checksums
f957633a1a28064d79e51679608b49295a3200bc8f2832aa79bd3a005bf6c86f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Release files / dspace_api_toolkit-0.2.0-py3-none-any.whl

Download URL dspace_api_toolkit-0.2.0-py3-none-any.whl
Size 154.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c4fef6604dda75c59b42527e6e134b1add00d2864542679c09c54af55e6d7159
BLAKE2b-256 checksum
How to use checksums
12e8af4b3fd8e412b8f6d477088d7724bc46f14e2922b8b4ef3405014ffb692d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Security for dspace-api-toolkit 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for dspace_api_toolkit-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page