dukascript 0.0.3__py3-none-any.whl → 0.0.5__py3-none-any.whl

dukascript/__init__.py

@@ -31,19 +31,19 @@ INTERVAL_SEC_1 = f"1{TIME_UNIT_SEC}"
 INTERVAL_TICK = TIME_UNIT_TICK
 
 _interval_units = {
-    INTERVAL_MONTH_1:TIME_UNIT_MONTH,
-    INTERVAL_WEEK_1:TIME_UNIT_WEEK,
-    INTERVAL_DAY_1:TIME_UNIT_DAY,
-    INTERVAL_HOUR_4:TIME_UNIT_HOUR,
-    INTERVAL_HOUR_1:TIME_UNIT_HOUR,
-    INTERVAL_MIN_30:TIME_UNIT_MIN,
-    INTERVAL_MIN_15:TIME_UNIT_MIN,
-    INTERVAL_MIN_10:TIME_UNIT_MIN,
-    INTERVAL_MIN_5:TIME_UNIT_MIN,
-    INTERVAL_MIN_1:TIME_UNIT_MIN,
-    INTERVAL_SEC_30:TIME_UNIT_SEC,
-    INTERVAL_SEC_10:TIME_UNIT_SEC,
-    INTERVAL_SEC_1:TIME_UNIT_SEC,
+    INTERVAL_MONTH_1: TIME_UNIT_MONTH,
+    INTERVAL_WEEK_1: TIME_UNIT_WEEK,
+    INTERVAL_DAY_1: TIME_UNIT_DAY,
+    INTERVAL_HOUR_4: TIME_UNIT_HOUR,
+    INTERVAL_HOUR_1: TIME_UNIT_HOUR,
+    INTERVAL_MIN_30: TIME_UNIT_MIN,
+    INTERVAL_MIN_15: TIME_UNIT_MIN,
+    INTERVAL_MIN_10: TIME_UNIT_MIN,
+    INTERVAL_MIN_5: TIME_UNIT_MIN,
+    INTERVAL_MIN_1: TIME_UNIT_MIN,
+    INTERVAL_SEC_30: TIME_UNIT_SEC,
+    INTERVAL_SEC_10: TIME_UNIT_SEC,
+    INTERVAL_SEC_1: TIME_UNIT_SEC,
 }
 
 OFFER_SIDE_BID = "B"
@@ -258,7 +258,7 @@ def fetch(
     debug=False,
 ):
     logger = _get_custom_logger(debug)
-    time_unit=_interval_units[interval]
+    time_unit = _interval_units[interval]
     columns = _get_dataframe_columns_for_timeunit(time_unit)
 
     data = []
@@ -299,6 +299,7 @@ def live_fetch(
     debug=False,
 ):
     logger = _get_custom_logger(debug)
