Metadata-Version: 2.2
Name: rorclient
Version: 0.1.0
Summary: A Python client for interacting with the ROR API
Author-email: Alexander Dernild <alex@dernild.dk>
Project-URL: Homepage, https://github.com/ADernild/RORClient
Project-URL: Bug Tracker, https://github.com/ADernild/RORClient/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1.0,>=0.28.1
Requires-Dist: pydantic<3.0,>=2.10.6
Requires-Dist: backoff<3.0,>=2.2.1
Provides-Extra: dev
Requires-Dist: ruff<1.0,>=0.1.14; extra == "dev"
Requires-Dist: pytest>=8.3.4; extra == "dev"
Requires-Dist: pytest-mock>=3.14.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.25.3; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx<9.0,>=8.2.1; extra == "docs"
Requires-Dist: sphinx-autobuild==2024.10.3; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=3.1.0; extra == "docs"
Requires-Dist: sphinx-book-theme>=1.1.4; extra == "docs"

# RORClient


[![Become a sponsor to ADernild](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&color=%23fe8e86)](https://github.com/sponsors/ADernild "Become a sponsor to ADernild")
[![GitHub](https://img.shields.io/github/followers/adernild?label=follow&style=social)](https://github.com/ADernild "Follow ADernild on GitHub")
[![LinkedIn](https://img.shields.io/badge/-LinkedInd-blue?style=flat-round&logo=Linkedin&logoColor=white&link=https://linkedin.com/in/alexander-dernild)](https://linkedin.com/in/alexander-dernild "Connect with me on LinkedIn")
[![Akami Cloud Computing](https://img.shields.io/badge/Cloud_Hosting-s?style=flat-round&logo=akamai&logoColor=%230096D6&labelColor=white&color=white)](https://www.linode.com/lp/refer/?r=a1236b8e74912ccb090628165fa6bf21cb52968f "Get a $100 credit on Linode Cloud")
[![Pydantic v2](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v2.json)](https://pydantic.dev)
[![httpx](https://img.shields.io/badge/httpx-%5E0.28.1-orange)](https://www.python-httpx.org/)
[![Python versions](https://img.shields.io/pypi/pyversions/httpx)](https://www.python.org/downloads/)

🚀 **A Python client for interacting with the ROR API.**
RORClient provides a simple, efficient way to query the [Research Organization Registry (ROR)](https://ror.org) API using **HTTPX** and **Pydantic**.

---

## 📖 Table of Contents
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Synchronous Client](#synchronous-client)
- [Asynchronous Client](#asynchronous-client)
- [Models](#models)
- [Testing](#testing)
- [Contributing](#contributing)
- [License](#license)

---

## ⚡ Installation
> ⚠ **Work in Progress**: RORClient is not yet available via PyPI.
> Clone the repository and install dependencies manually:

```sh
git clone https://github.com/ADernild/rorclient.git
cd rorclient
uv sync
```
---

## 🚀 Quick Start

### Synchronous Client
```python
from rorclient import RORClient

with RORClient() as client:
    # Get institution details
    org = client.get_institution("03yrm5c26")
    if org:
        print(f"Found institution: {org.name}")

    # Fetch multiple institutions
    multiple_orgs = client.get_multiple_institutions(["03yrm5c26", "029z82x56"])
    print(f"Fetched {len(multiple_orgs)} institutions")

```

### Asynchronous Client
```python
import asyncio
from rorclient import AsyncRORClient

async def main():
    async with AsyncRORClient() as client:
        # Get institution details
        org = await client.get_institution("03yrm5c26")
        if org:
            print(f"Found institution: {org.name}")

        # Fetch multiple institutions
        multiple_orgs = await client.get_multiple_institutions(["03yrm5c26", "029z82x56"])
        print(f"Fetched {len(multiple_orgs)} institutions")

asyncio.run(main())

```

---

## 🏛 Models
RORClient uses **Pydantic** models to structure API responses. The main model is `Institution`, which represents an organization in ROR.

Example usage:

```python
from rorclient import RORClient

client = RORClient()
org = client.get_institution("03yrm5c26")

if org:
    print(org.name)  # Stanford University
    print(org.external_ids)  # External identifiers like GRID, ISNI
    print(org.location.country)  # Country of the institution
```

For a full list of available fields, see the [institution.py](rorclient/models/institution.py) file.
You can also have a look at the [ROR API documentation](https://ror.readme.io/v2/docs/data-structure)

---

## 🧪 Testing

To run the test suite, run:

```sh
uv run pytest
```

---

## 🤝 Contributing

Contributions are welcome! Please open an issue or submit a pull request.

---

## 📜 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
