Server Classes

This module contains classes for managing connections to Dataverse servers.

DataverseServer

The main class for interacting with a Dataverse server installation.

class dartfx.dataverse.DataverseServer(server=None, api_key=None, on_api_error='raise', on_api_success_return='json', session=None, lookup_installation=True, *, installation, user_agent='dartfx-dataverse/0.2.0', ssl_verify=True)

Bases: BaseModel

model_config = {'arbitrary_types_allowed': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

installation: ServerInstallation

api_key: str | None

on_api_error: Literal['raise', 'none']

on_api_success_return: Literal['json', 'text', 'response']

session: CachedSession

user_agent: str

ssl_verify: bool

__init__(server=None, api_key=None, on_api_error='raise', on_api_success_return='json', session=None, lookup_installation=True, **kwargs)

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

request(method, path, description=None, headers=None, success=200, return_type=None, **kwargs)

Call the API.

get_request(path, description=None, headers=None, success=200, return_type=None, **kwargs)

Call the API using the GET method.

post_request(path, description=None, headers=None, success=200, **kwargs)

Call the API using the POST method.

get_info_api_terms()

Get API Terms of Use.

The response contains the text value inserted as API Terms of use which uses the database setting :ApiTermsOfUse:.

get_info_export_formats()

Get the available export formats, including custom formats. Introduced in version 6.5

get_info_server()

Get the server name.

This is useful when a Dataverse installation is composed of multiple app servers behind a load balancer.

get_server_info()

Alias for get_info_server.

get_info_version()

Get the Dataverse installation version. The response contains the version and build numbers:.

get_info_zip_download_limit()

Get the configured zip file download limit. The response contains the long value of the limit in bytes.

get_metadatablocks()

Lists brief info about all metadata blocks registered in the system.

get_metadatablock(identifier)

Return data about the block whose identifier is passed, including allowed controlled vocabulary values. identifier can either be the block’s database id, or its name (i.e. “citation”).

get_dataset(identifier)

Get information about a specific dataset by its persistent identifier.

Parameters:

identifier (str) – Persistent identifier (e.g., “doi:10.5683/SP3/FNS9EF”)

get_dataset_export(identifier, exporter)

Get a dataset in a specific export format.

Parameters:

• identifier (str) – Persistent identifier (e.g., “doi:10.5683/SP3/FNS9EF”)

• exporter (str) – Name of the exporter (e.g., “ddi”, “oai_dc”, “schema.org”)

search_simple(q, **kwargs)

Search for dataverses, datasets, and files using a simple query string.

Parameters:

• q (str) – The search query string.

• **kwargs (Any) – Additional search parameters (type, sort, order, per_page, start, etc.)

search(parameters)

Search for dataverses, datasets, and files.

References: - https://guides.dataverse.org/en/latest/api/search.html - https://github.com/IQSS/dataverse/issues/2558

ServerInstallation

Represents a Dataverse installation with its metadata.

class dartfx.dataverse.ServerInstallation(*, name=None, description=None, lat=None, lng=None, hostname=None, metrics=False, launch_year=None, country=None, continent=None, harvesting_sets=None, core_trust_seals=None, gdcc_member=None, doi_authority=None, board=None, contact_email=None)

Bases: BaseModel

Represents a dataverse installation. Based on the content of the data.json file in the dataverse-installations repository at https://github.com/IQSS/dataverse-installations

name: str | None

description: str | None

lat: float | None

lng: float | None

hostname: str | None

metrics: bool | None

launch_year: str | None

country: str | None

continent: str | None

harvesting_sets: list[str] | None

core_trust_seals: list[str] | None

gdcc_member: bool | None

doi_authority: str | None

board: str | None

contact_email: str | None

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Functions

dartfx.dataverse.fetch_dataverse_installations()

Returns a list of dataverse installations from the main branch of the dataverse-installations GitHub repo

Examples

Creating a Server Connection

from dartfx.dataverse import DataverseServer, ServerInstallation

# Create installation object
installation = ServerInstallation(
    name="Harvard Dataverse",
    hostname="dataverse.harvard.edu"
)

# Create server connection
server = DataverseServer(installation)

With API Key

server = DataverseServer(
    server=installation,
    api_key="your-api-key-here"
)

Custom Configuration

import requests_cache
from datetime import timedelta

# Create custom session
session = requests_cache.CachedSession(
    cache_name='my_cache',
    expire_after=timedelta(hours=1)
)

# Create server with custom config
server = DataverseServer(
    server=installation,
    session=session,
    ssl_verify=True,
    on_api_error="raise"
)

Getting Server Information

# Get server info
info = server.get_server_info()
print(f"Version: {info['data']['version']}")

# Get metadata blocks
blocks = server.get_metadatablocks()
for block in blocks['data']:
    print(block['name'])