# Preston
[](https://github.com/Celeo/preston/actions?query=workflow%3ACI)
[](https://codecov.io/gh/Celeo/preston)
[](https://www.python.org/)
[](https://github.com/psf/black)
[](LICENSE)
Preston is a Python library for accessing EVE Online's ESI API.
## Quick links
* EVE ESI: <https://esi.evetech.net>
* EVE developers: <https://developers.eveonline.com>
## Installation
From [pip](https://pip.pypa.io/en/stable/):
```sh
pip install preston
```
## Initialization
```python
from preston import Preston
preston = Preston()
```
There are values that you can pass to `__init__` as kwargs; those are detailed in the docstring for the class.
## Usage
There are 3 main things that Preston does:
1. Unauthenticated calls to ESI
2. User authentication
3. Authenticated calls to ESI for that user
For #1, all you need to do is initialize a Preston object and make the call:
```python
preston = Preston(
user_agent='some_user_agent'
)
data = preston.get_op('get_characters_character_id', character_id=91316135)
# ...
```
You should always include a good `user_agent`.
Additionally, a `post_op` method exists, that takes a dictionary (instead of **kwargs) and another parameter; the former is used like above, to satisfy the URL parameters, and the latter is sent to the ESI endpoint as the payloadd.
For #2, there are 2 methods that you'll need, `get_authorize_url` and `authenticate`, and several `__init__` kwargs.
```python
preston = Preston(
user_agent='some_user_agent',
client_id='something',
client_secret='something',
callback_url='something',
scope='maybe_something',
)
```
You can find the last 4 values in your application on the [EVE Dev site](https://developers.eveonline.com/).
When you have a Preston instance constructed like this, you can make the call to `get_authorize_url`:
```python
preston.get_authorize_url()
# https://login.eveonline.com/oauth/...
```
This is the URL that your user needs to visit and complete the flow. They'll be redirected to your app's callback URL, so you have to be monitoring that.
When you get their callback, take the code paramter from the URL and pass it to `authenticate`:
```python
auth = preston.authenticate('their_code_here')
```
Note the return variable and it's reassignment: this method returns a *new* instance, with the corresponding variables and headers setup for authenticated ESI calls.
Finally for #3, having followed the steps above, you just make calls like previously, but you can do so to the authenticated-only endpoints. Make sure that if you're calling
an endpoint that requires a specific scope, your app on EVE Devs has that scoped added and you've supplied it to the Preston initialization.
### Resuming authentication
If your app uses scopes, it'll receive a `refresh_token` alongside the `access_token`. The access token, per usual, only lasts 20 minutes before it expires. In this situation,
the refresh token can be used to get a *new* access token. If your Preston instance has a refresh token, this will be done automatically when the access token expires.
You can also get this refresh token from the Preston instance with `token = preston.refresh_token`. This can be then stored somewhere (securely) and used again later by
passing the token to Preston's constructor:
```python
preston = Preston(
user_agent='some_user_agent',
client_id='something',
client_secret='something',
callback_url='something',
scope='maybe_something',
refresh_token='your_token_here'
)
```
Preston will take the refresh token and attempt to get a new access token from it.
On that note, you can also pass the `access_token` to a new Preston instance, but there's less of a use case for that, as either you have an app with scopes, yielding a refresh token,
or an authentication-only app where you only use the access token to verify identity and some basic information before moving on.
## Developing
### Building
### Requirements
* Git
* Poetry
* Python 3.8+
### Steps
```sh
git clone https://github.com/Celeo/preston
cd preston
poetry install
```
### Running tests
| | |
| --- | --- |
| No coverage | `poetry run pytest`
| Coverage printout | `poetry run pytest --cov=preston` |
| Coverage report | `poetry run pytest --cov=preston --cov-report=html` |
## License
Licensed under MIT ([LICENSE](LICENSE)).
## Contributing
PRs are welcome. Please follow PEP8 (I'm lenient on E501) and use [Google-style docstrings](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html#example-google).
Raw data
{
"_id": null,
"home_page": "https://github.com/Celeo/Preston",
"name": "preston",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "eve online,eve,esi",
"author": "Celeo",
"author_email": "mattboulanger@fastmail.com",
"download_url": "https://files.pythonhosted.org/packages/4d/97/9aeb73bb536865a9b0becb1194ff23680783147c2292cc47ae82f435a015/preston-4.5.0.tar.gz",
"platform": null,
"description": "# Preston\n\n[](https://github.com/Celeo/preston/actions?query=workflow%3ACI)\n[](https://codecov.io/gh/Celeo/preston)\n[](https://www.python.org/)\n[](https://github.com/psf/black)\n[](LICENSE)\n\nPreston is a Python library for accessing EVE Online's ESI API.\n\n## Quick links\n\n* EVE ESI: <https://esi.evetech.net>\n* EVE developers: <https://developers.eveonline.com>\n\n## Installation\n\nFrom [pip](https://pip.pypa.io/en/stable/):\n\n```sh\npip install preston\n```\n\n## Initialization\n\n```python\nfrom preston import Preston\n\npreston = Preston()\n```\n\nThere are values that you can pass to `__init__` as kwargs; those are detailed in the docstring for the class.\n\n## Usage\n\nThere are 3 main things that Preston does:\n\n1. Unauthenticated calls to ESI\n2. User authentication\n3. Authenticated calls to ESI for that user\n\nFor #1, all you need to do is initialize a Preston object and make the call:\n\n```python\npreston = Preston(\n user_agent='some_user_agent'\n)\n\ndata = preston.get_op('get_characters_character_id', character_id=91316135)\n# ...\n```\n\nYou should always include a good `user_agent`.\n\nAdditionally, a `post_op` method exists, that takes a dictionary (instead of **kwargs) and another parameter; the former is used like above, to satisfy the URL parameters, and the latter is sent to the ESI endpoint as the payloadd.\n\nFor #2, there are 2 methods that you'll need, `get_authorize_url` and `authenticate`, and several `__init__` kwargs.\n\n```python\npreston = Preston(\n user_agent='some_user_agent',\n client_id='something',\n client_secret='something',\n callback_url='something',\n scope='maybe_something',\n)\n```\n\nYou can find the last 4 values in your application on the [EVE Dev site](https://developers.eveonline.com/).\n\nWhen you have a Preston instance constructed like this, you can make the call to `get_authorize_url`:\n\n```python\npreston.get_authorize_url()\n# https://login.eveonline.com/oauth/...\n```\n\nThis is the URL that your user needs to visit and complete the flow. They'll be redirected to your app's callback URL, so you have to be monitoring that.\n\nWhen you get their callback, take the code paramter from the URL and pass it to `authenticate`:\n\n```python\nauth = preston.authenticate('their_code_here')\n```\n\nNote the return variable and it's reassignment: this method returns a *new* instance, with the corresponding variables and headers setup for authenticated ESI calls.\n\nFinally for #3, having followed the steps above, you just make calls like previously, but you can do so to the authenticated-only endpoints. Make sure that if you're calling\nan endpoint that requires a specific scope, your app on EVE Devs has that scoped added and you've supplied it to the Preston initialization.\n\n### Resuming authentication\n\nIf your app uses scopes, it'll receive a `refresh_token` alongside the `access_token`. The access token, per usual, only lasts 20 minutes before it expires. In this situation,\nthe refresh token can be used to get a *new* access token. If your Preston instance has a refresh token, this will be done automatically when the access token expires.\n\nYou can also get this refresh token from the Preston instance with `token = preston.refresh_token`. This can be then stored somewhere (securely) and used again later by\npassing the token to Preston's constructor:\n\n```python\npreston = Preston(\n user_agent='some_user_agent',\n client_id='something',\n client_secret='something',\n callback_url='something',\n scope='maybe_something',\n refresh_token='your_token_here'\n)\n```\n\nPreston will take the refresh token and attempt to get a new access token from it.\n\nOn that note, you can also pass the `access_token` to a new Preston instance, but there's less of a use case for that, as either you have an app with scopes, yielding a refresh token,\nor an authentication-only app where you only use the access token to verify identity and some basic information before moving on.\n\n## Developing\n\n### Building\n\n### Requirements\n\n* Git\n* Poetry\n* Python 3.8+\n\n### Steps\n\n```sh\ngit clone https://github.com/Celeo/preston\ncd preston\npoetry install\n```\n\n### Running tests\n\n| | |\n| --- | --- |\n| No coverage | `poetry run pytest`\n| Coverage printout | `poetry run pytest --cov=preston` |\n| Coverage report | `poetry run pytest --cov=preston --cov-report=html` |\n\n## License\n\nLicensed under MIT ([LICENSE](LICENSE)).\n\n## Contributing\n\nPRs are welcome. Please follow PEP8 (I'm lenient on E501) and use [Google-style docstrings](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html#example-google).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "EVE ESI API access tool",
"version": "4.5.0",
"project_urls": {
"Homepage": "https://github.com/Celeo/Preston",
"Repository": "https://github.com/Celeo/Preston"
},
"split_keywords": [
"eve online",
"eve",
"esi"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c33afc5b35e57b5b8775c595da30532bb312c81cb78d51946d503db68a3a4ed2",
"md5": "781f7dd41874cd05a4afb4414f74b21c",
"sha256": "cda473df4d69a4e7c3244fdd1ce9b52975d86ce65fde0caa3f01c7bca9089f75"
},
"downloads": -1,
"filename": "preston-4.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "781f7dd41874cd05a4afb4414f74b21c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 8925,
"upload_time": "2024-01-21T05:51:22",
"upload_time_iso_8601": "2024-01-21T05:51:22.348406Z",
"url": "https://files.pythonhosted.org/packages/c3/3a/fc5b35e57b5b8775c595da30532bb312c81cb78d51946d503db68a3a4ed2/preston-4.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4d979aeb73bb536865a9b0becb1194ff23680783147c2292cc47ae82f435a015",
"md5": "75d3972a504699e25553df272b367daf",
"sha256": "2fdf505afae61c7ba1c44ad23decc482e62680bdb702f0351bca1425a59506c4"
},
"downloads": -1,
"filename": "preston-4.5.0.tar.gz",
"has_sig": false,
"md5_digest": "75d3972a504699e25553df272b367daf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 7981,
"upload_time": "2024-01-21T05:51:24",
"upload_time_iso_8601": "2024-01-21T05:51:24.066592Z",
"url": "https://files.pythonhosted.org/packages/4d/97/9aeb73bb536865a9b0becb1194ff23680783147c2292cc47ae82f435a015/preston-4.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-21 05:51:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Celeo",
"github_project": "Preston",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "preston"
}
JSON
