# tardis-client
[](https://pypi.org/project/tardis-client/)
[](https://pypi.org/project/tardis-client/)
<a href="https://github.com/psf/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
Python client for [tardis.dev](https://tardis.dev) - historical tick-level cryptocurrency market data replay API.
Provides fast, high level and developer friendly wrapper for more low level [HTTP API](https://docs.tardis.dev/api#http-api) with local file based caching build in.
## Installation
Requires Python 3.7.0+ installed.
```sh
pip install tardis-client
```
## Usage
```python
import asyncio
from tardis_client import TardisClient, Channel
async def replay():
tardis_client = TardisClient()
# replay method returns Async Generator
# https://rickyhan.com/jekyll/update/2018/01/27/python36.html
messages = tardis_client.replay(
exchange="bitmex",
from_date="2019-06-01",
to_date="2019-06-02",
filters=[Channel(name="trade", symbols=["XBTUSD","ETHUSD"]), Channel("orderBookL2", ["XBTUSD"])],
)
# this will print all trades and orderBookL2 messages for XBTUSD
# and all trades for ETHUSD for bitmex exchange
# between 2019-06-01T00:00:00.000Z and 2019-06-02T00:00:00.000Z (whole first day of June 2019)
async for local_timestamp, message in messages:
# local timestamp is a Python datetime that marks timestamp when given message has been received
# message is a message object as provided by exchange real-time stream
print(message)
asyncio.run(replay())
```
[](https://repl.it/@TardisThad/tardis-python-client-example)
## API
`tardis-client` package provides `TardisClient` and `Channel` classes.
```python
from tardis_client import TardisClient, Channel
```
### TardisClient
Optional client constructor parameters.
| name | type | default value | description |
| ---------------------- | -------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api_key` (optional) | `string` | `""` | optional `string` containing API key for [tardis.dev](https://tardis.dev) API. If not provided only first day of each month of data is accessible (free access) |
| `cache_dir` (optional) | `string` | `<os.tmpdir>/.tardis-cache` | optional `string` with path to local dir that will be used as cache location. If not provided default `temp` dir for given OS will be used. |
Example:
```python
# creates new client instance with access only to sample data (first day of each month)
tardis_client = TardisClient()
# creates new client with access to all data for given API key
tardis_client = TardisClient(api_key="YOUR_API_KEY")
# creates new client with custom cache dir
tardis_client = TardisClient(cache_dir="./cache")
```
- ### `tardis_client.clear_cache()`
Removes local file cache dir and it's contents.
Example:
```python
tardis_client = TardisClient()
tardis_client.clear_cache()
```
- ### `tardis_client.replay(exchange, from_date, to_date, filters=[])`
Replays historical market data messages for given replay arguments.
Returns [Async Generator](https://rickyhan.com/jekyll/update/2018/01/27/python36.html) with named tuples (`namedtuple("Response", ["local_timestamp", "message"])`).
- `local_timestamp` is a Python datetime object specyfying when message has been received from the exchange real-time data feed.
- `message` is Python dict with parsed JSON that has exactly the same format as message provided by particular exchange's real-time data feed.
#### `replay` method parameters:
| name | type | default value | description |
| -------------------- | --------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `exchange` | `string` | - | requested exchange name - Use [/exchanges](https://docs.tardis.dev/api/http#exchanges) API call to get allowed exchanges ids |
| `from_date` | `string` | - | requested UTC start date of data feed - [valid ISO date string](https://docs.python.org/3/library/datetime.html#datetime.date.fromisoformat), eg: `2019-04-05` or `2019-05-05T00:00:00` |
| `to_date` | `string` | - | requested UTC end date of data feed - [valid ISO date string](https://docs.python.org/3/library/datetime.html#datetime.date.fromisoformat), eg: `2019-04-05` or `2019-05-05T00:00:00` |
| `filters` (optional) | [`List[Channel]`](#channel-class) | [] | optional filters of requested data feed. Use [/exchanges/:exchange](https://docs.tardis.dev/api/http#exchanges-exchange) API call to get allowed channel names and symbols for requested exchange |
##### `Channel` class
`Channel` class constructor parameters.
| name | type | description |
| --------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | `string` | Use [/exchanges/:exchange](https://docs.tardis.dev/api#exchanges-exchange) API call to get allowed channel names and symbols for requested exchange |
| `symbols` | `List[string]` | Use [/exchanges/:exchange](https://docs.tardis.dev/api#exchanges-exchange) API call to get allowed channel names and symbols for requested exchange |
```python
Channel(name="trade", symbols=["XBTUSD","ETHUSD"])
Channel("orderBookL2", ["XBTUSD"])
```
## FAQ
#### How to debug it if something went wrong?
`tardis-client` uses Python logging on `DEBUG` level for that purpose. In doubt please create issue in this repository with steps how to reproduce the issue.
#### Where can I find more details about tardis.dev API?
Check out [API docs](https://docs.tardis.dev/api).
## License
MPL-2.0
Raw data
{
"_id": null,
"home_page": "https://github.com/tardis-dev/python-client",
"name": "tardis-client",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "cryptocurrency data feed, market data, api client, orderbook, crypto markets data replay, historical data, historical cryptocurrency prices, cryptocurrency api",
"author": "Thad",
"author_email": "thad@tardis.dev",
"download_url": "https://files.pythonhosted.org/packages/5c/81/3128d57dfcec10b410f891c59dbcb71b96c0835b0971e17537129908a082/tardis_client-1.3.9.tar.gz",
"platform": null,
"description": "# tardis-client\n\n[](https://pypi.org/project/tardis-client/)\n[](https://pypi.org/project/tardis-client/)\n<a href=\"https://github.com/psf/black\"><img alt=\"Code style: black\" src=\"https://img.shields.io/badge/code%20style-black-000000.svg\"></a>\n\nPython client for [tardis.dev](https://tardis.dev) - historical tick-level cryptocurrency market data replay API.\nProvides fast, high level and developer friendly wrapper for more low level [HTTP API](https://docs.tardis.dev/api#http-api) with local file based caching build in.\n\n## Installation\n\nRequires Python 3.7.0+ installed.\n\n```sh\npip install tardis-client\n```\n\n## Usage\n\n```python\nimport asyncio\nfrom tardis_client import TardisClient, Channel\n\nasync def replay():\n tardis_client = TardisClient()\n\n # replay method returns Async Generator\n # https://rickyhan.com/jekyll/update/2018/01/27/python36.html\n messages = tardis_client.replay(\n exchange=\"bitmex\",\n from_date=\"2019-06-01\",\n to_date=\"2019-06-02\",\n filters=[Channel(name=\"trade\", symbols=[\"XBTUSD\",\"ETHUSD\"]), Channel(\"orderBookL2\", [\"XBTUSD\"])],\n )\n\n # this will print all trades and orderBookL2 messages for XBTUSD\n # and all trades for ETHUSD for bitmex exchange\n # between 2019-06-01T00:00:00.000Z and 2019-06-02T00:00:00.000Z (whole first day of June 2019)\n async for local_timestamp, message in messages:\n # local timestamp is a Python datetime that marks timestamp when given message has been received\n # message is a message object as provided by exchange real-time stream\n print(message)\n\nasyncio.run(replay())\n```\n\n[](https://repl.it/@TardisThad/tardis-python-client-example)\n\n## API\n\n`tardis-client` package provides `TardisClient` and `Channel` classes.\n\n```python\nfrom tardis_client import TardisClient, Channel\n```\n\n### TardisClient\n\nOptional client constructor parameters.\n\n| name | type | default value | description |\n| ---------------------- | -------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `api_key` (optional) | `string` | `\"\"` | optional `string` containing API key for [tardis.dev](https://tardis.dev) API. If not provided only first day of each month of data is accessible (free access) |\n| `cache_dir` (optional) | `string` | `<os.tmpdir>/.tardis-cache` | optional `string` with path to local dir that will be used as cache location. If not provided default `temp` dir for given OS will be used. |\n\nExample:\n\n```python\n# creates new client instance with access only to sample data (first day of each month)\ntardis_client = TardisClient()\n\n# creates new client with access to all data for given API key\ntardis_client = TardisClient(api_key=\"YOUR_API_KEY\")\n\n# creates new client with custom cache dir\ntardis_client = TardisClient(cache_dir=\"./cache\")\n```\n\n- ### `tardis_client.clear_cache()`\n\n Removes local file cache dir and it's contents.\n\n Example:\n\n ```python\n tardis_client = TardisClient()\n\n tardis_client.clear_cache()\n ```\n\n- ### `tardis_client.replay(exchange, from_date, to_date, filters=[])`\n\n Replays historical market data messages for given replay arguments.\n\n Returns [Async Generator](https://rickyhan.com/jekyll/update/2018/01/27/python36.html) with named tuples (`namedtuple(\"Response\", [\"local_timestamp\", \"message\"])`).\n\n - `local_timestamp` is a Python datetime object specyfying when message has been received from the exchange real-time data feed.\n\n - `message` is Python dict with parsed JSON that has exactly the same format as message provided by particular exchange's real-time data feed.\n\n #### `replay` method parameters:\n\n | name | type | default value | description |\n | -------------------- | --------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n | `exchange` | `string` | - | requested exchange name - Use [/exchanges](https://docs.tardis.dev/api/http#exchanges) API call to get allowed exchanges ids |\n | `from_date` | `string` | - | requested UTC start date of data feed - [valid ISO date string](https://docs.python.org/3/library/datetime.html#datetime.date.fromisoformat), eg: `2019-04-05` or `2019-05-05T00:00:00` |\n | `to_date` | `string` | - | requested UTC end date of data feed - [valid ISO date string](https://docs.python.org/3/library/datetime.html#datetime.date.fromisoformat), eg: `2019-04-05` or `2019-05-05T00:00:00` |\n | `filters` (optional) | [`List[Channel]`](#channel-class) | [] | optional filters of requested data feed. Use [/exchanges/:exchange](https://docs.tardis.dev/api/http#exchanges-exchange) API call to get allowed channel names and symbols for requested exchange |\n\n ##### `Channel` class\n\n `Channel` class constructor parameters.\n\n | name | type | description |\n | --------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |\n | `name` | `string` | Use [/exchanges/:exchange](https://docs.tardis.dev/api#exchanges-exchange) API call to get allowed channel names and symbols for requested exchange |\n | `symbols` | `List[string]` | Use [/exchanges/:exchange](https://docs.tardis.dev/api#exchanges-exchange) API call to get allowed channel names and symbols for requested exchange |\n\n ```python\n Channel(name=\"trade\", symbols=[\"XBTUSD\",\"ETHUSD\"])\n Channel(\"orderBookL2\", [\"XBTUSD\"])\n ```\n\n## FAQ\n\n#### How to debug it if something went wrong?\n\n`tardis-client` uses Python logging on `DEBUG` level for that purpose. In doubt please create issue in this repository with steps how to reproduce the issue.\n\n#### Where can I find more details about tardis.dev API?\n\nCheck out [API docs](https://docs.tardis.dev/api).\n\n## License\n\nMPL-2.0\n",
"bugtrack_url": null,
"license": "MPL-2.0",
"summary": "Python client for tardis.dev - historical tick-level cryptocurrency market data replay API.",
"version": "1.3.9",
"project_urls": {
"Homepage": "https://github.com/tardis-dev/python-client"
},
"split_keywords": [
"cryptocurrency data feed",
" market data",
" api client",
" orderbook",
" crypto markets data replay",
" historical data",
" historical cryptocurrency prices",
" cryptocurrency api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "597fa01ef90bec7a22aad2023e947fc70cddcd0781e6e6c236eecc66413f539e",
"md5": "718370a09cf95a243a55dc3e3f2e5012",
"sha256": "fcf2cab062ed93abae7695a7d14d33ca3e8ed2d6b9245e300c612a3950abbe44"
},
"downloads": -1,
"filename": "tardis_client-1.3.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "718370a09cf95a243a55dc3e3f2e5012",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 18250,
"upload_time": "2024-10-04T07:18:52",
"upload_time_iso_8601": "2024-10-04T07:18:52.004149Z",
"url": "https://files.pythonhosted.org/packages/59/7f/a01ef90bec7a22aad2023e947fc70cddcd0781e6e6c236eecc66413f539e/tardis_client-1.3.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5c813128d57dfcec10b410f891c59dbcb71b96c0835b0971e17537129908a082",
"md5": "7c5d7181c4fdbc32239b80cab811a603",
"sha256": "ba3ede82f3e51081c2083faf8b2b990da7aa8101abdaa785c73b23c3cc8bf4fe"
},
"downloads": -1,
"filename": "tardis_client-1.3.9.tar.gz",
"has_sig": false,
"md5_digest": "7c5d7181c4fdbc32239b80cab811a603",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 17636,
"upload_time": "2024-10-04T07:18:53",
"upload_time_iso_8601": "2024-10-04T07:18:53.719883Z",
"url": "https://files.pythonhosted.org/packages/5c/81/3128d57dfcec10b410f891c59dbcb71b96c0835b0971e17537129908a082/tardis_client-1.3.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-04 07:18:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tardis-dev",
"github_project": "python-client",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "tardis-client"
}
JSON
