Http Objects - Tools to make python interfaces to http services.
Technically speaking, this is lightweight Python library for turning URL templates and OpenAPI specifications into usable Python functions.
Informally speaking, this package gives you tools to make task-specific python objects that talk to the internet.
To install: pip install ho
The most common scenario: You have a URL template with placeholders and want to quickly create a Python function to make API calls:
fromhoimportroute_to_func# Create a function from a URL templatesearch_google=route_to_func("https://www.google.com/search?q={search_term}")
# Use the function as if it were hand-writtenresults=search_google("python openapi")
results[:40] +'...'+results[-20:]'<!doctype html><html itemscope="" itemty... </body></html>'
That's it! The library handles parameter extraction, HTTP requests, and response processing automatically.
Well. Not really "that's it". Of course, there's many more control parameters to extend this further. Let's have a look at a few.
This is what happened under the hood, when you do just a func = route_to_func(url_template).
- Parses your URL template
- Generates an OpenAPI Specification (formerly known as Swagger)
- Creates a Python function with the correct signature based on this specification
- Sets up all the necessary HTTP request handling
Of course, there's a much more direct route from a url template to a function. You can specify pretty much any aspect of a webservice API, using the OpenAPI Specification. We chose to go via the OpenAPI specification because it enables us to quickly connect to a huge ecosystem of other tools you'll then be able to use.
The OpenAPI Specification is an industry standard for describing HTTP APIs in a language-agnostic way. Today, most significant APIs publish such specifications, enabling automatic code generation in various programming languages.
While traditional approaches often use static code generation, this library provides a dynamic runtime solution to create Python interfaces to HTTP services using OpenAPI specifications.
Now, it's not always what you want. Once your API is stable, static code is usually a better idea. But in many cases, you don't want to have to generate static code, put it in your python path, import it, and all that jazz.
This is when ho is the tool you want.
# URL with path and query parameters including defaultsget_country=route_to_func(
"https://restcountries.com/v3.1/name/{country_name}?fullText={full_text:false}",
description="Get country information by name",
param_types={"country_name": "string", "full_text": "boolean"}
)
# Call with required parameters, using defaults for the restcountries=get_country(country_name="germany")
# Or override the defaultsexact_match=get_country(country_name="germany", full_text=True)This is to demo cases where the API needs authentication.
The example will work only if you have a GitHub token that you placed in an environmental variable called GITHUB_TOKEN.
(If you don't have one, go get one, it's free! We like free!)
# API requiring authenticationimportosgithub_api=route_to_func(
"https://api.github.com/repos/{owner}/{repo}/issues",
description="List issues for a repository",
custom_headers={
"Authorization": os.environ.get("GITHUB_TOKEN"),
"Accept": "application/vnd.github.v3+json"
}
)Let's play with that:
issues=github_api(owner="openai", repo="openai-python")
first_issue=issues[0] ifissueselseNoneiffirst_issue:
print(f"Issue fields: {list(first_issue)}")
print(f"First issue title: {issues[0]['title']}")Issue fields: ['url', 'repository_url', 'labels_url', 'comments_url', 'events_url', 'html_url', 'id', 'node_id', 'number', 'title', 'user', 'labels', 'state', 'locked', 'assignee', 'assignees', 'milestone', 'comments', 'created_at', 'updated_at', 'closed_at', 'author_association', 'type', 'active_lock_reason', 'draft', 'pull_request', 'body', 'closed_by', 'reactions', 'timeline_url', 'performed_via_github_app', 'state_reason']
First issue title: feat(api): return better error message on missing embedding
The rest of these examples are not runnable, but just illustrative of the functionalities of ho.
# Creating resources with POSTcreate_item=route_to_func(
"https://api.example.com/items",
method="post",
description="Create a new item",
param_types={"name": "string", "price": "number"}
)
new_item=create_item(name="New Product", price=19.99)If you have an existing OpenAPI specification file:
importyamlfromhoimportroutes_to_funcs# Load the OpenAPI specwithopen('api_spec.yaml', 'r') asf:
spec=yaml.safe_load(f)
# Create functions for all endpointsapi_client=routes_to_funcs(spec, "https://api.example.com")
# Use the functionsusers=api_client['get', '/users']()
user=api_client['get', '/users/{id}'](id=123)Or convert them to a namespace for even easier access:
fromhoimportroutes_to_namespace# Create a namespace with all API functionsapi=routes_to_namespace(spec, "https://api.example.com")
# Access functions by their generated namesusers=api.get_users()
user=api.get_users_id_(id=123)defprocess_xml_response(response):
importxml.etree.ElementTreeasETroot=ET.fromstring(response.text)
# Process the XMLreturn {"processed": True, "data": root}
xml_api=route_to_func(
"https://api.example.com/xml/{resource}",
egress=process_xml_response
)defcustom_error_handler(response, exception=None):
ifexception:
print(f"Request failed: {exception}")
return {"error": str(exception)}
ifresponse.status_code>=400:
print(f"API error: {response.status_code}")
return {"error": response.text}
returnresponseapi=route_to_func(
"https://api.example.com/{resource}",
error_handler=custom_error_handler
)- No Code Generation: Unlike traditional OpenAPI tools that generate static code, this library creates functions dynamically at runtime.
- Simplified Interface: Turn complex HTTP API calls into simple Python function calls.
- Type Hints and Documentation: Generated functions include proper signatures and docstrings.
- Flexibility: Works with both simple URL templates and complete OpenAPI specifications.
- Lightweight: No complex dependencies or build processes required.
Most OpenAPI tools like OpenAPI Generator generate static code in multiple languages. This approach requires a build step and often results in large codebases. Our library provides a lightweight alternative with dynamic function creation at runtime, which is perfect for Python's dynamic nature and for rapid prototyping.
pip install hoMIT