From 8128cc0c599d4880b3d5b3ace5a92df23cf0b71f Mon Sep 17 00:00:00 2001 From: Sermet Pekin Date: Fri, 19 Apr 2024 21:37:45 +0300 Subject: [PATCH] docs --- docs/{Makefile. => Makefile} | 5 ++++- docs/make.bat | 35 +++++++++++++++++++++++++++++++++++ docs/requirements.txt | 1 - docs/source/conf.py | 22 ++++++++++++++++++++-- docs/source/get_series.rst | 32 ++++++++++++++++++++++++++++++-- docs/source/home.rst | 19 ++++++++++++++++++- docs/source/index.rst | 8 ++++++-- docs/source/menu.rst | 13 ++++++++++++- docs/source/save.rst | 11 ++++++++++- docs/source/setup.rst | 10 +++++++++- 10 files changed, 144 insertions(+), 12 deletions(-) rename docs/{Makefile. => Makefile} (99%) create mode 100644 docs/make.bat diff --git a/docs/Makefile. b/docs/Makefile similarity index 99% rename from docs/Makefile. rename to docs/Makefile index c37efd7..269cadc 100644 --- a/docs/Makefile. +++ b/docs/Makefile @@ -1,16 +1,19 @@ - # Minimal makefile for Sphinx documentation # + # You can set these variables from the command line, and also # from the environment for the first two. SPHINXOPTS ?= SPHINXBUILD ?= sphinx-build SOURCEDIR = source BUILDDIR = build + # Put it first so that "make" without argument is like "make help". help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + .PHONY: help Makefile + # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..dc1312a --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/requirements.txt b/docs/requirements.txt index 80877a4..55cf737 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,3 @@ - evdspy==1.1.21 sphinx_rtd_theme sphinx_book_theme \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index 4b93a97..f9ca957 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,21 +1,26 @@ - # Configuration file for the Sphinx documentation builder. # # For the full list of built-in configuration values, see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html + # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + html_build_dir = '../docs' # html_build_dir = 'docs' + project = 'evdspy' copyright = '2024, Sermet Pekin' author = 'Sermet Pekin' + # The short X.Y version version = '' # The full version, including alpha/beta/rc tags release = '' # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + + extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.doctest', @@ -27,23 +32,34 @@ 'sphinx.ext.autosummary', # 'myst_parser' ] + templates_path = ['_templates'] exclude_patterns = [] + # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + + # html_theme = 'sphinx_rtd_theme' html_theme = 'sphinx_book_theme' + html_static_path = ['static'] + source_suffix = { '.rst': 'restructuredtext', '.txt': 'markdown', '.md': 'markdown', } + import os import inspect from sphinx.util import logging + logger = logging.getLogger(__name__) + import time + + def linkcode_resolve(domain, info): print(domain, info, "Domain info ") if domain != 'py': @@ -51,4 +67,6 @@ def linkcode_resolve(domain, info): if not info['module']: return None filename = info['module'].replace('.', '/') - return "https://github.com/SermetPekin/evdspy-repo/%s.py" % filename \ No newline at end of file + return "https://github.com/SermetPekin/evdspy-repo/%s.py" % filename + + diff --git a/docs/source/get_series.rst b/docs/source/get_series.rst index cbee201..8e14eae 100644 --- a/docs/source/get_series.rst +++ b/docs/source/get_series.rst @@ -1,18 +1,24 @@ - get_series Function =================== + The ``get_series`` function fetches economic data series from a specified API and returns it formatted as a pandas DataFrame, making extensive use of various parameters to fine-tune the data retrieval process. + .. autofunction:: evdspy.get_series + Parameters ---------- index : str or tuple Identifier(s) for the data series to fetch. This can be a single string for one series or a tuple of strings for multiple series. + start_date : str, optional The start date for the data retrieval in 'DD-MM-YYYY' format. By default, this calls ``default_start_date_fnc()``. + end_date : str, optional The end date for the data retrieval in 'DD-MM-YYYY' format. By default, this calls ``default_end_date_fnc()``. + frequency : str, optional The frequency at which data should be retrieved. Options include: + - **daily (1)**: Data retrieved every day. - **business (2)**: Data retrieved only on business days. - **weekly (3)**: Data retrieved weekly on Fridays. @@ -21,8 +27,10 @@ frequency : str, optional - **quarterly (6)**: Data retrieved every quarter. - **semiannually (7)**: Data retrieved twice a year. - **annual/annually (8)**: Data retrieved once a year. + formulas : str or tuple, optional Computation methods to apply to the data series. Options include: + - **level (0)**: Raw data values. - **percentage change (1)**: Percent change between consecutive data points. - **difference (2)**: Difference between consecutive data points. @@ -32,46 +40,66 @@ formulas : str or tuple, optional - **difference compared to end-of-previous year (6)**: Difference relative to the end of the previous year. - **moving average (7)**: Moving average of data points. - **moving sum (8)**: Moving sum of data points. + aggregation : str or tuple, optional Aggregation methods to apply to the data, options include: + - **avg**: Average value over the specified period. - **min**: Minimum value over the specified period. - **max**: Maximum value over the specified period. - **first**: First value within the specified period. - **last**: Last value within the specified period. - **sum**: Sum of all values within the specified period. + cache : bool, optional If True, uses cached data when available to speed up the data retrieval process. Default is False. + proxy : str, optional The URL of the proxy server to use for the requests. Default is None. + proxies : dict, optional A dictionary of proxies to use for the request. Default is None. + debug : bool, optional If True, runs the function in debug mode, providing additional debug information without making a real API request. Default is False. + api_key : str, optional The API key required for accessing the data. Initially, it can be saved using the ``save("APIKEY")`` function or via command line with ``$ evdspy save``. + Returns ------- pd.DataFrame A pandas DataFrame containing the retrieved data series. + Raises ------ ValueError Raised if an invalid API key is provided or required parameters are missing. + Examples -------- Basic usage: + .. code-block:: python + index = "TP.ODEMGZS.BDTTOPLAM" df = get_series(index, start_date="01-01-2020", end_date="01-01-2021", frequency="monthly") print(df.head()) + Using multiple indexes and cache: + .. code-block:: python + indexes = ("TP.ODEMGZS.BDTTOPLAM", "TP.ODEMGZS.ABD") df = get_series(indexes, start_date="01-01-2020", frequency="monthly", cache=True) print(df.head()) + Applying formulas and aggregation: + .. code-block:: python + template = "TP.ODEMGZS.BDTTOPLAM" df = get_series(template, start_date="01-01-2020", formulas="level", aggregation="sum") - print(df.head()) \ No newline at end of file + print(df.head()) + + diff --git a/docs/source/home.rst b/docs/source/home.rst index baf3907..77cb36d 100644 --- a/docs/source/home.rst +++ b/docs/source/home.rst @@ -9,53 +9,70 @@ Introduction :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) 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. + 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. + 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. \ No newline at end of file +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/index.rst b/docs/source/index.rst index 1ccc3c6..daa1feb 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,20 +1,24 @@ - .. evdspy documentation master file, created by sphinx-quickstart on Wed Apr 17 23:47:22 2024. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. + Welcome to evdspy's documentation! ================================== .. toctree:: :maxdepth: 2 :caption: Contents: + home get_series setup save menu + + Indices and tables ================== * :ref:`genindex` * :ref:`modindex` -* :ref:`search` \ No newline at end of file +* :ref:`search` + diff --git a/docs/source/menu.rst b/docs/source/menu.rst index bbfd29f..79e81a0 100644 --- a/docs/source/menu.rst +++ b/docs/source/menu.rst @@ -3,26 +3,37 @@ menu Function ============= The ``menu`` function displays a list of selectable options to the user and returns the index of the chosen option. This function is useful in CLI applications where user interaction is required to choose between different actions. + .. autofunction:: evdspy.menu + Function Details ---------------- + .. autofunction:: evdspy.menu + Parameters ---------- options : list of str A list of strings that represent the choices available to the user. + Returns ------- int The index of the option selected by the user, where the first option is indexed as 0. + Raises ------ ValueError If the user's input is not a valid option index. + Example Usage ------------- Here is a simple usage example that demonstrates how to use the ``menu`` function: + .. code-block:: python + from evdspy import menu menu() -This example will display a menu with three options. After the user selects an option, the function will print the selected option. \ No newline at end of file + +This example will display a menu with three options. After the user selects an option, the function will print the selected option. + diff --git a/docs/source/save.rst b/docs/source/save.rst index 60fc2e4..d47742c 100644 --- a/docs/source/save.rst +++ b/docs/source/save.rst @@ -2,14 +2,19 @@ save Function ==================== 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. + .. autofunction:: evdspy.save + Function Signature ------------------ + .. autofunction:: evdspy.save + Parameters ---------- api_key : str, optional The API key to be saved. If not provided or if an invalid key is passed, the user is prompted to input a valid API key interactively. + Behavior and Errors ------------------- The function checks if the provided `api_key` is a valid string. If the `api_key` is `None` or not a string, it attempts to set the API key through an interactive input method provided by `set_apikey_input()`. @@ -17,12 +22,16 @@ This function should handle cases where: - An API key is not provided, leading to an interactive input request. - An invalid API key type is provided, prompting a type check and subsequent interactive input request. The final step involves checking the validity of the API key with `check_apikey_and_then_save(api_key)`, which presumably implements further validation and storage mechanisms. + Example Usage ------------- Here is how you might typically call this function: + .. code-block:: python # Example of saving an API key directly save("your_api_key_here") # Example when no API key is provided; this will trigger an interactive input prompt save() -This function is crucial for scenarios where secure and valid API key storage is necessary for the operation of your application, particularly in environments where configuration changes dynamically or where user input is required to initiate configuration. \ No newline at end of file + +This function is crucial for scenarios where secure and valid API key storage is necessary for the operation of your application, particularly in environments where configuration changes dynamically or where user input is required to initiate configuration. + diff --git a/docs/source/setup.rst b/docs/source/setup.rst index 30145f3..ba58b01 100644 --- a/docs/source/setup.rst +++ b/docs/source/setup.rst @@ -3,22 +3,30 @@ setup Function ============== The ``setup`` function initializes the application environment by performing multiple preparatory steps essential for the application's operation. This function encapsulates tasks such as configuring settings, initializing data structures, and preparing necessary resources. .. autofunction:: evdspy.setup + Function Details ---------------- .. autofunction:: evdspy.setup + Purpose ------- The function is designed to: - Initialize base settings and configurations via ``SetupInitial().setup()`` - Configure additional settings specific to the application setup phase with ``start_setup_config(onsetup=True)`` - Create initial data examples necessary for the application with ``create_series_text_example(onsetup=True)`` + Usage ----- The ``setup`` function is typically called at the beginning of the application's lifecycle, before any other operations or user interactions occur. + Example Usage ------------- This function is generally used without arguments and does not return any value: .. code-block:: python + from evdspy import setup + setup() -This call ensures that all initial configurations and setups are correctly executed, preparing the application for use. \ No newline at end of file + +This call ensures that all initial configurations and setups are correctly executed, preparing the application for use. +