From a4592b6c004130771686d1834365d1c0fa3c2305 Mon Sep 17 00:00:00 2001 From: Sermet Pekin Date: Mon, 5 Aug 2024 13:22:22 +0300 Subject: [PATCH] docs --- docs/source/conf.py | 60 ++++++++++++------------ docs/source/examples.rst | 3 ++ docs/source/home.rst | 91 ++++++++++++++++++++---------------- docs/source/homeEski.EEErst | 93 +++++++++++++++++++++++++++++++++++++ docs/source/proxy.rst | 22 ++------- 5 files changed, 183 insertions(+), 86 deletions(-) create mode 100644 docs/source/examples.rst create mode 100644 docs/source/homeEski.EEErst diff --git a/docs/source/conf.py b/docs/source/conf.py index c3127d8..f1f8f8a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -8,33 +8,33 @@ from sphinx.util import logging import os -html_build_dir = '../docs' # Directory for HTML build output +html_build_dir = "../docs" # Directory for HTML build output -project = 'evdspy' -copyright = '2024, Sermet Pekin' -author = 'Sermet Pekin' +project = "evdspy" +copyright = "2024, Sermet Pekin" +author = "Sermet Pekin" # The short X.Y version -version = '' +version = "" # The full version, including alpha/beta/rc tags -release = '' +release = "" # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.doctest', - 'sphinx.ext.intersphinx', - 'sphinx.ext.todo', - 'sphinx.ext.ifconfig', - 'sphinx.ext.viewcode', - 'sphinx.ext.inheritance_diagram', - 'sphinx.ext.autosummary', + "sphinx.ext.autodoc", + "sphinx.ext.doctest", + "sphinx.ext.intersphinx", + "sphinx.ext.todo", + "sphinx.ext.ifconfig", + "sphinx.ext.viewcode", + "sphinx.ext.inheritance_diagram", + "sphinx.ext.autosummary", # 'myst_parser' # Uncomment if you use MyST markdown ] -templates_path = ['_templates'] +templates_path = ["_templates"] exclude_patterns = [] doctest_global_setup = """ @@ -42,23 +42,24 @@ """ # Disable execution of doctest blocks -doctest_test_doctest_blocks = 'false' +doctest_test_doctest_blocks = "false" # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -# <<<<<<< HEAD -html_theme = 'sphinx_book_theme' # Theme for HTML output -html_static_path = ['_static'] # Static files path -#======= -#html_static_path = ['static'] -os.makedirs(html_static_path[0]) -#>>>>>>> f106125c794f7eeb8348e421c7d0ba4b3edee5e1 +html_theme = "sphinx_book_theme" # Theme for HTML output +html_static_path = ["_static"] # Static files path + +try: + os.makedirs(html_static_path[0]) +except: + pass + source_suffix = { - '.rst': 'restructuredtext', - '.txt': 'markdown', - '.md': 'markdown', + ".rst": "restructuredtext", + ".txt": "markdown", + ".md": "markdown", } @@ -66,14 +67,15 @@ logger = logging.getLogger(__name__) + def linkcode_resolve(domain, info): """ Resolve the link to the source code for documentation. """ print(domain, info, "Domain info ") - if domain != 'py': + if domain != "py": return None - if not info['module']: + if not info["module"]: return None - filename = info['module'].replace('.', '/') + filename = info["module"].replace(".", "/") return f"https://github.com/SermetPekin/evdspy-repo/{filename}.py" diff --git a/docs/source/examples.rst b/docs/source/examples.rst new file mode 100644 index 0000000..bcc2c96 --- /dev/null +++ b/docs/source/examples.rst @@ -0,0 +1,3 @@ +Examples +==================== +The ``save`` function is designed to save an API key into your application's configuration or a designated storage mechanism. It ensures the API key is valid and prompts the user for input if the provided key is not valid or if no key is provided. diff --git a/docs/source/home.rst b/docs/source/home.rst index 874ff7e..6ef3ee9 100644 --- a/docs/source/home.rst +++ b/docs/source/home.rst @@ -1,6 +1,6 @@ - Introduction =============================== + .. image:: https://github.com/SermetPekin/evdspy-repo/actions/workflows/python-package.yml/badge.svg :target: https://github.com/SermetPekin/evdspy-repo/actions/workflows/python-package.yml .. image:: https://img.shields.io/pypi/v/evdspy @@ -10,7 +10,7 @@ Introduction .. image:: https://pepy.tech/badge/evdspy/week :target: https://pepy.tech/project/evdspy -evdspy is an open-source Python interface that simplifies making requests to the Central Bank of the Republic of Turkey (CBRT) Economic Data Service (EDS). It provides efficient request handling by caching results, a user-friendly menu for data inquiries, and capabilities for handling complex data structures through an accessible API. +evdspy is an open-source Python interface that simplifies making requests to the Central Bank of the Republic of Turkey (CBRT) Electronic Data Delivery System (EVDS). It provides efficient request handling by caching results, a user-friendly menu for data inquiries, and capabilities for handling complex data structures through an accessible API. View Source Code ---------------- @@ -18,35 +18,57 @@ You can view the source code for this project on GitHub: `View Source `_ + + +.. image:: https://github.com/user-attachments/assets/14024132-4d41-4879-9ea8-3e510b2f8f02 + :target: https://evdspychat.onrender.com/ + + + -#### evdspyChat application was added. -Api Key is not required for only evdspy documentation related questions. -[evdspyChat](https://evdspychat-b11f96868cb6.herokuapp.com/) +.. image:: https://github.com/user-attachments/assets/14024132-4d41-4879-9ea8-3e510b2f8f02 + :target: https://evdspychat.onrender.com/ + + + +.. image:: https://github.com/user-attachments/assets/2cece3e0-958a-454b-8876-5dbdfea1e1a4 + :target: https://evdspychat.onrender.com/ + +.. image:: https://github.com/user-attachments/assets/3e5d3ab4-df41-4d34-8e2a-e1ca3d19a190 + :target: https://evdspychat.onrender.com/ + + +.. image:: https://github.com/user-attachments/assets/3e5d3ab4-df41-4d34-8e2a-e1ca3d19a190 + :target: https://evdspychat.onrender.com/ - [![tellme](https://github.com/user-attachments/assets/14024132-4d41-4879-9ea8-3e510b2f8f02)](https://evdspychat-b11f96868cb6.herokuapp.com/) - -[![askyourself](https://github.com/user-attachments/assets/2cece3e0-958a-454b-8876-5dbdfea1e1a4)](https://evdspychat-b11f96868cb6.herokuapp.com/) -[![a2](https://github.com/user-attachments/assets/3e5d3ab4-df41-4d34-8e2a-e1ca3d19a190)](https://evdspychat-b11f96868cb6.herokuapp.com/) Key Features ------------ - **API Key Management**: Automatically saves the API key to a file when provided to the ``get_series`` function, ignoring subsequent entries unless explicitly updated. -- **Visual and Textual Menu Options**: Provides both a visual and textual menu to facilitate user interaction for setting up projects, creating output folders, and preparing configuration files. +- **Visual and Textual Menu Options**: Provides both visual and textual menus to facilitate user interaction for setting up projects, creating output folders, and preparing configuration files. - **Data Request Handling**: Utilizes caching to optimize data retrieval, minimizing redundant requests and speeding up the data access process. Installation ------------ To install evdspy, simply run the following command: + .. code-block:: bash pip install evdspy -U @@ -55,39 +77,28 @@ Quick Start ----------- Here's a quick example to get you started with using evdspy: +using get_series function from evdspy + .. code-block:: python + + from evdsy import get_series + index = "TP.ODEMGZS.BDTTOPLAM" + df = get_series(index, start_date="21-01-2020", end_date="31-12-2021", frequency="monthly") + print(df.head()) - from evdspy import get_series, default_start_date_fnc, default_end_date_fnc - index = "TP.ODEMGZS.BDTTOPLAM", "TP.ODEMGZS.ABD" - df = get_series(index, frequency="monthly", start_date=default_start_date_fnc(), end_date=default_end_date_fnc(), aggregation=("avg",), cache=True) - print(df) -API Usage Examples ------------------- +using get_series_exp function from evdspy -.. literalinclude:: ../../evdspy_example.py - :language: python - :linenos: - :caption: Example of using the get_series function to retrieve data. +.. code-block:: python -Menus and Commands ------------------- -- **Main Menu**: Access a user-friendly menu to manage data requests and settings. -- **Console Commands**: Use terminal commands to manage settings and request data: + from evdsy import get_series , get_series_exp + index = "TP.ODEMGZS.BDTTOPLAM" + result = get_series_exp(index, start_date="21-01-2020", end_date="31-12-2021", frequency="monthly") + print(result.data ) # data frame of data + print(result.metadata ) # metadata frame of data + result.to_excel('filename.xlsx') # write output as excel file data and metadata in sheets - .. code-block:: bash - evdspy setup - evdspy menu - evdspy create series - evdspy help - evdspy get -Learn More ----------- -For more detailed information on all functions and their parameters, refer to the *Modules* section or visit our [GitHub Repository](https://github.com/SermetPekin/evdspy-repo). -Disclaimer ----------- -Please note that evdspy is not officially affiliated with or endorsed by the CBRT. It is developed and maintained under an MIT license by independent developers. Use of this tool should comply with all applicable laws and API usage guidelines provided by the CBRT. diff --git a/docs/source/homeEski.EEErst b/docs/source/homeEski.EEErst new file mode 100644 index 0000000..7b3f6a5 --- /dev/null +++ b/docs/source/homeEski.EEErst @@ -0,0 +1,93 @@ + +Introduction +=============================== +.. image:: https://github.com/SermetPekin/evdspy-repo/actions/workflows/python-package.yml/badge.svg + :target: https://github.com/SermetPekin/evdspy-repo/actions/workflows/python-package.yml +.. image:: https://img.shields.io/pypi/v/evdspy + :target: https://pypi.org/project/evdspy/ +.. image:: https://img.shields.io/pypi/pyversions/evdspy + :target: https://pypi.org/project/evdspy/ +.. image:: https://pepy.tech/badge/evdspy/week + :target: https://pepy.tech/project/evdspy + +evdspy is an open-source Python interface that simplifies making requests to the Central Bank of the Republic of Turkey (CBRT) Electronic Data Delivery System (EVDS). It provides efficient request handling by caching results, a user-friendly menu for data inquiries, and capabilities for handling complex data structures through an accessible API. + +View Source Code +---------------- +You can view the source code for this project on GitHub: `View Source `_. + +What's New +---------- +**Updated on this version:** +- The API key parameter has now been moved to the HTTP header to enhance security and ensure that sensitive information is not exposed in URLs. +- Added a new function, ``get_series``, which enhances the way data groups and series are handled. +- Deprecated: The ``get_datagroup`` function will be deprecated in future versions; ``get_series`` will cover its functionalities. + +### Updated on this version + +#### evdspyChat application was added. + +Api Key is not required for only evdspy documentation related questions. + +[evdspyChat](https://evdspychat-b11f96868cb6.herokuapp.com/) + + [![tellme](https://github.com/user-attachments/assets/14024132-4d41-4879-9ea8-3e510b2f8f02)](https://evdspychat-b11f96868cb6.herokuapp.com/) + +[![askyourself](https://github.com/user-attachments/assets/2cece3e0-958a-454b-8876-5dbdfea1e1a4)](https://evdspychat-b11f96868cb6.herokuapp.com/) + +[![a2](https://github.com/user-attachments/assets/3e5d3ab4-df41-4d34-8e2a-e1ca3d19a190)](https://evdspychat-b11f96868cb6.herokuapp.com/) + + +Key Features +------------ +- **API Key Management**: Automatically saves the API key to a file when provided to the ``get_series`` function, ignoring subsequent entries unless explicitly updated. +- **Visual and Textual Menu Options**: Provides both a visual and textual menu to facilitate user interaction for setting up projects, creating output folders, and preparing configuration files. +- **Data Request Handling**: Utilizes caching to optimize data retrieval, minimizing redundant requests and speeding up the data access process. + +Installation +------------ +To install evdspy, simply run the following command: +.. code-block:: bash + + pip install evdspy -U + +Quick Start +----------- +Here's a quick example to get you started with using evdspy: + +.. code-block:: python + + from evdspy import get_series, default_start_date_fnc, default_end_date_fnc + index = "TP.ODEMGZS.BDTTOPLAM", "TP.ODEMGZS.ABD" + df = get_series(index, frequency="monthly", start_date=default_start_date_fnc(), end_date=default_end_date_fnc(), aggregation=("avg",), cache=True) + print(df) + +API Usage Examples +------------------ + +.. literalinclude:: ../../evdspy_example.py + :language: python + :linenos: + :caption: Example of using the get_series function to retrieve data. + +Menus and Commands +------------------ +- **Main Menu**: Access a user-friendly menu to manage data requests and settings. +- **Console Commands**: Use terminal commands to manage settings and request data: + + .. code-block:: bash + + evdspy setup + evdspy menu + evdspy create series + evdspy help + evdspy get + +Learn More +---------- +For more detailed information on all functions and their parameters, refer to the *Modules* section or visit our [GitHub Repository](https://github.com/SermetPekin/evdspy-repo). + +Disclaimer +---------- +Please note that evdspy is not officially affiliated with or endorsed by the CBRT. It is developed and maintained under an MIT license by independent developers. Use of this tool should comply with all applicable laws and API usage guidelines provided by the CBRT. + diff --git a/docs/source/proxy.rst b/docs/source/proxy.rst index b690d5f..8de182c 100644 --- a/docs/source/proxy.rst +++ b/docs/source/proxy.rst @@ -9,21 +9,14 @@ Creating a `.env` File Create a `.env` file in the root directory of your project and define your proxies as shown below: -.. code-block:: python +.. code-block:: bash # Example .env file content EVDS_API_KEY=AxByCzDsFoGmHeIgJaKrLbMaNgOe -<<<<<<< HEAD - - http_proxy=http://proxy.example.com:80 - https_proxy=http://proxy.example.com:80 - -======= http_proxy=http://proxy.example.com:80 https_proxy=http://proxy.example.com:80 ->>>>>>> f106125c794f7eeb8348e421c7d0ba4b3edee5e1 Replace `http://proxy.example.com:80` with the actual URL and port of your proxy server. @@ -35,16 +28,10 @@ Windows To set environment variables on Windows, you can use the `setx` command in the Command Prompt: -.. code-block:: python -<<<<<<< HEAD - - setx EVDS_API_KEY "AxByCzDsFoGmHeIgJaKrLbMaNgOe" - setx http_proxy "http://proxy.example.com:80" -======= +.. code-block:: bash setx EVDS_API_KEY "AxByCzDsFoGmHeIgJaKrLbMaNgOe" setx http_proxy "http://proxy.example.com:80" ->>>>>>> f106125c794f7eeb8348e421c7d0ba4b3edee5e1 setx https_proxy "http://proxy.example.com:80" @@ -53,7 +40,7 @@ Linux and macOS ---------- To set environment variables on Linux or macOS, you can use the `export` command in the terminal: -.. code-block:: python +.. code-block:: bash export EVDS_API_KEY="AxByCzDsFoGmHeIgJaKrLbMaNgOe" export http_proxy="http://proxy.example.com:80" @@ -61,7 +48,8 @@ To set environment variables on Linux or macOS, you can use the `export` command You can add these lines to your shell configuration file (e.g., `.bashrc`, `.bash_profile`, `.zshrc`) to make them persistent. -## Notes +Notes +---------- - Replace `http://proxy.example.com:80` with the actual URL and port of your proxy server. - For the API key and proxy settings to take effect, you might need to restart your terminal or Command Prompt session. \ No newline at end of file