### Basic Dataverse MCP Server Setup

Source: https://gdcc.github.io/pyDataverse/mcp/server

This minimal example demonstrates how to create an MCP server for a single Dataverse installation. It initializes the MCP server, connects to Dataverse, and registers Dataverse tools.

```python
from fastmcp import FastMCP
from pyDataverse import Dataverse
from pyDataverse.mcp import DataverseMCP


# Step 1: Create the MCP server
mcp = FastMCP(name="My Dataverse Server")


# Step 2: Connect to your Dataverse installation
dataverse = Dataverse(
    base_url="https://demo.dataverse.org",
    verbose=0  # Reduce logging noise
)


# Step 3: Add Dataverse tools to the MCP server
DataverseMCP(dataverse=dataverse).to_mcp(mcp)


# Step 4: Run the server
if __name__ == "__main__":
    mcp.run()

```

--------------------------------

### Full pyDataverse Workflow Example

Source: https://gdcc.github.io/pyDataverse/getting-started

This script demonstrates connecting to a Dataverse installation, selecting a collection and dataset, reading file contents, updating dataset metadata, and creating a new file.

```python
from pyDataverse import Dataverse


# 1. Connect to a Dataverse installation
dv = Dataverse(base_url="https://demo.dataverse.org")


# 2. Select a collection and a dataset
collection = dv.collections["my-collection"]
dataset = collection.datasets["doi:10.5072/FK2/ABC123"]


# 3. Open a file from the dataset and read its contents
with dataset.open("data/example.txt", mode="r") as f:
    text = f.read()


# 4. Update metadata of the dataset
dataset["citation"]["title"] = "My new title"
dataset.update_metadata()


# 4. Create a new file in the dataset from in memory content
with dataset.open("data/hello.txt", mode="w") as f:
    f.write("Hello, Dataverse!")

```

--------------------------------

### Get All Key Metrics Summary

Source: https://gdcc.github.io/pyDataverse/high-level/dataverse

Fetch a comprehensive summary DataFrame containing all key metrics for the Dataverse installation. This is ideal for obtaining a high-level overview of the installation's status.

```python
# Get a summary DataFrame with all key metrics
# This is convenient when you want an overview of everything
summary = dv.metrics.df
```

--------------------------------

### Install pyDataverse using uv

Source: https://gdcc.github.io/pyDataverse/installation

Install pyDataverse from PyPI using the uv package manager.

```bash
uv pip install pyDataverse
```

--------------------------------

### Install pyDataverse from Local Source using uv

Source: https://gdcc.github.io/pyDataverse/installation

Install pyDataverse directly from a local source checkout using uv.

```bash
uv pip install .
```

--------------------------------

### Install pyDataverse with Test Dependencies using uv

Source: https://gdcc.github.io/pyDataverse/installation

Install pyDataverse with test dependencies using uv's sync command.

```bash
uv sync --extra tests
```

--------------------------------

### Example: Fetching Multiple Datasets

Source: https://gdcc.github.io/pyDataverse/reference/api/native

Demonstrates how to use the `get_datasets` method with a list of dataset identifiers.

```python
>>> api = NativeApi(base_url="https://demo.dataverse.org")
>>> datasets = api.get_datasets([123, 456, "doi:10.11587/8H3N93"])
```

--------------------------------

### Get All Available Licenses

Source: https://gdcc.github.io/pyDataverse/high-level/dataverse

Retrieve a list of all licenses that are currently configured and available for use within the Dataverse installation. This is useful for dataset creators and for code that needs to handle different license types.

```python
# Get all available licenses
licenses = dv.licenses
```

--------------------------------

### ApiTokenAuth Example

Source: https://gdcc.github.io/pyDataverse/reference/auth

Demonstrates how to use ApiTokenAuth to authenticate with the DataAccessApi. Ensure the API_TOKEN environment variable is set.

```python
import os
from pyDataverse.api import DataAccessApi
base_url = ‘https://demo.dataverse.org’
api_token_auth = ApiTokenAuth(os.getenv(‘API_TOKEN’))
api = DataAccessApi(base_url, api_token_auth)

```

--------------------------------

### Install pyDataverse

Source: https://gdcc.github.io/pyDataverse/getting-started

Install the pyDataverse library using pip. You may need to use `pip3` or `python -m pip` depending on your system configuration.

```bash
pip install pyDataverse
```

--------------------------------

### Running the MCP Server

Source: https://gdcc.github.io/pyDataverse/mcp/server

Execute the saved Python script to start the MCP server.

```bash
python server.py
```

--------------------------------

### BearerTokenAuth Example

Source: https://gdcc.github.io/pyDataverse/reference/auth

Demonstrates how to use BearerTokenAuth to authenticate with the DataAccessApi. Ensure the OAUTH_TOKEN environment variable is set.

```python
import os
from pyDataverse.api import DataAccessApi
base_url = ‘https://demo.dataverse.org’
bearer_token_auth = OAuthBearerTokenAuth(os.getenv(‘OAUTH_TOKEN’))
api = DataAccessApi(base_url, bearer_token_auth)

```

--------------------------------

### Install pyDataverse with Test Dependencies using poetry

Source: https://gdcc.github.io/pyDataverse/installation

Install pyDataverse along with its test dependencies using poetry's extras.

```bash
poetry install --extras tests
```

--------------------------------

### Install pyDataverse from Local Source using pip

Source: https://gdcc.github.io/pyDataverse/installation

Install pyDataverse directly from a local source checkout using pip.

```bash
python -m pip install .
```

--------------------------------

### Install pyDataverse with Test Dependencies using pip

Source: https://gdcc.github.io/pyDataverse/installation

Install pyDataverse along with its test dependencies using pip.

```bash
python -m pip install ".[tests]"
```

--------------------------------

### Install pyDataverse Runtime Dependencies using poetry

Source: https://gdcc.github.io/pyDataverse/installation

Install only the runtime dependencies for pyDataverse using poetry.

