| Name | pychasing JSON |
| Version |
0.1.8
JSON |
| download |
| home_page | |
| Summary | Short description |
| upload_time | 2023-06-04 20:52:17 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.7 |
| license | MIT License Copyright (c) 2022-2023 Tanner B. Corcoran 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 |
a
b
c
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
A full-functionality wrapper for the https://ballchasing.com API.
# Install
`$ pip install pychasing`
# The pychasing Client
The `pychasing.Client` class is the main object used to interact with the Ballchasing API.
```py
import pychasing
pychasing_client = pychasing.Client(
token="your_token",
auto_rate_limit=True,
patreon_tier=pychasing.PatreonTier.none # same as "regular"
)
```
Before we get into the methods of `Client`, there are a few things to note about rate limit handling. If `auto_rate_limit` is set to `False`, any request you make will be immediately sent to the ballchasing API. If `auto_rate_limit` is set to `True`, the client will automatically limit the rate of your requests, taking into account both hourly quota and burst limit. This is done through `time.sleep`, so how long it takes to get a response from a given method will depend on how often you are using the API, as well as your Ballchasing Patreon tier. Additionally, there is a `rate_limit_safe_start` option; if this option is set to `True`, the rate limiting will start off as already maxed out on API calls. This prevents any issues from arising if you are reinstantiating the client often (e.g. if you are testing by running a script multiple times). If this option is set to `False`, the rate limiter will assume that you haven't made any API calls in the past hour, and will rate limit accordingly. For long-running programs and use a single client instance, this option isn't necessarily needed, but I would always recommend it be enabled.
The `pychasing.Client` object has the below methods:
- `ping` - pings the ballchasing servers.
- `upload_replay` - uploads a replay to the token-holder's account.
- NOTE: this takes a `BinaryIO` object. For example:
```py
with open("my_replay.replay", "rb") as replay_file:
...upload_replay(replay_file, ...)
```
- `list_replays` - list replays (basic information only) filtered on various criteria.
- `get_replay` - get the in-depth information of a specific replay.
- `delete_replay` - delete a specific replay, so long as it is owned by the token-holder.
- NOTE: this operation is **permenant** and cannot be undone.
- `patch_replay` - edit the `title`, `visibility` or parent `group` of a specific replay.
- `download_replay` - download the raw bytes of a specific replay, so long as it is not private (unless it is owned by the token-holder).
- NOTE: since replays are relatively large, they should be downloaded in chunks. For example:
```py
with ...download_replay(...) as data_stream:
with open("my_replay.replay", "wb") as replay_file:
for chunk in data_stream.iter_content(chunk_size=4096):
replay_file.write(chunk)
```
- `create_group` - create a replay group.
- `list_groups` - list groups (basic information only) filtered on various criteria.
- `get_group` - get in-depth information of a specific replay group.
- `delete_group` - delete a specific group, so long as it is owned by the token-holder.
- NOTE: this operation is **permenant** and cannot be undone.
- `patch_group` - edit the `player-identification`, `team-identification`, `parent`, or `shared` status of a specific replay group, so long as it owned by the token-holder.
- `maps` - list all the maps in the game.
- `get_threejs` - get basic locational data (among other data) of a specific replay. This does not require
- NOTE: this functionality is highly experimental. It accesses a back-end API used for populating site data (that notably does not require authorization headers). At any time, this API could become restricted or its functionality could change.
- `get_timeline` - get basic timeline data of a specific replay.
- NOTE: this functionality is highly experimental. It accesses a back-end API used for populating site data (that notably does not require authorization headers). At any time, this API could become restricted or its functionality could change.
- `export_csv` - get group statistics formatted as semi-colon-separated values.
# Enums and other types
Many of the methods in `Client` can use custom enumerations for ease of use. For example, when setting the visibility of a replay through `Client.patch_replay`, you could set `visibility` to `"unlisted"` *or* `Visibility.unlisted`. These Enums are listed below:
- `pychasing.Rank` - used for `min_rank` and `max_rank` in `list_replays`
- `pychasing.Playlist` - used for `playlists` in `list_replays`
- `pychasing.Platform` - used for `platform` in `list_replays`
- `pychasing.Map` - used for `map` in `list_replays`
- `pychasing.Visibility` - used for `visibility` in `patch_replay` and `patch_group`
- `pychasing.PlayerIdentifiercation` - used for `player_identification` in `create_group` and `patch_group`
- `pychasing.TeamIdentification` - used for `team_identification` in `create_group` and `patch_group`
- `pychasing.MatchResult` - used for `match_result` in `list_replays`
- `pychasing.ReplaySortBy` - used for `sort_by` in `list_replays`
- `pychasing.GroupSortBy` - used for `sort_by` in `list_groups`
- `pychasing.SortDirection` - used for `sort_dir` in `list_replays` and `list_groups`
- `pychasing.GroupStats` - used for `stat` in `export_csv`
- `pychasing.PatreonTier` - used in the initialization of `Client`. This is the only exception to the aforementioned "str or enum" rule above; the proper initialization of `Client` **requires** the `PatreonTier` enum.
Additionally, all date parameters (which require an RFC3339 formatted datetime) also accept a `pychasing.Date`. For example:
```py
...list_replays(created_before="2022-11-22T05:00:30Z")
...list_replays(created_before=pychasing.Date(2022, 11, 22, 5, 0, 30))
```
Raw data
{
"_id": null,
"home_page": "",
"name": "pychasing",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "a,b,c",
"author": "",
"author_email": "\"Tanner B. Corcoran\" <tannerbcorcoran@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/3f/3f/1120dfbd5688f0ca123de5dd3a84f7ab6a3759e8f619b5911c1b86ac68d2/pychasing-0.1.8.tar.gz",
"platform": null,
"description": "A full-functionality wrapper for the https://ballchasing.com API.\r\n\r\n# Install\r\n\r\n`$ pip install pychasing`\r\n\r\n# The pychasing Client\r\n\r\nThe `pychasing.Client` class is the main object used to interact with the Ballchasing API.\r\n\r\n```py\r\nimport pychasing\r\n\r\npychasing_client = pychasing.Client(\r\n token=\"your_token\",\r\n auto_rate_limit=True,\r\n patreon_tier=pychasing.PatreonTier.none # same as \"regular\"\r\n)\r\n```\r\n\r\nBefore we get into the methods of `Client`, there are a few things to note about rate limit handling. If `auto_rate_limit` is set to `False`, any request you make will be immediately sent to the ballchasing API. If `auto_rate_limit` is set to `True`, the client will automatically limit the rate of your requests, taking into account both hourly quota and burst limit. This is done through `time.sleep`, so how long it takes to get a response from a given method will depend on how often you are using the API, as well as your Ballchasing Patreon tier. Additionally, there is a `rate_limit_safe_start` option; if this option is set to `True`, the rate limiting will start off as already maxed out on API calls. This prevents any issues from arising if you are reinstantiating the client often (e.g. if you are testing by running a script multiple times). If this option is set to `False`, the rate limiter will assume that you haven't made any API calls in the past hour, and will rate limit accordingly. For long-running programs and use a single client instance, this option isn't necessarily needed, but I would always recommend it be enabled.\r\n\r\nThe `pychasing.Client` object has the below methods:\r\n- `ping` - pings the ballchasing servers.\r\n- `upload_replay` - uploads a replay to the token-holder's account.\r\n - NOTE: this takes a `BinaryIO` object. For example:\r\n ```py\r\n with open(\"my_replay.replay\", \"rb\") as replay_file:\r\n ...upload_replay(replay_file, ...)\r\n ```\r\n- `list_replays` - list replays (basic information only) filtered on various criteria.\r\n- `get_replay` - get the in-depth information of a specific replay.\r\n- `delete_replay` - delete a specific replay, so long as it is owned by the token-holder.\r\n - NOTE: this operation is **permenant** and cannot be undone.\r\n- `patch_replay` - edit the `title`, `visibility` or parent `group` of a specific replay.\r\n- `download_replay` - download the raw bytes of a specific replay, so long as it is not private (unless it is owned by the token-holder).\r\n - NOTE: since replays are relatively large, they should be downloaded in chunks. For example:\r\n ```py\r\n with ...download_replay(...) as data_stream:\r\n with open(\"my_replay.replay\", \"wb\") as replay_file:\r\n for chunk in data_stream.iter_content(chunk_size=4096):\r\n replay_file.write(chunk)\r\n ```\r\n- `create_group` - create a replay group.\r\n- `list_groups` - list groups (basic information only) filtered on various criteria.\r\n- `get_group` - get in-depth information of a specific replay group.\r\n- `delete_group` - delete a specific group, so long as it is owned by the token-holder.\r\n - NOTE: this operation is **permenant** and cannot be undone.\r\n- `patch_group` - edit the `player-identification`, `team-identification`, `parent`, or `shared` status of a specific replay group, so long as it owned by the token-holder.\r\n- `maps` - list all the maps in the game.\r\n- `get_threejs` - get basic locational data (among other data) of a specific replay. This does not require\r\n - NOTE: this functionality is highly experimental. It accesses a back-end API used for populating site data (that notably does not require authorization headers). At any time, this API could become restricted or its functionality could change.\r\n- `get_timeline` - get basic timeline data of a specific replay.\r\n - NOTE: this functionality is highly experimental. It accesses a back-end API used for populating site data (that notably does not require authorization headers). At any time, this API could become restricted or its functionality could change.\r\n- `export_csv` - get group statistics formatted as semi-colon-separated values.\r\n\r\n# Enums and other types\r\n\r\nMany of the methods in `Client` can use custom enumerations for ease of use. For example, when setting the visibility of a replay through `Client.patch_replay`, you could set `visibility` to `\"unlisted\"` *or* `Visibility.unlisted`. These Enums are listed below:\r\n- `pychasing.Rank` - used for `min_rank` and `max_rank` in `list_replays`\r\n- `pychasing.Playlist` - used for `playlists` in `list_replays`\r\n- `pychasing.Platform` - used for `platform` in `list_replays`\r\n- `pychasing.Map` - used for `map` in `list_replays`\r\n- `pychasing.Visibility` - used for `visibility` in `patch_replay` and `patch_group`\r\n- `pychasing.PlayerIdentifiercation` - used for `player_identification` in `create_group` and `patch_group`\r\n- `pychasing.TeamIdentification` - used for `team_identification` in `create_group` and `patch_group`\r\n- `pychasing.MatchResult` - used for `match_result` in `list_replays`\r\n- `pychasing.ReplaySortBy` - used for `sort_by` in `list_replays`\r\n- `pychasing.GroupSortBy` - used for `sort_by` in `list_groups`\r\n- `pychasing.SortDirection` - used for `sort_dir` in `list_replays` and `list_groups`\r\n- `pychasing.GroupStats` - used for `stat` in `export_csv`\r\n- `pychasing.PatreonTier` - used in the initialization of `Client`. This is the only exception to the aforementioned \"str or enum\" rule above; the proper initialization of `Client` **requires** the `PatreonTier` enum.\r\n\r\nAdditionally, all date parameters (which require an RFC3339 formatted datetime) also accept a `pychasing.Date`. For example:\r\n\r\n```py\r\n...list_replays(created_before=\"2022-11-22T05:00:30Z\")\r\n...list_replays(created_before=pychasing.Date(2022, 11, 22, 5, 0, 30)) \r\n```\r\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2022-2023 Tanner B. Corcoran 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": "Short description",
"version": "0.1.8",
"project_urls": {
"changelog": "https://github.com/tanrbobanr/pychasing/blob/main/changelog.md",
"documentation": "https://github.com/tanrbobanr/pychasing/blob/main/README.md",
"repository": "https://github.com/tanrbobanr/pychasing"
},
"split_keywords": [
"a",
"b",
"c"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "341bdd12b7e8f89c55b6912a24b81a474067dae5ea02649d1777a67d0c91cad4",
"md5": "f3266cdec64ab7b23f919a8155d8ccfe",
"sha256": "239ba1f8e47c014e4e27d1b121bb1da59523c21e62c1471492c2bec6250ad04e"
},
"downloads": -1,
"filename": "pychasing-0.1.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f3266cdec64ab7b23f919a8155d8ccfe",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 14099,
"upload_time": "2023-06-04T20:52:16",
"upload_time_iso_8601": "2023-06-04T20:52:16.393750Z",
"url": "https://files.pythonhosted.org/packages/34/1b/dd12b7e8f89c55b6912a24b81a474067dae5ea02649d1777a67d0c91cad4/pychasing-0.1.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3f3f1120dfbd5688f0ca123de5dd3a84f7ab6a3759e8f619b5911c1b86ac68d2",
"md5": "a31d54862ff81eaab273ae37b9a73318",
"sha256": "b146929d0d9991f08fbfe92fba2218bc2e741fe968cb53e7653b9775b1921841"
},
"downloads": -1,
"filename": "pychasing-0.1.8.tar.gz",
"has_sig": false,
"md5_digest": "a31d54862ff81eaab273ae37b9a73318",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 16768,
"upload_time": "2023-06-04T20:52:17",
"upload_time_iso_8601": "2023-06-04T20:52:17.592606Z",
"url": "https://files.pythonhosted.org/packages/3f/3f/1120dfbd5688f0ca123de5dd3a84f7ab6a3759e8f619b5911c1b86ac68d2/pychasing-0.1.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-04 20:52:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tanrbobanr",
"github_project": "pychasing",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pychasing"
}
