evdsts 0.1.0__tar.gz

evdsts-0.1.0/.gitignore

@@ -0,0 +1,93 @@
+# Project
+**/test.py
+**/evds_series_references.json
+**/evds_api_key.json
+
+
+# VS Code
+.vscode/**/*
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.pixi/*
+!.pixi/config.toml
+pixi.lock
+uv.lock
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+

evdsts-0.1.0/LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2022 Burak ÇELİK
+
+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.

evdsts-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: evdsts
+Version: 0.1.0
+Summary: A Python implementation for retrieving and transforming macroeconomic time series data from TCMB EVDS (CBRT EDDS) API.
+Project-URL: Homepage, https://github.com/syncoding/evdsts
+Project-URL: Documentation, https://github.com/syncoding/evdsts/blob/master/README_EN.md
+Project-URL: Repository, https://github.com/syncoding/evdsts.git
+Project-URL: Issues, https://github.com/syncoding/evdsts/issues
+Project-URL: Changelog, https://github.com/syncoding/evdsts/blob/master/CHANGELOG.md
+Author-email: Burak CELIK <synertic@gmail.com>
+Maintainer-email: syncoding <synertic@gmail.com>
+License-Expression: MIT
+License-File: LICENSE.txt
+Keywords: cbot,econometrics,edds,evds,macroeconomics,tcmb
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Natural Language :: Turkish
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.13
+Requires-Dist: pandas>=3.0.0
+Requires-Dist: requests>=2.32.5
+Requires-Dist: tqdm>=4.67.3
+Provides-Extra: excel
+Requires-Dist: openpyxl; extra == 'excel'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://github.com/syncoding/evdsts/blob/master/docs/images/evdsts.png?raw=true" width="120"/>
+</p>
+
+<h1 align="center">evdsts</h1>
+
+<p align="center">
+  <strong>Macroeconomic time series toolkit for TCMB EVDS (CBRT EDDS)</strong>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/evdsts/"><img src="https://badge.fury.io/py/evdsts.svg" alt="PyPI version"></a>
+  <a href="https://pypistats.org/packages/evdsts"><img src="https://img.shields.io/pypi/dm/evdsts" alt="Downloads"></a>
+  <a href="https://pypi.org/project/evdsts/"><img src="https://img.shields.io/pypi/pyversions/evdsts" alt="Python Version"></a>
+  <a href="https://pypi.org/project/evdsts/"><img src="https://img.shields.io/pypi/status/evdsts" alt="Status"></a>
+  <a href="https://github.com/syncoding/evdsts/blob/master/LICENSE.txt"><img src="https://img.shields.io/github/license/syncoding/evdsts" alt="License"></a>
+  <a href="https://github.com/syncoding/evdsts/issues"><img src="https://img.shields.io/github/issues-raw/syncoding/evdsts" alt="Issues"></a>
+  <a href="https://github.com/syncoding/evdsts"><img src="https://img.shields.io/github/languages/top/syncoding/evdsts" alt="Top Language"></a>
+  <a href="https://github.com/syncoding/evdsts"><img src="https://img.shields.io/github/forks/syncoding/evdsts?style=social" alt="Forks"></a>
+</p>
+
+---
+
+## The Purpose
+
+`evdsts` is a Python implementation for retrieving and transforming macroeconomic time series data from
+**The Central Bank of Republic of Turkiye** **Electronic Data Delivery System** **(EDDS)** API.
+`evdsts` is designed for making both data retrieving and also time series analysis easy thanks to its
+time series analysis ready outputs and other useful transformations.
+
+## Overview
+
+`evdsts` is mainly designed for preparing the time series analysis ready datasets from the data
+retrieved from **EDDS**. `evdsts` both makes the data retrieving easy and also allows you to start
+working on data instantly with its advanced features that gives you complete control over the
+retrieved data.
+
+`evdsts` is consisted of two important classes:
+
+| Class | Responsibility |
+|:------|:---------------|
+| **Connector** | Connecting to EDDS, data retrieving, data renaming, etc. |
+| **Transformator** | Co-integrated transformations such as z-score, dummies, outliers, differencing and more. |
+
+### Key Features
+
+- **In-situ search** -- search series by keywords without leaving Python; results are instant and local.
+- **Analysis-ready outputs** -- every returned value is guaranteed to be a proper numeric or datetime type, never a raw string.
+- **Auto time-series indexing** -- retrieved data are converted to real pandas DatetimeIndex series automatically (optional).
+- **Reference names** -- assign memorable aliases like `usdtry` or `cppi` to complex EDDS codes; aliases are permanent and portable across projects.
+- **Human-readable parameters** -- use `daily`, `quarterly`, `percent`, `diff`, `max` instead of cryptic API codes.
+- **Pre-flight validation** -- many parameter errors are caught before any network request is made.
+- **Extended transformations** -- log-returns, higher-order differences and other operations not natively supported by the API.
+- **Flexible output** -- get results as `DataFrame`, `JSON` or `dict`; write to disk as CSV, JSON or XLS.
+- **CLI support** -- rebuild search indexes from the command line with `evdsts build-index`.
+- **Fully annotated** -- type hints and docstrings everywhere for IDE autocompletion and quick help.
+
+## Quick Start
+
+```python
+from evdsts import Connector
+
+connector = Connector("YOUR_API_KEY", language="EN")
+
+# search for a series
+connector.where("consumer price index")
+
+# retrieve data
+cpi = connector.get_series("TP.FE.OKTG01", start_date="01.01.2020")
+
+# retrieve multiple series
+rates = connector.get_series(
+    "TP.DK.USD.A.YTL, TP.DK.EUR.A.YTL",
+    start_date="01.01.2023",
+    frequency="M",
+    transformations="percent",
+)
+```
+
+## CLI Usage
+
+```bash
+# rebuild the search index
+evdsts build-index --language ENG -y
+
+# see all options
+evdsts build-index --help
+```
+
+## Documentation
+
+Please see [**THE USER MANUAL**](https://github.com/syncoding/evdsts/blob/master/docs/manuals/manual_en.md) for detailed explanations about how to get an API key from the EDDS and use `evdsts`.
+
+## Examples [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/syncoding/evdsts/blob/master/examples/examples.ipynb)
+
+Download the [**Jupyter Notebook Application**](https://github.com/syncoding/evdsts/blob/master/examples) that covers the main use cases of `evdsts`,
+or alternatively open it on **Google Colab** by clicking the *Open in Colab* badge above.
+
+## Installation
+
+Stable version of `evdsts` is available on GitHub, PyPI and conda-forge.
+
+```bash
+# PyPI
+pip install evdsts
+
+# GitHub
+pip install git+https://github.com/syncoding/evdsts.git
+
+# Conda
+conda install evdsts -c conda-forge
+```
+
+## Dependencies
+
+| Package | Version |
+|:--------|:--------|
+| Python | >= 3.11 |
+| pandas | >= 3.0.0 |
+| requests | >= 2.32.5 |
+| tqdm | >= 4.67.3 |
+
+> [openpyxl](https://pypi.org/project/openpyxl/) is additionally required if you want to write data in MS Excel format.
+
+## Links
+
+| | |
+|:--|:--|
+| Source Code | [GitHub](https://github.com/syncoding/evdsts/blob/master/evdsts) |
+| Changelog | [CHANGELOG.md](https://github.com/syncoding/evdsts/blob/master/CHANGELOG.md) |
+| License | [MIT](https://github.com/syncoding/evdsts/blob/master/LICENSE.txt) |
+
+## Contact
+
+<a href="mailto:synertic@gmail.com?"><img src="https://img.shields.io/badge/gmail-%23DD0031.svg?&style=for-the-badge&logo=gmail&logoColor=white"/></a>

evdsts-0.1.0/README_EN.md

@@ -0,0 +1,135 @@
+<p align="center">
+  <img src="https://github.com/syncoding/evdsts/blob/master/docs/images/evdsts.png?raw=true" width="120"/>
+</p>
+
+<h1 align="center">evdsts</h1>
+
+<p align="center">
+  <strong>Macroeconomic time series toolkit for TCMB EVDS (CBRT EDDS)</strong>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/evdsts/"><img src="https://badge.fury.io/py/evdsts.svg" alt="PyPI version"></a>
+  <a href="https://pypistats.org/packages/evdsts"><img src="https://img.shields.io/pypi/dm/evdsts" alt="Downloads"></a>
+  <a href="https://pypi.org/project/evdsts/"><img src="https://img.shields.io/pypi/pyversions/evdsts" alt="Python Version"></a>
+  <a href="https://pypi.org/project/evdsts/"><img src="https://img.shields.io/pypi/status/evdsts" alt="Status"></a>
+  <a href="https://github.com/syncoding/evdsts/blob/master/LICENSE.txt"><img src="https://img.shields.io/github/license/syncoding/evdsts" alt="License"></a>
+  <a href="https://github.com/syncoding/evdsts/issues"><img src="https://img.shields.io/github/issues-raw/syncoding/evdsts" alt="Issues"></a>
+  <a href="https://github.com/syncoding/evdsts"><img src="https://img.shields.io/github/languages/top/syncoding/evdsts" alt="Top Language"></a>
+  <a href="https://github.com/syncoding/evdsts"><img src="https://img.shields.io/github/forks/syncoding/evdsts?style=social" alt="Forks"></a>
+</p>
+
+---
+
+## The Purpose
+
+`evdsts` is a Python implementation for retrieving and transforming macroeconomic time series data from
+**The Central Bank of Republic of Turkiye** **Electronic Data Delivery System** **(EDDS)** API.
+`evdsts` is designed for making both data retrieving and also time series analysis easy thanks to its
+time series analysis ready outputs and other useful transformations.
+
+## Overview
+
+`evdsts` is mainly designed for preparing the time series analysis ready datasets from the data
+retrieved from **EDDS**. `evdsts` both makes the data retrieving easy and also allows you to start
+working on data instantly with its advanced features that gives you complete control over the
+retrieved data.
+
+`evdsts` is consisted of two important classes:
+
+| Class | Responsibility |
+|:------|:---------------|
+| **Connector** | Connecting to EDDS, data retrieving, data renaming, etc. |
+| **Transformator** | Co-integrated transformations such as z-score, dummies, outliers, differencing and more. |
+
+### Key Features
+
+- **In-situ search** -- search series by keywords without leaving Python; results are instant and local.
+- **Analysis-ready outputs** -- every returned value is guaranteed to be a proper numeric or datetime type, never a raw string.
+- **Auto time-series indexing** -- retrieved data are converted to real pandas DatetimeIndex series automatically (optional).
+- **Reference names** -- assign memorable aliases like `usdtry` or `cppi` to complex EDDS codes; aliases are permanent and portable across projects.
+- **Human-readable parameters** -- use `daily`, `quarterly`, `percent`, `diff`, `max` instead of cryptic API codes.
+- **Pre-flight validation** -- many parameter errors are caught before any network request is made.
+- **Extended transformations** -- log-returns, higher-order differences and other operations not natively supported by the API.
+- **Flexible output** -- get results as `DataFrame`, `JSON` or `dict`; write to disk as CSV, JSON or XLS.
+- **CLI support** -- rebuild search indexes from the command line with `evdsts build-index`.
+- **Fully annotated** -- type hints and docstrings everywhere for IDE autocompletion and quick help.
+
+## Quick Start
+
+```python
+from evdsts import Connector
+
+connector = Connector("YOUR_API_KEY", language="EN")
+
+# search for a series
+connector.where("consumer price index")
+
+# retrieve data
+cpi = connector.get_series("TP.FE.OKTG01", start_date="01.01.2020")
+
+# retrieve multiple series
+rates = connector.get_series(
+    "TP.DK.USD.A.YTL, TP.DK.EUR.A.YTL",
+    start_date="01.01.2023",
+    frequency="M",
+    transformations="percent",
+)
+```
+
+## CLI Usage
+
+```bash
+# rebuild the search index
+evdsts build-index --language ENG -y
+
+# see all options
+evdsts build-index --help
+```
+
+## Documentation
+
+Please see [**THE USER MANUAL**](https://github.com/syncoding/evdsts/blob/master/docs/manuals/manual_en.md) for detailed explanations about how to get an API key from the EDDS and use `evdsts`.
+
+## Examples [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/syncoding/evdsts/blob/master/examples/examples.ipynb)
+
+Download the [**Jupyter Notebook Application**](https://github.com/syncoding/evdsts/blob/master/examples) that covers the main use cases of `evdsts`,
+or alternatively open it on **Google Colab** by clicking the *Open in Colab* badge above.
+
+## Installation
+
+Stable version of `evdsts` is available on GitHub, PyPI and conda-forge.
+
+```bash
+# PyPI
+pip install evdsts
+
+# GitHub
+pip install git+https://github.com/syncoding/evdsts.git
+
+# Conda
+conda install evdsts -c conda-forge
+```
+
+## Dependencies
+
+| Package | Version |
+|:--------|:--------|
+| Python | >= 3.11 |
+| pandas | >= 3.0.0 |
+| requests | >= 2.32.5 |
+| tqdm | >= 4.67.3 |
+
+> [openpyxl](https://pypi.org/project/openpyxl/) is additionally required if you want to write data in MS Excel format.
+
+## Links
+
+| | |
+|:--|:--|
+| Source Code | [GitHub](https://github.com/syncoding/evdsts/blob/master/evdsts) |
+| Changelog | [CHANGELOG.md](https://github.com/syncoding/evdsts/blob/master/CHANGELOG.md) |
+| License | [MIT](https://github.com/syncoding/evdsts/blob/master/LICENSE.txt) |
+
+## Contact
+
+<a href="mailto:synertic@gmail.com?"><img src="https://img.shields.io/badge/gmail-%23DD0031.svg?&style=for-the-badge&logo=gmail&logoColor=white"/></a>

evdsts-0.1.0/evdsts/__init__.py

@@ -0,0 +1,3 @@
+from evdsts.base.connecting import Connector
+from evdsts.base.indexing import IndexBuilder
+from evdsts.base.transforming import Transformator