```bash
poetry install
```

--------------------------------

### DataverseHub.installations

Source: https://gdcc.github.io/pyDataverse/reference/api/hub

Retrieve the status of all Dataverse installations.

```APIDOC
## DataverseHub.installations

### Description
Retrieve the status of all Dataverse installations.

### Method
GET

### Endpoint
/api/v1/installations

### Parameters
#### Query Parameters
- **limit** (int) - Optional - The maximum number of installations to return.
- **offset** (int) - Optional - The number of installations to skip.

### Response
#### Success Response (200)
- **installations** (List[InstallationStatus]) - A list of Dataverse installation statuses.

### Response Example
{
  "installations": [
    {
      "name": "Harvard Dataverse",
      "url": "https://dataverse.harvard.edu",
      "version": "5.11",
      "status": "active"
    }
  ]
}
```

--------------------------------

### Connect to Multiple Dataverse Installations

Source: https://gdcc.github.io/pyDataverse/mcp/server

Configure a single MCP server to connect to multiple Dataverse installations. This is useful for federated search or cross-repository analysis. The server automatically makes tools available for each installation and routes requests based on LLM decisions.

```python
from fastmcp import FastMCP
from pyDataverse import Dataverse
from pyDataverse.mcp import DataverseMCP


# Create the MCP server
mcp = FastMCP(name="Multi-Dataverse Server")


# Connect to multiple Dataverse installations
dataverses = {
    "demo": Dataverse("https://demo.dataverse.org"),
    "harvard": Dataverse("https://dataverse.harvard.edu"),
    "darus": Dataverse("https://darus.uni-stuttgart.de"),
}


# Add all installations to the MCP server
DataverseMCP(dataverse=dataverses).to_mcp(mcp)


if __name__ == "__main__":
    mcp.run()

```

--------------------------------

### Paginate Search Results - Python

Source: https://gdcc.github.io/pyDataverse/apis/search

Handle large result sets by implementing pagination. Specify the number of results per page (`per_page`) and the starting offset (`start`). Smaller page sizes are generally more efficient. The output includes pagination details like start, count in response, and total count.

```python
from pyDataverse.api import SearchApi
from pyDataverse.api.search import QueryOptions


api = SearchApi("https://demo.dataverse.org")


# First page (default: 10 results)
options = QueryOptions(per_page=20, start=0)
results = api.search("climate", options)
print(f"Results {results.start} to {results.start + results.count_in_response} of {results.total_count}")


# Second page
options = QueryOptions(per_page=20, start=20)
results = api.search("climate", options)
```

--------------------------------

### Connect to Dataverse (Read-Only)

Source: https://gdcc.github.io/pyDataverse/high-level/dataverse

Create a Dataverse instance for browsing public datasets and reading metadata. This requires only the base URL of the Dataverse installation.

```python
from pyDataverse import Dataverse


# Connect to a Dataverse instance (read-only access)
# This works for browsing public datasets and reading metadata
dv = Dataverse(base_url="https://demo.dataverse.org")
```

--------------------------------

### Initialize SearchApi for Public Access

Source: https://gdcc.github.io/pyDataverse/apis/search

Create an instance of SearchApi to search public content on a Dataverse installation. No API token is needed for this.

```python
from pyDataverse.api import SearchApi


# Public access (searches public content)
api = SearchApi(base_url="https://demo.dataverse.org")
```

--------------------------------

### NativeApi Initialization

Source: https://gdcc.github.io/pyDataverse/apis/native

Instantiate the NativeApi class with the base URL of your Dataverse installation. An optional API token can be provided for authenticated operations.

```APIDOC
## NativeApi Initialization

### Description
To start using the Native API, create a `NativeApi` instance with the base URL of your Dataverse installation and, if needed, an API token for authenticated operations.

### Parameters
* **`base_url`** (str, required): The base URL of the Dataverse installation, such as `"https://demo.dataverse.org"` or `"https://dataverse.harvard.edu"`. All API calls are constructed from this URL.
* **`api_token`** (str, optional): API token used for endpoints that require authentication, such as creating datasets, uploading files, or changing permissions.
* **`api_version`** (str, optional): API version string passed to the Dataverse server. This is typically left at its default unless you have a specific reason to override it.

### Request Example
```python
from pyDataverse.api import NativeApi

# Read-only access (public data and metadata)
api = NativeApi(base_url="https://demo.dataverse.org")

# Authenticated access for creating and modifying content
api = NativeApi(
    base_url="https://dataverse.example.edu",
    api_token="your-api-token-here",
)
```
```

--------------------------------

### Initialize NativeApi for Read-Only Access

Source: https://gdcc.github.io/pyDataverse/apis/native

Create a NativeApi instance for public data and metadata access by providing only the base URL of the Dataverse installation.

```python
from pyDataverse.api import NativeApi


# Read-only access (public data and metadata)
api = NativeApi(base_url="https://demo.dataverse.org")
```

--------------------------------

### Initialize Dataverse and Access Metrics

Source: https://gdcc.github.io/pyDataverse/reference/dataverse/metrics

Instantiate a Dataverse object and access its metrics attributes and methods. This is the starting point for all metrics-related operations.

```python
from pyDataverse.dataverse import Dataverse
dv = Dataverse("https://demo.dataverse.org")
```

--------------------------------

### Initialize SemanticApi for Read-Only Access

Source: https://gdcc.github.io/pyDataverse/apis/semantic

Create a SemanticApi instance for read-only access to public datasets by providing the base URL of your Dataverse installation.

```python
from pydataverse.api import SemanticApi


# Read-only access (public datasets)
api = SemanticApi(base_url="https://demo.dataverse.org")
```

--------------------------------

### Create and Activate Virtual Environment

Source: https://gdcc.github.io/pyDataverse/installation

Before installing pyDataverse, create and activate a Python virtual environment. This isolates project dependencies.

```bash
python -m venv .venv
source .venv/bin/activate
```

