| Name | kline-timestamp JSON |
| Version |
0.1.6
JSON |
| download |
| home_page | https://github.com/nand0san/kline_timestamp |
| Summary | KlineTimestamp is a Python library designed to efficiently handle timestamps within discrete time intervals, commonly known as klines or candlesticks, often used in financial data analysis. |
| upload_time | 2024-10-20 18:37:59 |
| maintainer | None |
| docs_url | None |
| author | nand0san |
| requires_python | >=3.6 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# KlineTimestamp
KlineTimestamp is a Python library designed to efficiently handle timestamps within discrete time intervals, commonly known as klines or candlesticks, often used in financial data analysis. This library simplifies the management of Unix timestamps (in milliseconds) for applications that work with time series data, particularly those involving financial market data.
Project: https://github.com/nand0san/KlineTimestamp/tree/github
## Features
- **Calculate Opening and Closing Timestamps**: Easily obtain the opening and closing timestamps of a kline based on specified intervals.
- **Timezone Support**: Handle different timezones with correct Daylight Saving Time (DST) adjustments.
- **Convert to Common Date-Time Objects**: Convert timestamps to `datetime.datetime` and `pandas.Timestamp` objects for seamless integration with other libraries.
- **Arithmetic Operations**: Modify timestamps using `timedelta` objects, and perform arithmetic operations between klines.
- **Navigation Between Klines**: Retrieve the next or previous kline's opening and closing timestamps.
- **Comparison Methods**: Compare klines using standard comparison operators (`==`, `!=`, `<`, `<=`, `>`, `>=`).
- **Robust Equality Checks**: Determine if two klines represent the same time interval, considering interval and timezone.
## Installation
Install the library using `pip`:
```bash
pip install kline_timestamp
```
## Dependencies
- Python 3.x
- [`pytz`](https://pypi.org/project/pytz/)
- [`pandas`](https://pypi.org/project/pandas/)
## Usage
### Importing the Library
```python
from kline_timestamp import KlineTimestamp
from datetime import timedelta
```
### Creating a KlineTimestamp Instance
```python
# Create an instance with a specific timestamp, interval, and timezone
kt = KlineTimestamp(timestamp_ms=1633036800000, interval='1h', tzinfo='Europe/Madrid')
```
### Getting Opening and Closing Timestamps
```python
# Get the opening timestamp in milliseconds
open_ts_ms = kt.get_candle_open_timestamp_ms()
print(f"Open timestamp (ms): {open_ts_ms}")
# Get the closing timestamp in milliseconds
close_ts_ms = kt.get_candle_close_timestamp_ms()
print(f"Close timestamp (ms): {close_ts_ms}")
# Access opening and closing timestamps as attributes
print(f"Open as attribute: {kt.open}")
print(f"Close as attribute: {kt.close}")
```
### Converting to Datetime Objects
```python
# Convert to datetime in the specified timezone
dt = kt.to_datetime()
print(f"Datetime: {dt}")
# Convert to pandas Timestamp
pd_ts = kt.to_pandas_timestamp()
print(f"Pandas Timestamp: {pd_ts}")
```
### String Representation
```python
# String representation of the KlineTimestamp instance
print(f"String representation: {str(kt)}")
print(f"Representation: {repr(kt)}")
```
### Updating Timezone
```python
# Update the timezone of the instance
kt.update_timezone('UTC')
print(f"Updated timezone: {kt.tzinfo}")
print(kt)
```
### Arithmetic Operations with Timedelta
```python
# Add a timedelta to the timestamp
kt_added = kt + timedelta(hours=1)
print(f"Timestamp after adding 1 hour: {kt_added.to_datetime()}")
# Subtract a timedelta from the timestamp
kt_subtracted = kt - timedelta(hours=1)
print(f"Timestamp after subtracting 1 hour: {kt_subtracted.to_datetime()}")
```
### Subtracting Two KlineTimestamp Instances
```python
# Create another KlineTimestamp instance
kt_other = KlineTimestamp(timestamp_ms=1633033200000, interval='1h', tzinfo='UTC')
# Subtract two KlineTimestamp instances to get a timedelta
time_diff = kt - kt_other
print(f"Time difference between kt and kt_other: {time_diff}")
```
### Navigating Between Klines
```python
# Get the next kline
kt_next = kt.next()
print(f"Next candle timestamp: {kt_next.to_datetime()}")
# Get the previous kline
kt_prev = kt.prev()
print(f"Previous candle timestamp: {kt_prev.to_datetime()}")
```
### Comparison Methods
```python
# Compare two KlineTimestamp instances
print(f"kt == kt_other: {kt == kt_other}")
print(f"kt > kt_other: {kt > kt_other}")
print(f"kt < kt_other: {kt < kt_other}")
print(f"kt >= kt_other: {kt >= kt_other}")
print(f"kt <= kt_other: {kt <= kt_other}")
# Equality with the same parameters
kt_same = KlineTimestamp(timestamp_ms=1633036800000, interval='1h', tzinfo='UTC')
print(f"kt == kt_same: {kt == kt_same}")
```
## Supported Intervals
The following intervals are supported:
- `'1m'`: 1 minute
- `'3m'`: 3 minutes
- `'5m'`: 5 minutes
- `'15m'`: 15 minutes
- `'30m'`: 30 minutes
- `'1h'`: 1 hour
- `'2h'`: 2 hours
- `'4h'`: 4 hours
- `'6h'`: 6 hours
- `'8h'`: 8 hours
- `'12h'`: 12 hours
- `'1d'`: 1 day
- `'3d'`: 3 days
- `'1w'`: 1 week
## API Reference
### Class: `KlineTimestamp`
#### Initialization
```python
KlineTimestamp(timestamp_ms: int, interval: str, tzinfo='UTC')
```
- **Parameters**:
- `timestamp_ms` (int): The timestamp in milliseconds.
- `interval` (str): The interval of the kline. Must be one of the supported intervals.
- `tzinfo` (str or pytz.timezone, optional): The timezone of the timestamp. Defaults to `'UTC'`.
- **Raises**:
- `ValueError`: If the interval is not valid.
- `TypeError`: If `tzinfo` is neither a string nor a `pytz.timezone` object.
#### Attributes
- `timestamp_ms` (int): The original timestamp in milliseconds.
- `interval` (str): The interval of the kline.
- `tzinfo` (`pytz.timezone`): The timezone of the timestamp.
- `open` (int): The opening timestamp of the kline in milliseconds.
- `close` (int): The closing timestamp of the kline in milliseconds.
#### Methods
- `get_candle_open_timestamp_ms() -> int`: Returns the opening timestamp of the current kline in milliseconds.
- `get_candle_close_timestamp_ms() -> int`: Returns the closing timestamp of the current kline in milliseconds.
- `to_datetime() -> datetime`: Converts the opening timestamp to a `datetime` object in the specified timezone.
- `to_pandas_timestamp() -> pd.Timestamp`: Converts the opening timestamp to a `pandas.Timestamp` object in the specified timezone.
- `update_timezone(tzinfo: Union[str, pytz.BaseTzInfo]) -> None`: Updates the timezone of the KlineTimestamp instance.
- `__add__(other: timedelta) -> KlineTimestamp`: Adds a `timedelta` to the timestamp, returning a new `KlineTimestamp` instance.
- `__sub__(other: Union[timedelta, KlineTimestamp]) -> Union[KlineTimestamp, timedelta]`: Subtracts a `timedelta` or another `KlineTimestamp` from this instance.
- `next() -> KlineTimestamp`: Returns a new `KlineTimestamp` representing the next kline.
- `prev() -> KlineTimestamp`: Returns a new `KlineTimestamp` representing the previous kline.
- Comparison methods: `__eq__`, `__lt__`, `__le__`, `__gt__`, `__ge__` for comparing klines.
## Example
Here's a complete example demonstrating how to use the `KlineTimestamp` class:
```python
from kline_timestamp import KlineTimestamp
from datetime import timedelta
# Initialize a KlineTimestamp instance
kt = KlineTimestamp(timestamp_ms=1633036800000, interval='1h', tzinfo='Europe/Madrid')
# Print opening and closing timestamps
print(f"Open timestamp (ms): {kt.open}")
print(f"Close timestamp (ms): {kt.close}")
# Convert to datetime and pandas Timestamp
print(f"Datetime: {kt.to_datetime()}")
print(f"Pandas Timestamp: {kt.to_pandas_timestamp()}")
# Update timezone
kt.update_timezone('UTC')
print(f"Updated timezone: {kt.tzinfo}")
print(f"Datetime in UTC: {kt.to_datetime()}")
# Arithmetic operations with timedelta
kt_plus_one_hour = kt + timedelta(hours=1)
print(f"Timestamp after adding 1 hour: {kt_plus_one_hour.to_datetime()}")
kt_minus_one_hour = kt - timedelta(hours=1)
print(f"Timestamp after subtracting 1 hour: {kt_minus_one_hour.to_datetime()}")
# Navigate to next and previous klines
next_kt = kt.next()
prev_kt = kt.prev()
print(f"Next kline datetime: {next_kt.to_datetime()}")
print(f"Previous kline datetime: {prev_kt.to_datetime()}")
# Compare klines
kt_other = KlineTimestamp(timestamp_ms=1633033200000, interval='1h', tzinfo='UTC')
print(f"kt == kt_other: {kt == kt_other}")
print(f"kt > kt_other: {kt > kt_other}")
# Time difference between two klines
time_difference = kt - kt_other
print(f"Time difference: {time_difference}")
```
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
## Author
[nand0san](https://github.com/nand0san)
## Contributing
Contributions are welcome! Please open an issue or submit a pull request on [GitHub](https://github.com/nand0san/KlineTimestamp/tree/github).
## Contact
For any questions or suggestions, please contact using github.
## Acknowledgments
- Inspired by the need for efficient timestamp management in financial data analysis.
- Thanks to the contributors of `pytz` and `pandas` for providing essential tools for timezone and data handling.
Raw data
{
"_id": null,
"home_page": "https://github.com/nand0san/kline_timestamp",
"name": "kline-timestamp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "nand0san",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/3f/9d/94d0f7236bbdf5ecb53112a5c2fa3965f5fd1b03c3e7d4861c2a5ce4cdb8/kline_timestamp-0.1.6.tar.gz",
"platform": null,
"description": "\r\n# KlineTimestamp\r\n\r\nKlineTimestamp is a Python library designed to efficiently handle timestamps within discrete time intervals, commonly known as klines or candlesticks, often used in financial data analysis. This library simplifies the management of Unix timestamps (in milliseconds) for applications that work with time series data, particularly those involving financial market data.\r\n\r\nProject: https://github.com/nand0san/KlineTimestamp/tree/github\r\n\r\n## Features\r\n\r\n- **Calculate Opening and Closing Timestamps**: Easily obtain the opening and closing timestamps of a kline based on specified intervals.\r\n- **Timezone Support**: Handle different timezones with correct Daylight Saving Time (DST) adjustments.\r\n- **Convert to Common Date-Time Objects**: Convert timestamps to `datetime.datetime` and `pandas.Timestamp` objects for seamless integration with other libraries.\r\n- **Arithmetic Operations**: Modify timestamps using `timedelta` objects, and perform arithmetic operations between klines.\r\n- **Navigation Between Klines**: Retrieve the next or previous kline's opening and closing timestamps.\r\n- **Comparison Methods**: Compare klines using standard comparison operators (`==`, `!=`, `<`, `<=`, `>`, `>=`).\r\n- **Robust Equality Checks**: Determine if two klines represent the same time interval, considering interval and timezone.\r\n\r\n## Installation\r\n\r\nInstall the library using `pip`:\r\n\r\n```bash\r\npip install kline_timestamp\r\n```\r\n\r\n## Dependencies\r\n\r\n- Python 3.x\r\n- [`pytz`](https://pypi.org/project/pytz/)\r\n- [`pandas`](https://pypi.org/project/pandas/)\r\n\r\n## Usage\r\n\r\n### Importing the Library\r\n\r\n```python\r\nfrom kline_timestamp import KlineTimestamp\r\nfrom datetime import timedelta\r\n```\r\n\r\n### Creating a KlineTimestamp Instance\r\n\r\n```python\r\n# Create an instance with a specific timestamp, interval, and timezone\r\nkt = KlineTimestamp(timestamp_ms=1633036800000, interval='1h', tzinfo='Europe/Madrid')\r\n```\r\n\r\n### Getting Opening and Closing Timestamps\r\n\r\n```python\r\n# Get the opening timestamp in milliseconds\r\nopen_ts_ms = kt.get_candle_open_timestamp_ms()\r\nprint(f\"Open timestamp (ms): {open_ts_ms}\")\r\n\r\n# Get the closing timestamp in milliseconds\r\nclose_ts_ms = kt.get_candle_close_timestamp_ms()\r\nprint(f\"Close timestamp (ms): {close_ts_ms}\")\r\n\r\n# Access opening and closing timestamps as attributes\r\nprint(f\"Open as attribute: {kt.open}\")\r\nprint(f\"Close as attribute: {kt.close}\")\r\n```\r\n\r\n### Converting to Datetime Objects\r\n\r\n```python\r\n# Convert to datetime in the specified timezone\r\ndt = kt.to_datetime()\r\nprint(f\"Datetime: {dt}\")\r\n\r\n# Convert to pandas Timestamp\r\npd_ts = kt.to_pandas_timestamp()\r\nprint(f\"Pandas Timestamp: {pd_ts}\")\r\n```\r\n\r\n### String Representation\r\n\r\n```python\r\n# String representation of the KlineTimestamp instance\r\nprint(f\"String representation: {str(kt)}\")\r\nprint(f\"Representation: {repr(kt)}\")\r\n```\r\n\r\n### Updating Timezone\r\n\r\n```python\r\n# Update the timezone of the instance\r\nkt.update_timezone('UTC')\r\nprint(f\"Updated timezone: {kt.tzinfo}\")\r\nprint(kt)\r\n```\r\n\r\n### Arithmetic Operations with Timedelta\r\n\r\n```python\r\n# Add a timedelta to the timestamp\r\nkt_added = kt + timedelta(hours=1)\r\nprint(f\"Timestamp after adding 1 hour: {kt_added.to_datetime()}\")\r\n\r\n# Subtract a timedelta from the timestamp\r\nkt_subtracted = kt - timedelta(hours=1)\r\nprint(f\"Timestamp after subtracting 1 hour: {kt_subtracted.to_datetime()}\")\r\n```\r\n\r\n### Subtracting Two KlineTimestamp Instances\r\n\r\n```python\r\n# Create another KlineTimestamp instance\r\nkt_other = KlineTimestamp(timestamp_ms=1633033200000, interval='1h', tzinfo='UTC')\r\n\r\n# Subtract two KlineTimestamp instances to get a timedelta\r\ntime_diff = kt - kt_other\r\nprint(f\"Time difference between kt and kt_other: {time_diff}\")\r\n```\r\n\r\n### Navigating Between Klines\r\n\r\n```python\r\n# Get the next kline\r\nkt_next = kt.next()\r\nprint(f\"Next candle timestamp: {kt_next.to_datetime()}\")\r\n\r\n# Get the previous kline\r\nkt_prev = kt.prev()\r\nprint(f\"Previous candle timestamp: {kt_prev.to_datetime()}\")\r\n```\r\n\r\n### Comparison Methods\r\n\r\n```python\r\n# Compare two KlineTimestamp instances\r\nprint(f\"kt == kt_other: {kt == kt_other}\")\r\nprint(f\"kt > kt_other: {kt > kt_other}\")\r\nprint(f\"kt < kt_other: {kt < kt_other}\")\r\nprint(f\"kt >= kt_other: {kt >= kt_other}\")\r\nprint(f\"kt <= kt_other: {kt <= kt_other}\")\r\n\r\n# Equality with the same parameters\r\nkt_same = KlineTimestamp(timestamp_ms=1633036800000, interval='1h', tzinfo='UTC')\r\nprint(f\"kt == kt_same: {kt == kt_same}\")\r\n```\r\n\r\n## Supported Intervals\r\n\r\nThe following intervals are supported:\r\n\r\n- `'1m'`: 1 minute\r\n- `'3m'`: 3 minutes\r\n- `'5m'`: 5 minutes\r\n- `'15m'`: 15 minutes\r\n- `'30m'`: 30 minutes\r\n- `'1h'`: 1 hour\r\n- `'2h'`: 2 hours\r\n- `'4h'`: 4 hours\r\n- `'6h'`: 6 hours\r\n- `'8h'`: 8 hours\r\n- `'12h'`: 12 hours\r\n- `'1d'`: 1 day\r\n- `'3d'`: 3 days\r\n- `'1w'`: 1 week\r\n\r\n## API Reference\r\n\r\n### Class: `KlineTimestamp`\r\n\r\n#### Initialization\r\n\r\n```python\r\nKlineTimestamp(timestamp_ms: int, interval: str, tzinfo='UTC')\r\n```\r\n\r\n- **Parameters**:\r\n - `timestamp_ms` (int): The timestamp in milliseconds.\r\n - `interval` (str): The interval of the kline. Must be one of the supported intervals.\r\n - `tzinfo` (str or pytz.timezone, optional): The timezone of the timestamp. Defaults to `'UTC'`.\r\n\r\n- **Raises**:\r\n - `ValueError`: If the interval is not valid.\r\n - `TypeError`: If `tzinfo` is neither a string nor a `pytz.timezone` object.\r\n\r\n#### Attributes\r\n\r\n- `timestamp_ms` (int): The original timestamp in milliseconds.\r\n- `interval` (str): The interval of the kline.\r\n- `tzinfo` (`pytz.timezone`): The timezone of the timestamp.\r\n- `open` (int): The opening timestamp of the kline in milliseconds.\r\n- `close` (int): The closing timestamp of the kline in milliseconds.\r\n\r\n#### Methods\r\n\r\n- `get_candle_open_timestamp_ms() -> int`: Returns the opening timestamp of the current kline in milliseconds.\r\n- `get_candle_close_timestamp_ms() -> int`: Returns the closing timestamp of the current kline in milliseconds.\r\n- `to_datetime() -> datetime`: Converts the opening timestamp to a `datetime` object in the specified timezone.\r\n- `to_pandas_timestamp() -> pd.Timestamp`: Converts the opening timestamp to a `pandas.Timestamp` object in the specified timezone.\r\n- `update_timezone(tzinfo: Union[str, pytz.BaseTzInfo]) -> None`: Updates the timezone of the KlineTimestamp instance.\r\n- `__add__(other: timedelta) -> KlineTimestamp`: Adds a `timedelta` to the timestamp, returning a new `KlineTimestamp` instance.\r\n- `__sub__(other: Union[timedelta, KlineTimestamp]) -> Union[KlineTimestamp, timedelta]`: Subtracts a `timedelta` or another `KlineTimestamp` from this instance.\r\n- `next() -> KlineTimestamp`: Returns a new `KlineTimestamp` representing the next kline.\r\n- `prev() -> KlineTimestamp`: Returns a new `KlineTimestamp` representing the previous kline.\r\n- Comparison methods: `__eq__`, `__lt__`, `__le__`, `__gt__`, `__ge__` for comparing klines.\r\n\r\n## Example\r\n\r\nHere's a complete example demonstrating how to use the `KlineTimestamp` class:\r\n\r\n```python\r\nfrom kline_timestamp import KlineTimestamp\r\nfrom datetime import timedelta\r\n\r\n# Initialize a KlineTimestamp instance\r\nkt = KlineTimestamp(timestamp_ms=1633036800000, interval='1h', tzinfo='Europe/Madrid')\r\n\r\n# Print opening and closing timestamps\r\nprint(f\"Open timestamp (ms): {kt.open}\")\r\nprint(f\"Close timestamp (ms): {kt.close}\")\r\n\r\n# Convert to datetime and pandas Timestamp\r\nprint(f\"Datetime: {kt.to_datetime()}\")\r\nprint(f\"Pandas Timestamp: {kt.to_pandas_timestamp()}\")\r\n\r\n# Update timezone\r\nkt.update_timezone('UTC')\r\nprint(f\"Updated timezone: {kt.tzinfo}\")\r\nprint(f\"Datetime in UTC: {kt.to_datetime()}\")\r\n\r\n# Arithmetic operations with timedelta\r\nkt_plus_one_hour = kt + timedelta(hours=1)\r\nprint(f\"Timestamp after adding 1 hour: {kt_plus_one_hour.to_datetime()}\")\r\n\r\nkt_minus_one_hour = kt - timedelta(hours=1)\r\nprint(f\"Timestamp after subtracting 1 hour: {kt_minus_one_hour.to_datetime()}\")\r\n\r\n# Navigate to next and previous klines\r\nnext_kt = kt.next()\r\nprev_kt = kt.prev()\r\nprint(f\"Next kline datetime: {next_kt.to_datetime()}\")\r\nprint(f\"Previous kline datetime: {prev_kt.to_datetime()}\")\r\n\r\n# Compare klines\r\nkt_other = KlineTimestamp(timestamp_ms=1633033200000, interval='1h', tzinfo='UTC')\r\nprint(f\"kt == kt_other: {kt == kt_other}\")\r\nprint(f\"kt > kt_other: {kt > kt_other}\")\r\n\r\n# Time difference between two klines\r\ntime_difference = kt - kt_other\r\nprint(f\"Time difference: {time_difference}\")\r\n```\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\r\n\r\n## Author\r\n\r\n[nand0san](https://github.com/nand0san)\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please open an issue or submit a pull request on [GitHub](https://github.com/nand0san/KlineTimestamp/tree/github).\r\n\r\n## Contact\r\n\r\nFor any questions or suggestions, please contact using github.\r\n\r\n## Acknowledgments\r\n\r\n- Inspired by the need for efficient timestamp management in financial data analysis.\r\n- Thanks to the contributors of `pytz` and `pandas` for providing essential tools for timezone and data handling.\r\n",
"bugtrack_url": null,
"license": null,
"summary": "KlineTimestamp is a Python library designed to efficiently handle timestamps within discrete time intervals, commonly known as klines or candlesticks, often used in financial data analysis.",
"version": "0.1.6",
"project_urls": {
"Homepage": "https://github.com/nand0san/kline_timestamp"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3f9d94d0f7236bbdf5ecb53112a5c2fa3965f5fd1b03c3e7d4861c2a5ce4cdb8",
"md5": "1cf5562bf8ef24d33acde4c845efb45e",
"sha256": "9e4670cd9840ad993b149ae31f7ac0c418876e6a7a724e27fbfe524f1fc7aac2"
},
"downloads": -1,
"filename": "kline_timestamp-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "1cf5562bf8ef24d33acde4c845efb45e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 7143,
"upload_time": "2024-10-20T18:37:59",
"upload_time_iso_8601": "2024-10-20T18:37:59.405952Z",
"url": "https://files.pythonhosted.org/packages/3f/9d/94d0f7236bbdf5ecb53112a5c2fa3965f5fd1b03c3e7d4861c2a5ce4cdb8/kline_timestamp-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-20 18:37:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nand0san",
"github_project": "kline_timestamp",
"github_not_found": true,
"lcname": "kline-timestamp"
}
