esi-client


Nameesi-client JSON
Version 0.1.0a2 PyPI version JSON
download
home_page
SummaryA Python client for accessing the complete Eve Online ESI API.
upload_time2023-04-29 21:45:08
maintainer
docs_urlNone
author
requires_python>=3.6
licenseMIT License Copyright (c) 2023 Erik Kalkoken Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
keywords eve swagger interface eve online
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # esi-client

A Python client for accessing the complete Eve Online ESI API.

[![release](https://img.shields.io/pypi/v/esi-client?label=release)](https://pypi.org/project/esi-client/)
[![python](https://img.shields.io/pypi/pyversions/esi-client)](https://pypi.org/project/esi-client/)
[![openapi](https://img.shields.io/badge/openapigen-6.6.0_SNAPSHOT-blue)](https://esi.evetech.net/ui/)
[![ESI](https://img.shields.io/badge/ESI-1.17-blue)](https://esi.evetech.net/ui/)
[![pipeline status](https://gitlab.com/ErikKalkoken/esi-client-generator/badges/main/pipeline.svg)](https://gitlab.com/ErikKalkoken/esi-client-generator/-/commits/main)
[![license](https://img.shields.io/badge/license-MIT-green)](https://gitlab.com/ErikKalkoken/esi-client/-/blob/master/LICENSE)
[![chat](https://img.shields.io/discord/790364535294132234)](https://discord.gg/zmh52wnfvM)

## Contents

- [Overview](#overview)
- [Installation](#installation)
- [Usage](#usage)

## Overview

This package is a library that provides a Python client for accessing the public 3rd party API of EVE Online, which is more commonly known as "ESI" (EVE Swagger Interface).

The client is automatically generated from ESI's specification with the [Open API generator](https://openapi-generator.tech/).

This approach offers many benefits in comparison to other ESI libraries:

- Complete and correct coverage of all endpoints
- Automatic serialization and mapping to Python data types
- Python classes for all data models
- Type annotations, i.e. enabling auto complete for API methods
- No delay at startup for building the client
- Robust and proven API client
- Fast turnaround on API updates

## Installation

You can install the current this library directly from PyPI:

```sh
pip install esi-client
```

## Usage

In this chapter we are showing how to get information from ESI with the open API client.

### Accessing public endpoints

The esi client from openAPI is easy to use. Here is a minimal example for fetching a character from the public endpoint:

```python
from esi_client.api.character_api import CharacterApi

api = CharacterApi()
character = api.get_characters_character_id(character_id=93330670)
print(character.name)
```

### Error handling

Common errors can be handled by catching `ApiException`:

```python
import esi_client
from esi_client.api.character_api import CharacterApi

api = CharacterApi()
try:
    character = api.get_characters_character_id(character_id=93330670)
    print(character.name)
except esi_client.ApiException as ex:
    print(f"Exception occurred when trying to fetch a character: {ex}")
```

### Making multiple calls to endpoints

When making multiple calls to endpoints it is more efficient to use the same API client instance. Here we are first calling the character endpoint to get information about a character and then we are calling the corporation endpoint to get the name of the corporation the character belongs to.

```python
import esi_client
from esi_client.api.character_api import CharacterApi
from esi_client.api.corporation_api import CorporationApi

with esi_client.ApiClient() as api_client:
    character_api = CharacterApi(api_client)
    character = character_api.get_characters_character_id(character_id=93330670)
    corporation_api = CorporationApi(api_client)
    corporation = corporation_api.get_corporations_corporation_id(
        corporation_id=character.corporation_id
    )
    print(f"{character.name} if a member of {corporation.name}")

    
```

### Accessing private endpoints

For accessing private endpoint you need a valid access token.

Note that to topic of obtaining an access token is not in scope of this library. Please see the [SSO documentation](https://docs.esi.evetech.net/docs/sso/) for more information on how to obtain an access token for your web site or app. For testing purposes it is possible to generate an access token on the [ESI web site](https://esi.evetech.net/ui/).

You can provide your access token in two ways:

1. As configuration for the api client
2. As parameter when calling an endpoint

#### Token as configuration

One way for providing your access token is as configuration for the api client:

```python
import esi_client
from esi_client.api.character_api import CharacterApi

configuration = esi_client.Configuration(access_token="ACCESS-TOKEN")

with esi_client.ApiClient(configuration) as api_client:
    api_instance = CharacterApi(api_client)
    api_response = api_instance.get_characters_character_id_medals(
        character_id=93330670
    )
    ...
```

#### Token as parameter

Another way of providing your access token is as parameter when making the call to the endpoint:

```python
from esi_client.api.character_api import CharacterApi

api_instance = CharacterApi(api_client)
api_response = api_instance.get_characters_character_id_medals(
    character_id=93330670, token="ACCESS-TOKEN"
)
```

### Getting HTTP information for a response

In some cases you also need to get the HTTP information for a response. e.g. if a endpoint supports paging the information about how many pages there are is in the HTTP header.

To get the HTTP information you need to pass the argument `_return_http_data_only=False` when calling the API method. The API method will then return a tuple consisting of:

- data
- HTTP status code
- HTTP response headers

Here is an example:

```python
from esi_client.api.universe_api import UniverseApi

api = UniverseApi()
data, status_code, header = api.get_universe_types(_return_http_data_only=False)
```

The source code for these examples can also be found in project's `examples` folder.

            

Raw data

            {
    "_id": null,
    "home_page": "",
    "name": "esi-client",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.6",
    "maintainer_email": "Erik Kalkoken <kalkoken87@gmail.com>",
    "keywords": "EVE Swagger Interface,Eve Online",
    "author": "",
    "author_email": "",
    "download_url": "https://files.pythonhosted.org/packages/f7/e8/90a3351b51bda622f1af5f2ae893a2d0f6c6f9caf1adf052c6fe58f2c619/esi_client-0.1.0a2.tar.gz",
    "platform": null,
    "description": "# esi-client\n\nA Python client for accessing the complete Eve Online ESI API.\n\n[![release](https://img.shields.io/pypi/v/esi-client?label=release)](https://pypi.org/project/esi-client/)\n[![python](https://img.shields.io/pypi/pyversions/esi-client)](https://pypi.org/project/esi-client/)\n[![openapi](https://img.shields.io/badge/openapigen-6.6.0_SNAPSHOT-blue)](https://esi.evetech.net/ui/)\n[![ESI](https://img.shields.io/badge/ESI-1.17-blue)](https://esi.evetech.net/ui/)\n[![pipeline status](https://gitlab.com/ErikKalkoken/esi-client-generator/badges/main/pipeline.svg)](https://gitlab.com/ErikKalkoken/esi-client-generator/-/commits/main)\n[![license](https://img.shields.io/badge/license-MIT-green)](https://gitlab.com/ErikKalkoken/esi-client/-/blob/master/LICENSE)\n[![chat](https://img.shields.io/discord/790364535294132234)](https://discord.gg/zmh52wnfvM)\n\n## Contents\n\n- [Overview](#overview)\n- [Installation](#installation)\n- [Usage](#usage)\n\n## Overview\n\nThis package is a library that provides a Python client for accessing the public 3rd party API of EVE Online, which is more commonly known as \"ESI\" (EVE Swagger Interface).\n\nThe client is automatically generated from ESI's specification with the [Open API generator](https://openapi-generator.tech/).\n\nThis approach offers many benefits in comparison to other ESI libraries:\n\n- Complete and correct coverage of all endpoints\n- Automatic serialization and mapping to Python data types\n- Python classes for all data models\n- Type annotations, i.e. enabling auto complete for API methods\n- No delay at startup for building the client\n- Robust and proven API client\n- Fast turnaround on API updates\n\n## Installation\n\nYou can install the current this library directly from PyPI:\n\n```sh\npip install esi-client\n```\n\n## Usage\n\nIn this chapter we are showing how to get information from ESI with the open API client.\n\n### Accessing public endpoints\n\nThe esi client from openAPI is easy to use. Here is a minimal example for fetching a character from the public endpoint:\n\n```python\nfrom esi_client.api.character_api import CharacterApi\n\napi = CharacterApi()\ncharacter = api.get_characters_character_id(character_id=93330670)\nprint(character.name)\n```\n\n### Error handling\n\nCommon errors can be handled by catching `ApiException`:\n\n```python\nimport esi_client\nfrom esi_client.api.character_api import CharacterApi\n\napi = CharacterApi()\ntry:\n    character = api.get_characters_character_id(character_id=93330670)\n    print(character.name)\nexcept esi_client.ApiException as ex:\n    print(f\"Exception occurred when trying to fetch a character: {ex}\")\n```\n\n### Making multiple calls to endpoints\n\nWhen making multiple calls to endpoints it is more efficient to use the same API client instance. Here we are first calling the character endpoint to get information about a character and then we are calling the corporation endpoint to get the name of the corporation the character belongs to.\n\n```python\nimport esi_client\nfrom esi_client.api.character_api import CharacterApi\nfrom esi_client.api.corporation_api import CorporationApi\n\nwith esi_client.ApiClient() as api_client:\n    character_api = CharacterApi(api_client)\n    character = character_api.get_characters_character_id(character_id=93330670)\n    corporation_api = CorporationApi(api_client)\n    corporation = corporation_api.get_corporations_corporation_id(\n        corporation_id=character.corporation_id\n    )\n    print(f\"{character.name} if a member of {corporation.name}\")\n\n    \n```\n\n### Accessing private endpoints\n\nFor accessing private endpoint you need a valid access token.\n\nNote that to topic of obtaining an access token is not in scope of this library. Please see the [SSO documentation](https://docs.esi.evetech.net/docs/sso/) for more information on how to obtain an access token for your web site or app. For testing purposes it is possible to generate an access token on the [ESI web site](https://esi.evetech.net/ui/).\n\nYou can provide your access token in two ways:\n\n1. As configuration for the api client\n2. As parameter when calling an endpoint\n\n#### Token as configuration\n\nOne way for providing your access token is as configuration for the api client:\n\n```python\nimport esi_client\nfrom esi_client.api.character_api import CharacterApi\n\nconfiguration = esi_client.Configuration(access_token=\"ACCESS-TOKEN\")\n\nwith esi_client.ApiClient(configuration) as api_client:\n    api_instance = CharacterApi(api_client)\n    api_response = api_instance.get_characters_character_id_medals(\n        character_id=93330670\n    )\n    ...\n```\n\n#### Token as parameter\n\nAnother way of providing your access token is as parameter when making the call to the endpoint:\n\n```python\nfrom esi_client.api.character_api import CharacterApi\n\napi_instance = CharacterApi(api_client)\napi_response = api_instance.get_characters_character_id_medals(\n    character_id=93330670, token=\"ACCESS-TOKEN\"\n)\n```\n\n### Getting HTTP information for a response\n\nIn some cases you also need to get the HTTP information for a response. e.g. if a endpoint supports paging the information about how many pages there are is in the HTTP header.\n\nTo get the HTTP information you need to pass the argument `_return_http_data_only=False` when calling the API method. The API method will then return a tuple consisting of:\n\n- data\n- HTTP status code\n- HTTP response headers\n\nHere is an example:\n\n```python\nfrom esi_client.api.universe_api import UniverseApi\n\napi = UniverseApi()\ndata, status_code, header = api.get_universe_types(_return_http_data_only=False)\n```\n\nThe source code for these examples can also be found in project's `examples` folder.\n",
    "bugtrack_url": null,
    "license": "MIT License  Copyright (c) 2023 Erik Kalkoken  Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:  The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.  THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
    "summary": "A Python client for accessing the complete Eve Online ESI API.",
    "version": "0.1.0a2",
    "project_urls": {
        "Homepage": "https://gitlab.com/ErikKalkoken/esi-client-generator"
    },
    "split_keywords": [
        "eve swagger interface",
        "eve online"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "d63ef1586a1e5b8cc84da6d3cabc024261c65bc06a25a4be2908edc9a9753df3",
                "md5": "99b70fa67a2752478ed6f5f486a0ff2a",
                "sha256": "368eff95ad20c1bf7e31546cca830bb10e04b001d2c74366225030fbe6f79e4d"
            },
            "downloads": -1,
            "filename": "esi_client-0.1.0a2-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "99b70fa67a2752478ed6f5f486a0ff2a",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.6",
            "size": 1643624,
            "upload_time": "2023-04-29T21:45:05",
            "upload_time_iso_8601": "2023-04-29T21:45:05.939153Z",
            "url": "https://files.pythonhosted.org/packages/d6/3e/f1586a1e5b8cc84da6d3cabc024261c65bc06a25a4be2908edc9a9753df3/esi_client-0.1.0a2-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "f7e890a3351b51bda622f1af5f2ae893a2d0f6c6f9caf1adf052c6fe58f2c619",
                "md5": "9ff2eaac9b312b2ec27c84703817e6ed",
                "sha256": "6b912efbca390ad4d5ddbfdb1ca8c54cc7f738e62fdbcc9b0546c64a7cb75712"
            },
            "downloads": -1,
            "filename": "esi_client-0.1.0a2.tar.gz",
            "has_sig": false,
            "md5_digest": "9ff2eaac9b312b2ec27c84703817e6ed",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.6",
            "size": 349569,
            "upload_time": "2023-04-29T21:45:08",
            "upload_time_iso_8601": "2023-04-29T21:45:08.334770Z",
            "url": "https://files.pythonhosted.org/packages/f7/e8/90a3351b51bda622f1af5f2ae893a2d0f6c6f9caf1adf052c6fe58f2c619/esi_client-0.1.0a2.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-04-29 21:45:08",
    "github": false,
    "gitlab": true,
    "bitbucket": false,
    "gitlab_user": "ErikKalkoken",
    "gitlab_project": "esi-client-generator",
    "lcname": "esi-client"
}
        
Elapsed time: 1.27057s