--------------------------------

### Complete Dataset Workflow Example

Source: https://gdcc.github.io/pyDataverse/high-level/dataset

Demonstrates a full cycle of creating a dataset, adding local files, uploading to a collection, and then fetching and working with the dataset. Requires initialization with Dataverse connection details.

```python
from pyDataverse import Dataverse


# Initialize connection
dv = Dataverse(
    base_url="https://demo.dataverse.org",
    api_token="your-token"
)


# Create a dataset
dataset = dv.create_dataset(
    title="Experimental Results 2024",
    description="Results from machine learning experiments",
    authors=[{"name": "Dr. Jane Smith", "affiliation": "Research Lab"}],
    contacts=[{"name": "Dr. Jane Smith", "email": "jane@lab.edu"}],
    subjects=["Computer and Information Science", "Engineering"]
)


# Add files by writing them
with dataset.open("data/results.csv", mode="w", description="Main results") as f:
    f.write("experiment,accuracy,loss\n")
    f.write("exp1,0.95,0.05\n")
    f.write("exp2,0.92,0.08\n")


with dataset.open("data/readme.txt", mode="w") as f:
    f.write("This dataset contains experimental results.\n")


# Upload the dataset to a collection (files written via open() are included)
dataset.upload_to_collection("research-lab")


# Upload additional local files after the dataset is uploaded
dataset.upload_file("/path/to/analysis.py", "code/analysis.py")


# Verify the upload
print(f"Dataset uploaded with identifier: {dataset.identifier}")
print(f"Dataset persistent identifier: {dataset.persistent_identifier}")


# Later, fetch and work with the dataset
fetched_dataset = dv.fetch_dataset(dataset.persistent_identifier)


# Read tabular data
df = fetched_dataset.open_tabular("data/results.csv")
print(df.head())


# Open in browser to view
fetched_dataset.open_in_browser()
```

--------------------------------

### Initialize DataverseFS and List Files

Source: https://gdcc.github.io/pyDataverse/filesystem/overview

Instantiate DataverseFS with a Dataverse URL and dataset identifier. Then, list the root directory of the dataset.

```python
from pyDataverse.filesystem import DataverseFS


fs = DataverseFS(
    base_url="https://demo.dataverse.org",
    identifier="doi:10.5072/FK2/ABCDEF",
)


fs.ls("/")                                  # list files
```

--------------------------------

### Get Total Content Counts

Source: https://gdcc.github.io/pyDataverse/high-level/dataverse

Retrieve the total counts for datasets, dataverses (collections), files, and downloads from the Dataverse installation. These metrics provide a quick overview of the installation's scale and usage.

```python
# Get total counts for different content types
total_datasets = dv.metrics.total("datasets")  # How many datasets exist
total_collections = dv.metrics.total("dataverses")  # How many collections exist
total_files = dv.metrics.total("files")  # How many files exist
total_downloads = dv.metrics.total("downloads")  # How many times files have been downloaded
```

--------------------------------

### Get Pydantic Models for Metadata Blocks

Source: https://gdcc.github.io/pyDataverse/high-level/dataverse

Retrieves Pydantic model classes for all available metadata blocks in a Dataverse installation. This dictionary can be used to access and instantiate models for specific blocks like 'citation'.

```python
# Get Pydantic model classes for all metadata blocks
# This returns a dictionary mapping block names to their model classes
blocks = dv.to_pydantic()


# Access a specific block model
# For example, get the model for the citation block
citation_block = blocks["citation"]
```

--------------------------------

### Complete pyDataverse Collection Management Example

Source: https://gdcc.github.io/pyDataverse/high-level/collection

Demonstrates a full workflow including initializing a connection, fetching, browsing, creating, and updating collections and datasets. Includes file uploads and metadata management.

```python
from pyDataverse import Dataverse


# Initialize connection
dv = Dataverse(
    base_url="https://demo.dataverse.org",
    api_token="your-token"
)


# Fetch an existing collection
collection = dv.fetch_collection("research-lab")


# View collection metadata
print(f"Collection: {collection.metadata.name}")
print(f"Description: {collection.metadata.description}")


# Browse datasets in the collection
print("\nDatasets in collection:")
for dataset in collection.datasets:
    print(f"  - {dataset.title} ({dataset.identifier})")


# Browse sub-collections
print("\nSub-collections:")
for sub_coll in collection.collections:
    print(f"  - {sub_coll.metadata.name} ({sub_coll.identifier})")


# Create a new dataset in the collection
new_dataset = collection.create_dataset(
    title="Experimental Results 2024",
    description="Results from our latest experiments",
    authors=[{"name": "Dr. Jane Smith", "affiliation": "Research Lab"}],
    contacts=[{"name": "Dr. Jane Smith", "email": "jane@lab.edu"}],
    subjects=["Physics", "Engineering"]
)


# Add files to the dataset
with new_dataset.open("data/results.csv", mode="w") as f:
    f.write("experiment,result\n")
    f.write("exp1,0.95\n")


# Create a sub-collection for a specific project
project_collection = collection.create_collection(
    alias="project-alpha",
    name="Project Alpha",
    description="Datasets for Project Alpha",
    affiliation="Research Lab",
    dataverse_type="RESEARCH_PROJECTS",
    dataverse_contacts=["project@lab.edu"]
)


# Create a dataset in the sub-collection
project_dataset = project_collection.create_dataset(
    title="Project Alpha Data",
    description="Data collected for Project Alpha",
    authors=[{"name": "Project Lead", "affiliation": "Research Lab"}],
    contacts=[{"name": "Project Lead", "email": "lead@lab.edu"}],
    subjects=["Engineering"]
)


# Update collection metadata
collection.update_metadata(
    description="Updated description: A collection for research lab datasets and publications"
)


# Check collection size
print(f"\nCollection has {len(collection)} direct children")
```

--------------------------------

### Getting Collection Contents

