# PyOpenAlex

> A Pydantic-powered Python client for the OpenAlex API. Provides typed access to 270M+ scholarly works, 90M+ authors, and 100K+ sources with a chainable query builder, filter expressions, markdown rendering, and automatic cursor pagination.

PyOpenAlex wraps the OpenAlex API (https://api.openalex.org) with Pydantic models for all entity types. The design follows FastAPI and Pydantic patterns: immutable query builders, typed models, filter expressions as descriptor functions, and environment-based configuration via pydantic-settings.

Install with `pip install pyopenalex`. Requires Python 3.10+.

```python
from pyopenalex import OpenAlex, gt

with OpenAlex(api_key="...") as client:
    for work in client.works.filter(cited_by_count=gt(1000), publication_year=2024).limit(10):
        print(work.to_markdown(limit_abstract=150))
```

## Core

- [README](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/README.md): Full usage guide with examples for all features
- [PyPI](https://pypi.org/project/pyopenalex/): Package page

## Client and Configuration

- [client.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyopenalex/client.py): OpenAlex client class with endpoint registry, special methods (rate_limit, changefiles, download_pdf), and context manager support
- [config.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyopenalex/config.py): Settings via pydantic-settings, configurable through OPENALEX_ env vars
- [_http.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyopenalex/_http.py): HTTP client with tenacity retry and exponential backoff

## Query Building

- [query.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyopenalex/query.py): Immutable QueryBuilder with .get(n), .get(all=True), filter, search, sort, limit, and cursor iteration
- [expressions.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyopenalex/expressions.py): Filter expressions: gt(), lt(), ne(), or_(), between()
- [endpoints.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyopenalex/endpoints.py): Typed Endpoint[T] with get, batch get, random, autocomplete, by_author/by_institution/by_source/by_topic/by_funder, and delegation to QueryBuilder

## Entity Models and Rendering

- [models/base.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyopenalex/models/base.py): Base model with to_markdown(), Meta, dehydrated entities, shared types
- [models/works.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyopenalex/models/works.py): Work with aliases (.year, .citations, .authors, .abstract)
- [models/authors.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyopenalex/models/authors.py): Author model
- [models/sources.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyopenalex/models/sources.py): Source model
- [models/institutions.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyopenalex/models/institutions.py): Institution model
- [models/topics.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyopenalex/models/topics.py): Topic model
- [models/keywords.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyopenalex/models/keywords.py): Keyword model
- [models/publishers.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyopenalex/models/publishers.py): Publisher model
- [models/funders.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyopenalex/models/funders.py): Funder model
- [models/domains.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyopenalex/models/domains.py): Domain model (top-level topic category)
- [models/fields.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyopenalex/models/fields.py): Field model (second-level topic category)
- [models/subfields.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyopenalex/models/subfields.py): Subfield model (third-level topic category)
- [models/sdgs.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyopenalex/models/sdgs.py): Sdg model (UN Sustainable Development Goals)
- [models/countries.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyopenalex/models/countries.py): Country model
- [models/continents.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyopenalex/models/continents.py): Continent model
- [models/languages.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyopenalex/models/languages.py): Language model
- [models/work_types.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyopenalex/models/work_types.py): WorkType model
- [models/source_types.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyopenalex/models/source_types.py): SourceType model
- [models/institution_types.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyopenalex/models/institution_types.py): InstitutionType model
- [models/licenses.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyopenalex/models/licenses.py): License model
- [models/awards.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyopenalex/models/awards.py): Award model (research grants)
- [models/special.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyopenalex/models/special.py): RateLimit, ChangefileDate, ChangefileEntry models
- [markdown.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyopenalex/markdown.py): Markdown renderers for all entity types with limit_abstract support

## Optional

- [exceptions.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyopenalex/exceptions.py): OpenAlexError, AuthenticationError, NotFoundError, RateLimitError, APIError
- [models/autocomplete.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyopenalex/models/autocomplete.py): AutocompleteResult model
- [examples/quickstart.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/examples/quickstart.py): Runnable example showcasing core features
- [examples/new_endpoints.py](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/examples/new_endpoints.py): Smoke test for topic hierarchy, geographic, and special endpoints
- [pyproject.toml](https://raw.githubusercontent.com/nthomsencph/pyopenalex/main/pyproject.toml): Package metadata and dependencies
