Arya’s API Framework

Docs
PyPI
Activity
QA
Other

This module is designed to be a base for the creation of clients that interact with RESTful web APIs.

Features:

• Synchronous branch utilizing requests.

• Asynchronous branch utilizing aiohttp.

• Integrated with pydantic for strict typing.

Disclaimer

This library is not intended for fast, performant code. It is instead optimized for user-friendliness and strict data typing. While this will likely not be a noticeable issue for many users, please keep this in mind.

Installation

To install the sync branch:

pip install arya-api-framework[sync]

To install the async branch:

pip install arya-api-framework[async]

Getting Started

This example is a minimal example. However, it is still much more than most libraries have for a getting started page. This is because of this modules usage of Pydantic for data validation from API responses. If you would like a breakdown of this, please see the Breakdown section, or take a look at the available Guides.

models.py

from arya_api_framework import BaseModel, Response

# Data models
class Geo(BaseModel):
    lat: float
    lng: float

class Address(BaseModel):
    street: str
    suite: str
    city: str
    zipcode: str
    geo: Geo

class Company(BaseModel):
    name: str
    catchPhrase: str
    bs: str

class User(Response):
    id: int
    name: str
    email: str
    address: Address
    phone: str
    website: str
    company: Company

# Query models
class AddressQuery(BaseModel):
    city: Optional[str]

class UserQuery(BaseModel):
    username: Optional[str]
    address: Optional[AddressQuery]

api.py

from arya_api_framework import SyncClient
from pydantic import validate_arguments

from models import User, UserQuery, AddressQuery

class PlaceholderClient(SyncClient, uri="https://jsonplaceholder.typicode.com"):
    def get_users(self):
        # https://jsonplaceholder.typicode.com/users
        return self.get('/users', response_format=User)

    @validate_arguments()
    def get_user_by_id(self, id: int):
        # https://jsonplaceholder.typicode.com/users/<id>
        return self.get(f'/users/{id}', response_format=User)

    @validate_arguments()
    def search_user_by_username(self, name: str):
        # https://jsonplaceholder.typicode.com/users?username=<name>
        query = UserQuery(username=name)

        return self.get('/users', parameters=query, response_format=User)

    @validate_arguments()
    def search_user_by_city(self, city: str):
        # https://jsonplaceholder.typicode.com/users?address.city=<city>
        query = UserQuery(address=AddressQuery(city=city))

        return self.get('/users', parameters=query, response_format=User)

    @validate_arguments()
    def search_user_by_username_and_city(self, name: str, city: str):
        # https://jsonplaceholder.typicode.com/users?username=<name>&address.city=<city>
        query = UserQuery(username=name, address=AddressQuery(city=city))

        return self.get('/users', parameters=query, response_format=User)

main.py

from api import PlaceholderClient

if __name__ == "__main__":
    client = PlaceholderClient()

    users = client.get_users()
    print(users)

    user = client.get_user_by_id(3)
    print(user)

    lookup = client.search_user_by_username("Bret")
    print(lookup)

    lookup = client.search_user_by_city("Gwenborough")
    print(lookup)

    lookup = client.search_user_by_username_and_city("Bret", "Gwenborough")
    print(lookup)

Guides

These guides are intended to be a place where those looking to really take advantage of the features this system has can get started.

• Quickstart
• Logging
• SubClient Guide

API Reference

• API Reference
  • Sync Client
  • Async Client
  • Sub Client
  • Data Models
  • Enums
  • Utility Functions
• Exceptions
  • General Exceptions
  • Extension Exceptions
  • Client Exceptions
  • SubClient Exceptions
  • Request Exceptions
  • Exception Hierarchy

Information

Here lies a bunch of random information related to the project at least a little bit.

• Web Information
  • Terminology
  • HTTP Request Methods
  • HTTP Status Codes
  • Reference

Glossary

If you are struggling to find specific information, see these references:

• Search

• Glossary

TODO Features

• Rate Limits (Allow rate limit application for limited APIs.)
• Response Caching (Reduce processing times/network load.)
• Sub-Clients (For creating API category modules.)