Source: https://gdcc.github.io/pyDataverse/apis/native

Get immediate datasets and sub-collections within a collection using `get_collection_contents`.

```APIDOC
## GET /api/v1/dataverses/:identifier/contents

### Description
Retrieves the immediate datasets and sub-collections contained within a specified collection.

### Method
GET

### Endpoint
/api/v1/dataverses/:identifier/contents

### Parameters
#### Path Parameters
- **:identifier** (string) - Required - The alias or ID of the collection whose contents are to be retrieved.

### Response
#### Success Response (200)
- **datasets** (array) - A list of datasets within the collection.
- **dataverses** (array) - A list of sub-collections within the collection.

### Response Example
{
  "example": "{\"datasets\": [...], \"dataverses\": [...]}"
}
```

--------------------------------

### Initialize Dataverse and Fetch Collection by Alias

Source: https://gdcc.github.io/pyDataverse/high-level/collection

Initializes a Dataverse client and fetches a collection using its string alias. Ensure the Dataverse server URL is correct.

```python
from pyDataverse import Dataverse

dv = Dataverse("https://demo.dataverse.org")

# Fetch a collection by alias
collection = dv.fetch_collection("harvard")
```

--------------------------------

### Initialize DataverseFS from Dataset URL

Source: https://gdcc.github.io/pyDataverse/filesystem/connecting

Create a DataverseFS instance by parsing a standard Dataverse dataset URL, which automatically extracts connection details.

```python
fs = DataverseFS.from_url(
    "https://demo.dataverse.org/dataset.xhtml?persistentId=doi:10.5072/FK2/ABCDEF",
    api_token="your-token",
)
```

--------------------------------

### Get Dataset Private URL

Source: https://gdcc.github.io/pyDataverse/reference/api/native

Retrieve the existing private URL for a dataset. Use this to get anonymous access to unpublished datasets for review.

```python
get_dataset_private_url(self, identifier: str) -> dataset.PrivateUrl
```

--------------------------------

### Create Dataverse Instance and Dataset

Source: https://gdcc.github.io/pyDataverse/reference/dataverse/dataverse

Instantiate the Dataverse class with a base URL and create a dataset using all available metadata blocks. Access and modify metadata block fields.

```python
dv = Dataverse(base_url=“https://demo.dataverse.org”)

# Create a dataset with all available metadata blocks
dataset = dv.create_dataset()

# Access metadata blocks
dataset.metadata_blocks[“citation”].title = “My Dataset Title”
```

--------------------------------

### Performing a Basic Search

Source: https://gdcc.github.io/pyDataverse/apis/search

Demonstrates how to initialize the SearchApi and perform a basic search query. It also shows how to access key information from the search results such as total count, count in the current response, and starting index. The code iterates through the returned items, printing their type, name, description, and URL if available.

```APIDOC
## Search API - Basic Search

### Description
Performs a search query and retrieves results. This method allows users to find dataverse resources based on a given query string.

### Method
`search(query: str, options: Optional[QueryOptions] = None)`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **query** (str) - Required - The search term to look for.
- **options** (QueryOptions) - Optional - An object to specify search options like facets, pagination, etc.

### Request Example
```python
from pyDataverse.api import SearchApi

api = SearchApi("https://demo.dataverse.org")
results = api.search("climate change")

# Accessing results metadata
print(f"Total results: {results.total_count}")
print(f"Results in page: {results.count_in_response}")
print(f"Starting at: {results.start}")

# Iterating through items
if results.items:
    for item in results.items:
        print(f"\n{item.type.upper()}: {item.name}")
        if item.description:
            print(f"  {item.description}")
        if item.url:
            print(f"  URL: {item.url}")
```

### Response
#### Success Response
A `SearchResponse` object containing search results and metadata.
- **total_count** (int) - The total number of matching results across all pages.
- **count_in_response** (int) - The number of results included in the current response.
- **start** (int) - The starting index of the results in the current response.
- **items** (list) - A list of result items, each with properties like type, name, description, and URL.

#### Response Example
```json
{
  "total_count": 150,
  "count_in_response": 10,
  "start": 0,
  "items": [
    {
      "type": "dataset",
      "name": "Climate Change Impacts Dataset",
      "description": "A dataset detailing the impacts of climate change.",
      "url": "/dataset.xhtml?persistentId=doi:10.5072/FK2/ABCDEF"
    }
    // ... more items
  ]
}
```
```

--------------------------------

### Get Datasets by Subject

Source: https://gdcc.github.io/pyDataverse/apis/metrics

Use `get_datasets_by_subject` to retrieve a breakdown of datasets grouped by subject area. This snippet shows how to get the data and analyze the distribution.

```python
from pyDataverse.api import MetricsApi


api = MetricsApi("https://demo.dataverse.org")


# Get datasets grouped by subject
df = api.get_datasets_by_subject()
print(df.head())


# Analyze distribution
print(f"Total subjects: {len(df)}")
print(f"Most popular subject: {df.loc[df['count'].idxmax()]['subject']}")
```

--------------------------------

### Get Collection Graph

Source: https://gdcc.github.io/pyDataverse/reference/dataverse/collection

Retrieves the RDF graph for a collection using the 'OAI_ORE' format. This is useful for getting a comprehensive semantic view of all content within a collection.

```python
collection = dataverse.get_collection("my-collection")
graph = collection.graph("OAI_ORE")
print(f"Collection graph contains {len(graph)} triples")
```

--------------------------------

### open

Source: https://gdcc.github.io/pyDataverse/reference/filesystem/dvfs

Opens a file, returning a Dataverse-aware handle. Binary modes defer to fsspec, while text modes are wrapped to retain Dataverse-specific attributes.

