torngen

TorngenPythonClient

TorngenPythonClient is an autogenerated Python library containing the paths and schemas required to make requests against the Torn API v2 and parse the responses.

Installation

This library is intended to be installed from GitHub to allow developers to update the generated OpenAPI-related code regardless of the maintenance of projects depending upon this library.

For example, this can be done using pip:

pip3 install git+https://github.com/Tornium/torngen_python_client.git

Basic Usage

  1. Create an implementation of the HTTPAdapater to perform API calls and any custom API-related behavior.
  2. Perform the query:
    • Select a resource from the path documentation.
    • Determine the selections to use.
    • Determine the parameters to use for those selections.

Example:

from torngen.path import User

response = (
    User()
    .key("{{ API KEY }}")
    .select(User.attacks, User.bounties)
    .limit(10)
    .get(adapter=CustomHTTPClient)
    .parse()
)
  1. Access query response: After being parsed, each selection's parsed response can be selected by accessing the response dictionary by the selection name.

Example:

for attack in response.attacks:
    print(f"{attack.defender.name} was attacked")

Consult the documentation (and the path documentation) for information on available endpoints and parameters. For detailed API usage and available endpoints, refer to the Torn API Swagger documentation and the generated source code in this repository.

License

Copyright 2025 tiksan

This project is licensed under Apache 2.0; see LICENSE.md for more details.

Troubleshooting & Contributing

  • If you encounter issues, please ensure you have the latest version of the library.
  • Contributions are welcome! Open a pull request or submit an issue on GitHub if you have suggestions or bug reports.
  • If you have any questions, please use the Tornium Discord server.
class BaseQuery:

Base Torn APIv2 query object for a resource.

The generated client is based on a fluent interface where a query is built from a resource, at least one resource selection, and query/path parameters. After the query has been built, the query can be run against an HTTPAdapter implementation and parsed against the selected resource and selection(s).

BaseQuery(base_path: str)
base_path: str
selections: Set[base_path.Path]
parameters: Dict[str, str | int]
api_key: Optional[str]
response: Optional[dict]
def select(self, *args: Tuple[base_path.Path]) -> Self:

Select at least one path belonging to the query's resource.

def key(self, api_key: str) -> Self:

Add an API key to the query.

def get( self, adapter: Type[adapter.HTTPAdapter], new_headers: Dict[str, str] = {}) -> Self:

Perform the Torn APIv2 request.

This function performs a Torn APIv2 request for a URL generated against the query and store the response in the query. Once the query has been performed, the API response can be parsed with parse() or accessed directly with .response.

def url(self, domain: str = 'api.torn.com') -> str:

Generate a URL for the query.

Create a URL necessary for a Torn APIv2 call for the query. If a domain is provided, the domain will be used when creating the URL; otherwise, api.torn.com will be used.

def parse(self) -> torngen.base_query.ParsedResponse:

Parse an API response against the resource and resource selections.

class BaseSchema(abc.ABC):

Base representation of an Torn APIv2 response schema.

This base class will be used to parse API responses by the type hints and dataclasses used for the schema.

@staticmethod
def parse(data: Any, type_hints: Type[Any]) -> Any:
class HTTPAdapter(abc.ABC):

HTTP adapter to perform Torn API requests.

torngen_python_client is a bring-your-own-networking (BYON) library. To avoid restricting the client to a specific HTTP library, ratelimiting implementation, etc. which requires usage of this client to include an implementation of this HTTP adapter.

An implementation of the HTTP adapter will need to implement the following three functions. An example implementation of the HTTPAdapter can be found in tests/conftest.py.

@staticmethod
@abstractstaticmethod
def get(url: str, headers: dict = {}) -> Any:

HTTP GET request handler.

The implementation of this function will make HTTP GET requests against the specified URL with the provided headers. Any request handling functionality can be performed by the function such as ratelimiting.

@staticmethod
@abstractstaticmethod
def version() -> str:

Version of the HTTP library.

The implementation of this function will return a string identifying the version of the HTTP library utilized in the implementation of the HTTP adapter.

Example: 2.32.4

@staticmethod
@abstractstaticmethod
def client_name() -> str:

Name of the HTTP library.

The implementation of this function will return a string identifying the name of the HTTP library utilized in the implementation of the HTTP adapter.

class Path:

Torn APIv2 resource and selection representation.

This represents a selection for a resource in the Torn APIv2 OpenAPI specification. The representation indicates the relationship between a selection, the response schema, and the path/query parameters that can be used in an API call against the resource and selection.

Path( path_uri: str, response_schema: base_schema.BaseSchema, **parameters: Dict[str, parameter.Parameter])
selection: str

Torn API selection against a resource.

response_schema: base_schema.BaseSchema

Schema representing the API's response.

The response schema will be used to parse the Torn API's response for all selections utilized in the API call.

parameters: Dict[str, parameter.Parameter]

Parameters applicable for resource and selection.