+    assert interval_value > 0
 
     # validate time unit
     _resample_to_nearest(
@@ -343,7 +344,9 @@ def live_fetch(
 
     yield df
 
-    for row in datafeed:
+    last_tick_count = 0
+
+    for tick_count, row in enumerate(datafeed, 0):
 
         timestamp = _resample_to_nearest(
             pd.to_datetime(
@@ -355,19 +358,24 @@ def live_fetch(
             interval_value,
         )
 
-        if time_unit == TIME_UNIT_TICK:
+        if last_timestamp == None:
+            last_timestamp = timestamp.timestamp()
+
+        if time_unit == TIME_UNIT_TICK and interval_value == 1:
             df.loc[timestamp] = [
                 *row[1:],
             ]
             yield df
             continue
 
-        if last_timestamp == None:
-            last_timestamp = timestamp.timestamp()
+        new_tick_count = tick_count // interval_value
 
-        if timestamp.timestamp() != last_timestamp:
+        if (
+            time_unit != TIME_UNIT_TICK
+            and timestamp.timestamp() != last_timestamp.timestamp()
+        ) or (time_unit == TIME_UNIT_TICK and last_tick_count != new_tick_count):
             if open is not None:
-                df.loc[timestamp] = [
+                df.loc[last_timestamp] = [
                     open,
                     high,
                     low,
@@ -376,7 +384,8 @@ def live_fetch(
                 ]
 
                 yield df
-            last_timestamp = timestamp.timestamp()
+            last_timestamp = timestamp
+            last_tick_count = new_tick_count
             open = None
 
         if open is None:
@@ -398,4 +407,5 @@ def live_fetch(
             close,
             volume,
         ]
+        
         yield df

dukascript-0.0.5.dist-info/METADATA

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: dukascript
+Version: 0.0.5
+Summary: Download tick data from Dukascopy Bank SA to local cache, and simulate time-ordered price streams
+Author-email: Eghosa Osayande <osayandeeghosam@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2024 drui9
+        
+        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.
+Project-URL: Homepage, https://github.com/Eghosa-Osayande/dukascript
+Keywords: tick-data,forex-data,tick-api,ticks,dukascopy
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas
+Requires-Dist: requests
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# 🏦 dukascript
+
+Download and stream historical price data for variety of financial instruments (e.g. Forex, Commodities and Indices) from Dukascopy Bank SA. , including support for tick-level and aggregated intervals.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install dukascript
+```
+
+---
+
+## 🛠️ Usage
+
+### Importing
+
+```python
+from datetime import datetime, timedelta
+import dukascript
+from dukascript.instruments import INSTRUMENT_FX_MAJORS_GBP_USD
+```
+
+---
+
+## 🧠 Key Concepts
+
+Both `fetch` and `live_fetch` share similar parameters:
+
+| Parameter      | Description                                                                 |
+|----------------|-----------------------------------------------------------------------------|
+| `start`        | `datetime`, required. The start time of the data.                           |
+| `end`          | `datetime`, optional. If `None`, fetches data up to "now".                  |
+| `instrument`   | e.g., `INSTRUMENT_FX_MAJORS_GBP_USD`.                                       |
+| `offer_side`   | `OFFER_SIDE_BID` or `OFFER_SIDE_ASK`.                                       |
+| `max_retries`  | Optional. If `None`, keeps retrying on failure.                             |
+| `debug`        | Optional. If `True`, prints debug logs.                                     |
+
+### 🧊 `fetch()` only:
+
+| Parameter    | Description                  |
+|--------------|------------------------------|
+| `interval`   | e.g., `INTERVAL_HOUR_1`      |
+
+### 🔥 `live_fetch()` only:
+
+| Parameter         | Description                                 |
+|-------------------|---------------------------------------------|
+| `interval_value`  | e.g., `1`                                    |
+| `time_unit`       | e.g., `dukascript.TIME_UNIT_HOUR`           |
+
+---
+
+## 📝 Notes
+
+- **fetch**: Fetches static historical data. Returns **one** `DataFrame`.
+- **live_fetch**: Continuously fetches live updates. Returns a **generator** that yields the **same `DataFrame`** with updated data.
+
+When using intervals not based on ticks eg: `1HOUR`, `fetch()` will return delayed data. For up-to-date values, use `live_fetch()` which fetches tick data under the hood and reshapes it based on the `interval_value` and `time_unit`.
+
+---
+
+## 📊 DataFrame Columns
+
+### When interval/time_unit is based on tick:
+ie:
+
+`interval = INTERVAL_TICK`
+
+or
+
+`interval_value = 1`
+`time_units = TIME_UNIT_TICK`
+
+| Column      | Description            |
+|-------------|------------------------|
+| `timestamp` | UTC datetime, Dataframe Index |
+| `bidPrice`  | Bid price              |
+| `askPrice`  | Ask price              |
+| `bidVolume` | Bid volume             |
+| `askVolume` | Ask volume             |
+
+### When interval/time_unit is NOT based on tick
+eg: 5 minutes OHLC candle data
+
+`interval_value = 5`
+`time_units = TIME_UNIT_MIN`
+
+| Column      | Description            |
+|-------------|------------------------|
+| `timestamp` | UTC datetime, Dataframe Index |
+| `open`      | Opening price          |
+| `high`      | Highest price          |
+| `low`       | Lowest price           |
+| `close`     | Closing price          |
+| `volume`    | Volume (in units)      |
+
+---
+
+## 💾 Saving Results
+
+Use built-in `pandas` methods to export:
+
+```python
+df.to_csv("data.csv")
+df.to_excel("data.xlsx")
+df.to_json("data.json")
+```
+
+---
+
+## 🚀 Examples
+
+### Example 1: Fetch Historical Data
+
+```python
+start = datetime(2025, 1, 1)
+end = datetime(2025, 2, 1)
+instrument = INSTRUMENT_FX_MAJORS_GBP_USD
+interval = dukascript.INTERVAL_HOUR_1
+offer_side = dukascript.OFFER_SIDE_BID
+
+df = dukascript.fetch(
+    instrument,
+    interval,
+    offer_side,
+    start,
+    end,
+)
+
+df.to_json("output.json")
+```
+
+---
+
+### Example 2: Live Fetch with End Time
+
+```python
+now = datetime.now()
+start = datetime(now.year, now.month, now.day)
+end = start + timedelta(hours=24)
+
+iterator = dukascript.live_fetch(
+    instrument,
+    1,
+    dukascript.TIME_UNIT_HOUR,
+    offer_side,
+    start,
+    end,
+)
+
+for df in iterator:
+    pass
+
+df.to_csv("output.csv")
+```
+
+---
+
+### Example 3: Live Fetch Indefinitely (End = None)
+
+```python
+now = datetime.now()
+start = datetime(now.year, now.month, now.day)
+end = None
+
+df_iterator = dukascript.live_fetch(
+    instrument,
+    1,
+    dukascript.TIME_UNIT_HOUR,
+    offer_side,
+    start,
+    end,
+)
+
+for df in df_iterator:
+    # Do something with latest data
+    pass
+```
+
+---
+
+## 📄 License
+
+MIT
+
+---
+
+## 👋 Contributing
+
+Pull requests and suggestions are highly welcome!
+

dukascript-0.0.5.dist-info/RECORD

@@ -0,0 +1,8 @@
+dukascript/__init__.py,sha256=nxyrT1UGi2gBpRGsUMnZA2koMMnTwq7EZdoY_vq5J6E,11785
+dukascript/_instrument_generator.py,sha256=WDTNS1bLa-J2uI3TmoBTg-WCHdAtkX6d6tq0xhqL4GI,24848
+dukascript/instruments.py,sha256=OxKTWR8zx2sjaHtGtd81FsQwTdAMItjgUSojzuJ1waI,59069
+dukascript-0.0.5.dist-info/licenses/LICENSE,sha256=SA8D35cWkNTiEI71ATLBPTzWgFwjPNZLeloeBJrAJr4,1061
+dukascript-0.0.5.dist-info/METADATA,sha256=5h8k2mjIMRIZ2ARrs3bTod5VDXjT9Qh2DSwZadU8WQM,6484
+dukascript-0.0.5.dist-info/WHEEL,sha256=pxyMxgL8-pra_rKaQ4drOZAegBVuX-G_4nRHjjgWbmo,91
+dukascript-0.0.5.dist-info/top_level.txt,sha256=h7GgEQykn3TuhHU4jJxZQ7oNjP_naNvjUwZAw6KU3VE,11
+dukascript-0.0.5.dist-info/RECORD,,

dukascript-0.0.3.dist-info/METADATA

@@ -1,44 +0,0 @@
-Metadata-Version: 2.4
-Name: dukascript
-Version: 0.0.3
-Summary: Download tick data from Dukascopy Bank SA to local cache, and simulate time-ordered price streams
-Author-email: Eghosa Osayande <osayandeeghosam@gmail.com>
-License: MIT License
-        
-        Copyright (c) 2024 drui9
-        
-        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.
-Project-URL: Homepage, https://github.com/Eghosa-Osayande/dukascript
-Keywords: tick-data,forex-data,tick-api,ticks,dukascopy
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: pandas
-Requires-Dist: requests
-Provides-Extra: dev
-Requires-Dist: build; extra == "dev"
-Requires-Dist: twine; extra == "dev"
-Dynamic: license-file
-
-# dukascript
-
-Download and stream historical data from Dukascopy Bank SA.

dukascript-0.0.3.dist-info/RECORD

@@ -1,8 +0,0 @@
-dukascript/__init__.py,sha256=bPsw_EhL1g35ulDZLWuIZO3ueHncS-7dQ5AFvyT84nw,11412
-dukascript/_instrument_generator.py,sha256=WDTNS1bLa-J2uI3TmoBTg-WCHdAtkX6d6tq0xhqL4GI,24848
-dukascript/instruments.py,sha256=OxKTWR8zx2sjaHtGtd81FsQwTdAMItjgUSojzuJ1waI,59069
-dukascript-0.0.3.dist-info/licenses/LICENSE,sha256=SA8D35cWkNTiEI71ATLBPTzWgFwjPNZLeloeBJrAJr4,1061
-dukascript-0.0.3.dist-info/METADATA,sha256=uXCFZcjUOto7W_cJ1hTi28Y81S-jXxcCk5ks9pOfkPY,2040
-dukascript-0.0.3.dist-info/WHEEL,sha256=pxyMxgL8-pra_rKaQ4drOZAegBVuX-G_4nRHjjgWbmo,91
-dukascript-0.0.3.dist-info/top_level.txt,sha256=h7GgEQykn3TuhHU4jJxZQ7oNjP_naNvjUwZAw6KU3VE,11
-dukascript-0.0.3.dist-info/RECORD,,