```APIDOC
## open

### Description
Open a file, returning a Dataverse-aware handle. Binary modes defer to fsspec, which returns the :class:`DataverseFileReader` / :class:`DataverseFileWriter` directly. Text modes are wrapped in :class:`DataverseTextIO` instead of a plain :class:`io.TextIOWrapper` so the Dataverse-specific surface (`id`, `persistent_id`, `metadata`) stays reachable on the handle.

### Method Signature
`open(self, path: str, mode: str = 'rb', block_size = None, cache_options = None, compression = None, metadata: Optional[UploadBody] = None, **kwargs)`

### Parameters
#### Path Parameters
- **path** (str) - Required - Path to the file.
- **mode** (str) - Optional - Mode to open the file ('rb' for read binary, 'wb' for write binary, 'r' for read text, 'w' for write text). (default: 'rb')
- **block_size** - Optional - Block size for reading/writing.
- **cache_options** - Optional - Options for caching.
- **compression** - Optional - Compression type.
- **metadata** (Optional[UploadBody]) - Optional - Metadata for upload (write mode only).
```

--------------------------------

### total

Source: https://gdcc.github.io/pyDataverse/reference/dataverse/metrics

Get the total count for a type of entity (e.g., all datasets, files, downloads, dataverses). Optionally, specify a date to get the value for a given month.

```APIDOC
## Method: total

### Description
Get the total count for a type of entity (e.g., all datasets, files, downloads, dataverses).

### Method Signature
```python
total(self, data_type: DataType, date_to_month: Optional[Union[str, date]] = None) -> int
```

### Parameters
#### Path Parameters
- None

#### Query Parameters
- **data_type** (DataType) - Required - One of ‘dataverses’, ‘datasets’, ‘files’, or ‘downloads’.
- **date_to_month** (Optional[Union[str, date]]) - Optional - If provided, gives the value for a given month (‘YYYY-MM’ or date object). Defaults to None.

### Request Example
```python
# Get total datasets
dv.metrics.total("datasets")

# Get total downloads for January 2024
dv.metrics.total("downloads", "2024-01")
```

### Response
#### Success Response (200)
- **return value** (int) - Total count for the given type and period.
```

--------------------------------

### Listing Dataset Files from Command Line

Source: https://gdcc.github.io/pyDataverse/filesystem/pandas

Lists all files within a Dataverse dataset using a Python one-liner that initializes an fsspec filesystem for the 'dataverse' protocol.

```python
# List the files in a dataset
python -c "import pyDataverse, fsspec; \nfs = fsspec.filesystem('dataverse', base_url='https://demo.dataverse.org', \nidentifier='doi:10.5072/FK2/ABCDEF'); \nprint('\n'.join(fs.ls('/', detail=False)))"
```

--------------------------------

### Perform a Basic Search and Access Results

Source: https://gdcc.github.io/pyDataverse/apis/search

Initiates a search for a given query and demonstrates how to access key information from the response, such as total count, results per page, starting index, and iterating through individual items.

```python
from pyDataverse.api import SearchApi


api = SearchApi("https://demo.dataverse.org")
results = api.search("climate change")


# Total number of matching results
print(f"Total results: {results.total_count}")


# Number of results in this response
print(f"Results in page: {results.count_in_response}")


# Starting index
print(f"Starting at: {results.start}")


# Iterate through results
if results.items:
    for item in results.items:
        print(f"\n{item.type.upper()}: {item.name}")
        if item.description:
            print(f"  {item.description}")
        if item.url:
            print(f"  URL: {item.url}")

```

--------------------------------

### json

Source: https://gdcc.github.io/pyDataverse/reference/dataverse/metrics

Get a JSON string representation of all metrics, with optional indentation.

```APIDOC
## Method: json

### Description
JSON string of all metrics.

### Method Signature
```python
json(self, indent: Optional[int] = 4) -> str
```

### Parameters
#### Query Parameters
- **indent** (Optional[int]) - Optional - Number of spaces to use for indentation. Defaults to 4.

### Response
#### Success Response (200)
- **return value** (str) - A JSON string representing all metrics.
```

--------------------------------

### Download File to Path Object

Source: https://gdcc.github.io/pyDataverse/high-level/file

This example shows how to download a file to a location specified using a `Path` object, which is useful for constructing paths programmatically. The download process is streamed to avoid high memory usage.

```python
# Download to a Path object
from pathlib import Path
file.download(Path("downloads") / "results.csv")
```

--------------------------------

### graph

Source: https://gdcc.github.io/pyDataverse/reference/dataverse/dataset

Get the RDF graph of the dataset by exporting metadata in semantic formats.

```APIDOC
## graph

### Description
Get the RDF graph of the dataset by exporting metadata in semantic formats. This method retrieves the dataset’s metadata in one or more semantic formats (such as JSON-LD, RDF/XML, Turtle, etc.) and converts them into an RDF graph using rdflib. The method validates that the requested formats are available and support semantic data representation.

### Method
Not specified (assumed to be a method of a Dataset object)

### Endpoint
Not specified

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **format** (GraphFormat) - Required - A single format string or list of format strings specifying the semantic export formats to use. Valid formats are those available in the Dataverse instance that have semantic media types.

### Request Example
```python
# Get graph using a single format
graph = dataset.graph("OAI_ORE")

# Get graph using multiple formats
graph = dataset.graph(["OAI_ORE", "JSON-LD"])

# Query the resulting graph
for subj, pred, obj in graph:
    print(f"{subj} {pred} {obj}")
```

### Response
#### Success Response (200)
- **graph** (Graph) - An rdflib Graph object containing the merged RDF triples from all requested export formats.

#### Response Example
```python
# Example of an rdflib Graph object (actual representation may vary)
# print(graph)
```

### Raises
- **ValueError** - If any of the requested formats are not available in the Dataverse instance or do not support semantic data representation.
```

--------------------------------

### Getting Dataverse Roles

Source: https://gdcc.github.io/pyDataverse/apis/native

Retrieve the available roles on a collection using `get_dataverse_roles`.

```APIDOC
## GET /api/v1/roles

### Description
Retrieves a list of all available roles that can be assigned within Dataverse.

### Method
GET

### Endpoint
/api/v1/roles

### Response
#### Success Response (200)
- **roles** (array) - A list of available roles.

### Response Example
{
  "example": "{\"roles\": [...]}"
}
```

--------------------------------

### datasets_by_data_location

Source: https://gdcc.github.io/pyDataverse/reference/dataverse/metrics

Get the number of datasets based on their storage location (local, remote, or all).

```APIDOC
## Method: datasets_by_data_location

### Description
Number of datasets by storage location (local, remote, or all).

### Method Signature
```python
datasets_by_data_location(self, data_location: DataLocation) -> int
```

### Parameters
#### Path Parameters
- None

#### Query Parameters
- **data_location** (DataLocation) - Required - One of ‘local’, ‘remote’, or ‘all’.

### Request Example
```python
dv.metrics.datasets_by_data_location("local")
```

### Response
#### Success Response (200)
- **return value** (int) - Dataset count for the location.
```

--------------------------------

### Get Private URL Info

Source: https://gdcc.github.io/pyDataverse/apis/native

Retrieves information about an existing private URL for a dataset.

```APIDOC
## get_dataset_private_url

### Description
Retrieves information about an existing private URL for a dataset.

### Method
`get_dataset_private_url(identifier)`

### Parameters
#### Path Parameters
- **identifier** (string) - Required - The dataset identifier (e.g., DOI).

### Request Example
```python
from pyDataverse.api import NativeApi

api = NativeApi(
    base_url="https://dataverse.example.edu",
    api_token="your-api-token-here",
)

pid = "doi:10.5072/FK2/ABC123"
info = api.get_dataset_private_url(pid)
```

### Response
#### Success Response (200)
- **dict** - An object containing private URL information.
```

--------------------------------

### Create a New Dataset

Source: https://gdcc.github.io/pyDataverse/high-level/dataverse

Connect to a Dataverse installation and create a new dataset with basic metadata. This snippet demonstrates how to provide title, description, authors, contacts, subjects, and specify a collection. The dataset is configured with all available metadata blocks automatically.

```python
from pyDataverse import Dataverse


# First, connect to your Dataverse installation
dv = Dataverse("https://demo.dataverse.org")


# Create a new dataset with basic information
dataset = dv.create_dataset(
    title="My Research Dataset",
    description="A comprehensive dataset containing experimental results from our study on machine learning algorithms",
    authors=[
        {
            "name": "Jane Smith",
            "affiliation": "University of Science",
            "identifier_scheme": "ORCID",  # Optional: identifies the author using ORCID
            "identifier": "0000-0000-0000-0000"  # Optional: the actual ORCID number
        }
    ],
    contacts=[
        {
            
```

```python
"name": "Jane Smith",
            "email": "jane.smith@university.edu",
            "affiliation": "University of Science"  # Optional: where they work
        }
    ],
    subjects=["Computer and Information Science", "Engineering"]  # Categories for the dataset
    collection="my-collection"
)


# The dataset is now ready to use with all metadata blocks configured
# You can access the citation metadata block like this:
print(dataset.metadata_blocks["citation"].title)
# Output: 'My Research Dataset'
```

--------------------------------

### Getting Collection Facets

Source: https://gdcc.github.io/pyDataverse/apis/native

Retrieve configured search facets for a collection using `get_collection_facets`.

```APIDOC
## GET /api/v1/dataverses/:identifier/facets

### Description
Retrieves the configured search facets for a specific collection.

### Method
GET

### Endpoint
/api/v1/dataverses/:identifier/facets

### Parameters
#### Path Parameters
- **:identifier** (string) - Required - The alias or ID of the collection for which to retrieve facets.

### Response
#### Success Response (200)
- **facets** (array) - A list of configured search facets for the collection.

### Response Example
{
  "example": "{\"facets\": [...]}"
}
```

--------------------------------

### Initialize MetricsApi

Source: https://gdcc.github.io/pyDataverse/apis/metrics

Create an instance of MetricsApi to interact with Dataverse's Metrics API. Public access is common, but authenticated access can be configured using an API token if required by your Dataverse installation.

```python
from pyDataverse.api import MetricsApi


# Public access (most metrics are publicly available)
api = MetricsApi(base_url="https://demo.dataverse.org")


# Authenticated access (if required by your installation)
api = MetricsApi(
    base_url="https://dataverse.example.edu",
    api_token="your-api-token-here",
)
```

--------------------------------

### show_role

Source: https://gdcc.github.io/pyDataverse/reference/api/native

Retrieves details of a specific role by its ID. This is a GET request to the /api/roles/{id} endpoint.

```APIDOC
## GET /api/roles/{id}

### Description
Show role.

### Method
GET

### Endpoint
/api/roles/{id}

### Parameters
#### Path Parameters
- **id** (int) - Required - Can be alias or id of a Role.

### Response
#### Success Response (200)
- **collection.Role**| Response object of httpx library.
```

--------------------------------

### Accessing and Iterating Through Dataset Files

Source: https://gdcc.github.io/pyDataverse/high-level/file

Demonstrates how to fetch a dataset and then access its files. Files can be accessed by their path or iterated over to print their path and size. Also shows how to access individual file properties like identifier, path, and the parent dataset's title.

```python
from pyDataverse import Dataverse


dv = Dataverse("https://demo.dataverse.org")
dataset = dv.fetch_dataset("doi:10.5072/FK2/ABC123")


# Access a file by path
file = dataset.files["data/results.csv"]


# Iterate over all files
for file in dataset.files:
    print(f"{file.path}: {file.metadata.data_file.filesize} bytes")


# Access file properties
print(file.identifier)  # Integer ID
print(file.path)  # Path within dataset
print(file.dataset.title)  # Parent dataset title
```

--------------------------------

### Get All Dataset Versions

Source: https://gdcc.github.io/pyDataverse/reference/api/native

Retrieve a list of all published versions for a given dataset, including their metadata.

```python
get_dataset_versions(self, identifier: Union[str, int]) -> List[dataset.GetDatasetResponse]
```

--------------------------------

### Initialize SearchApi

Source: https://gdcc.github.io/pyDataverse/reference/api/search

Instantiate the SearchApi class to interact with Dataverse's search functionality. This requires an existing native_api object.

```python
search_api = SearchApi.from_api(native_api)
```

--------------------------------

### List and Fetch Dataverse Licenses

Source: https://gdcc.github.io/pyDataverse/apis/native

Use NativeApi to list all available licenses and fetch a specific license by its identifier. This is useful for tools that need to present license choices or interpret license information programmatically.

```python
from pyDataverse.api import NativeApi


api = NativeApi("https://demo.dataverse.org")


# List all available licenses
licenses = api.get_available_licenses()
for license in licenses:
    print(f"{license.name}: {license.uri}")


# Fetch a single license by numeric ID or identifier string
cc_by = api.get_license("CC BY")
print(cc_by.name, cc_by.uri)
```

--------------------------------

### Getting Collection Role Assignments

Source: https://gdcc.github.io/pyDataverse/apis/native

Inspect roles and permissions assigned to a collection using `get_collection_assignments`.

```APIDOC
## GET /api/v1/dataverses/:identifier/assignments

### Description
Retrieves the role assignments for a specific collection, detailing permissions.

### Method
GET

### Endpoint
/api/v1/dataverses/:identifier/assignments

### Parameters
#### Path Parameters
- **:identifier** (string) - Required - The alias or ID of the collection for which to retrieve role assignments.

### Response
#### Success Response (200)
- **assignments** (array) - A list of role assignments for the collection.

### Response Example
{
  "example": "{\"assignments\": [...]}"
}
```

--------------------------------

### Create Dataset with Metadata

Source: https://gdcc.github.io/pyDataverse/reference/dataverse/dataverse

Use this method to initialize a new Dataset instance with core metadata fields and all available metadata blocks. Metadata blocks are dynamically constructed from API-provided specifications at runtime. Ensure Author, Contact, and Subject objects are properly instantiated.

```python
dv = Dataverse(“https://demo.dataverse.org”) 
ds = dv.create_dataset( 
    title=“Neural Network Results”,
    description=“Results and code for the paper.”,
    authors=[Author(name=“Jane Smith”, affiliation=“UniX”)],
    contacts=[Contact(email=“jane.smith@unix.edu”)],
    subjects=[“Computer Science”]
    )
ds.metadata_blocks[“citation”].title 
‘Neural Network Results’
```

--------------------------------

### Get Historical Counts

Source: https://gdcc.github.io/pyDataverse/apis/metrics

Retrieve the total count for a specific data type up to a specified month.

```APIDOC
## Get Historical Counts

### Description
Retrieve the total count for a specific data type up to a specified month.

### Method
GET (implied by SDK usage)

### Endpoint
`/api/v1/metrics/total/{dataType}` (inferred from SDK)

### Parameters
#### Path Parameters
- **dataType** (string) - Required - The type of data to count (e.g., "datasets").

#### Query Parameters
- **date_to_month** (string or date object) - Required - The cutoff date (YYYY-MM format for string, or a `datetime.date` object) up to which counts should be retrieved.

### Request Example
```python
from pyDataverse.api import MetricsApi
from datetime import date

api = MetricsApi("https://demo.dataverse.org")

# Using string format
datasets_str = api.total("datasets", date_to_month="2023-12")

# Using date object
cutoff_date = date(2023, 6, 1)
datasets_date = api.total("datasets", date_to_month=cutoff_date)
```

### Response
#### Success Response (200)
- **count** (integer) - The total count for the specified data type up to the given month.

#### Response Example
```json
{
  "count": 1000
}
```
```

--------------------------------

### Get Base URL for Metrics API

Source: https://gdcc.github.io/pyDataverse/reference/api/metrics

Retrieves the base URL for all metrics API endpoints.

```python
api_base_url(self)
```

--------------------------------

### Geographic Search

Source: https://gdcc.github.io/pyDataverse/apis/search

Perform searches based on geographic location, such as within a specified radius, if supported by the installation.

```APIDOC
## Geographic Search

### Description
Conduct searches based on geographic criteria, such as proximity to a point or within a radius, provided the Dataverse installation supports it.

### Method
`SearchApi.search(query, options)`

### Parameters
#### Query Options
- **geo_radius** (string) - Optional - Specifies a geographic radius for the search (e.g., "10km").
- **geo_point** (string) - Typically set via `filter_query` - The geographic point for radius searches.

### Request Example
```python
from pyDataverse.api import SearchApi
from pyDataverse.api.search import QueryOptions

api = SearchApi("https://demo.dataverse.org")

# Search within a geographic radius
options = QueryOptions(
    geo_radius="10km",
    # Note: geo_point would typically be set via filter_query
)
results = api.search("climate", options)
```
```

--------------------------------

### Initialize SearchApi for Authenticated Access

Source: https://gdcc.github.io/pyDataverse/apis/search

Create an instance of SearchApi for authenticated access to search restricted content. An API token is required.

```python
from pyDataverse.api import SearchApi


# Authenticated access (searches include restricted content)
api = SearchApi(
    base_url="https://dataverse.example.edu",
    api_token="your-api-token-here",
)
```

--------------------------------

### get_user_api_token_expiration_date

Source: https://gdcc.github.io/pyDataverse/reference/api/native

Retrieves the expiration date of a user's API token. This is a GET request to the /api/users/token endpoint.

```APIDOC
## GET /api/users/token

### Description
Get the expiration date of a user's API token.

### Method
GET

### Endpoint
/api/users/token

### Response
#### Success Response (200)
- **message.Message**| Response object of httpx library.
```

--------------------------------

### Initialize DataverseFS via fsspec Registry

Source: https://gdcc.github.io/pyDataverse/filesystem/connecting

Use fsspec's generic filesystem factory to create a DataverseFS instance by registering the 'dataverse' protocol.

```python
import fsspec


fs = fsspec.filesystem(
    "dataverse",
    base_url="https://demo.dataverse.org",
    identifier="doi:10.5072/FK2/ABCDEF",
    api_token="your-token",
)
```

--------------------------------

### Iterate and Print Available Licenses

Source: https://gdcc.github.io/pyDataverse/high-level/dataverse

Loop through the list of available licenses and print their names and URIs. This helps in understanding the specific details of each license option.

```python
# Iterate through them to see what's available
for license in licenses:
    print(f"{license.name}: {license.uri}")
```

--------------------------------

### Create and Upload Dataset Immediately

Source: https://gdcc.github.io/pyDataverse/high-level/collection

Use this method to create a new dataset and upload it to the collection in one step. The dataset will be assigned an identifier upon creation.

```python
# Create a dataset in the collection
dataset = collection.create_dataset(
    title="My Research Dataset",
    description="A dataset containing experimental results",
    authors=[{"name": "Jane Smith", "affiliation": "University"}],
    contacts=[{"name": "Jane Smith", "email": "jane@university.edu"}],
    subjects=["Computer and Information Science"],
    upload_to_collection=True  # Upload immediately (default)
)

```

--------------------------------

### Server Information

Source: https://gdcc.github.io/pyDataverse/apis/native

Retrieve information about the Dataverse installation, including version, server details, and API terms of use.

```APIDOC
## Server Information

### Description
Retrieve essential information about the Dataverse installation, including its version, server hostname, and the API terms of use.

### Method
`NativeApi.get_info_version()`
`NativeApi.get_info_server()`
`NativeApi.get_info_api_terms_of_use()`

### Parameters
None of these methods require parameters.

### Response
- **`get_info_version`**: Returns an object with `version` and `build` attributes.
- **`get_info_server`**: Returns an object with a `hostname` attribute.
- **`get_info_api_terms_of_use`**: Returns an object with a `message` attribute.

### Request Example
```python
from pyDataverse.api import NativeApi

api = NativeApi("https://demo.dataverse.org")

version = api.get_info_version()
print(version.version, version.build)

server = api.get_info_server()
print(server.hostname)

terms = api.get_info_api_terms_of_use()
print(terms.message)
```
```

--------------------------------

### Get Available Licenses

Source: https://gdcc.github.io/pyDataverse/reference/api/native

Retrieve a list of all available licenses within the Dataverse system. This function does not require any parameters.

```python
get_available_licenses(self) -> List[info.License]
```

--------------------------------

### get_dataverse_roles

Source: https://gdcc.github.io/pyDataverse/reference/api/native

Retrieves all roles defined directly in a dataverse by its identifier. This is a GET request to the /api/dataverses/{identifier}/roles endpoint.

```APIDOC
## GET /api/dataverses/{identifier}/roles

### Description
Get all the roles defined directly in the dataverse by identifier.

### Method
GET

### Endpoint
/api/dataverses/{identifier}/roles

### Parameters
#### Path Parameters
- **identifier** (str) - Required - Can either be a dataverse id (long), a dataverse alias (more robust), or the special value :root.

### Response
#### Success Response (200)
- **List[collection.Role]**| Response object of httpx library.
```

--------------------------------

### Direct Initialization of DataverseFS

Source: https://gdcc.github.io/pyDataverse/filesystem/connecting

Initialize DataverseFS by explicitly providing the base URL, dataset identifier, and an optional API token.

```python
from pyDataverse.filesystem import DataverseFS


fs = DataverseFS(
    base_url="https://demo.dataverse.org",
    identifier="doi:10.5072/FK2/ABCDEF",
    api_token="your-token",  # optional; required for writes & restricted files
)
```

--------------------------------

### Get API Terms of Use

Source: https://gdcc.github.io/pyDataverse/reference/api/native

Retrieve the URL for the API Terms of Use. This information is configured at the database level.

```python
get_info_api_terms_of_use(self) -> info.TermsOfUseResponse
```

--------------------------------

### Initialize SemanticApi for Authenticated Access

Source: https://gdcc.github.io/pyDataverse/apis/semantic

Create a SemanticApi instance for authenticated access to private datasets by providing the base URL and an API token.

```python
from pydataverse.api import SemanticApi


# Authenticated access for private datasets
api = SemanticApi(
    base_url="https://dataverse.example.edu",
    api_token="your-api-token-here",
)
```

--------------------------------

### Get Dataset Assignments

Source: https://gdcc.github.io/pyDataverse/reference/api/native

Retrieve all role assignments for a specific dataset. Use this to check user permissions on a dataset.

```python
get_dataset_assignments(self, identifier: Union[str, int]) -> List[dataset.DatasetAssignment]
```

--------------------------------

### Using MetricsResponse Objects

Source: https://gdcc.github.io/pyDataverse/apis/metrics

Demonstrates how to use MetricsResponse objects returned by methods like `total`, `past_days`, and `get_datasets_by_data_location`. Shows how to access the count and use it in calculations.

```python
from pyDataverse.api import MetricsApi


api = MetricsApi("https://demo.dataverse.org")


# Get a metrics response
result = api.total("datasets")
print(f"Count: {result.count}")


# Use in calculations
collections = api.total("dataverses")
datasets = api.total("datasets")
avg_datasets_per_collection = datasets.count / collections.count
print(f"Average datasets per collection: {avg_datasets_per_collection:.2f}")
```

--------------------------------

### Get Dataset Metadata

Source: https://gdcc.github.io/pyDataverse/reference/api/native

Retrieve complete metadata for a specific dataset version. Defaults to the latest version if not specified.

```python
get_dataset(self, identifier: Union[str, int], version: Optional[Union[Literal[':latest', ':latest-published', ':draft'], str]] = ':latest') -> dataset.GetDatasetResponse
```