diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..269cadc --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# 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 + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/build/html/_sources/get_series.rst.txt b/docs/build/html/_sources/get_series.rst.txt deleted file mode 100644 index 397f87a..0000000 --- a/docs/build/html/_sources/get_series.rst.txt +++ /dev/null @@ -1,60 +0,0 @@ - -get_series Function -=================== -The ``get_series`` function is designed to fetch economic data series from a specified API and return 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 'monthly', 'weekly', 'annually', 'semimonthly', 'semiannually', and 'business'. -formulas : str or tuple, optional - Computation methods to apply to the data series, such as 'level', 'percentage_change', 'difference', 'year_to_year_percent_change', or 'year_to_year_differences'. -aggregation : str or tuple, optional - Aggregation methods to apply to the data, options include 'avg', 'min', 'max', 'first', 'last', and 'sum'. -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()) -.. code-block:: python - template = """ - TP.ODEMGZS.BDTTOPLAM - TP.ODEMGZS.ABD - """ - df = get_series(template, start_date="01-01-2020", frequency="monthly", cache=True) - print(df.head()) -Applying formulas and aggregation: -.. code-block:: python - df = get_series(template, start_date="01-01-2020", formulas="level", aggregation="sum") - print(df.head()) \ No newline at end of file diff --git a/docs/build/html/_sources/home.rst.txt b/docs/build/html/_sources/home.rst.txt deleted file mode 100644 index ddc87a4..0000000 --- a/docs/build/html/_sources/home.rst.txt +++ /dev/null @@ -1,61 +0,0 @@ - -Welcome to evdspy Documentation -=============================== -.. 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) 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 diff --git a/docs/build/html/_sources/index.rst.txt b/docs/build/html/_sources/index.rst.txt deleted file mode 100644 index 1ccc3c6..0000000 --- a/docs/build/html/_sources/index.rst.txt +++ /dev/null @@ -1,20 +0,0 @@ - -.. 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 diff --git a/docs/build/html/_sources/menu.rst.txt b/docs/build/html/_sources/menu.rst.txt deleted file mode 100644 index bbfd29f..0000000 --- a/docs/build/html/_sources/menu.rst.txt +++ /dev/null @@ -1,28 +0,0 @@ - -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 diff --git a/docs/build/html/_sources/save.rst.txt b/docs/build/html/_sources/save.rst.txt deleted file mode 100644 index 60fc2e4..0000000 --- a/docs/build/html/_sources/save.rst.txt +++ /dev/null @@ -1,28 +0,0 @@ - -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()`. -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 diff --git a/docs/build/html/_sources/setup.rst.txt b/docs/build/html/_sources/setup.rst.txt deleted file mode 100644 index 30145f3..0000000 --- a/docs/build/html/_sources/setup.rst.txt +++ /dev/null @@ -1,24 +0,0 @@ - -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 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/source/conf.py b/docs/source/conf.py index b859fa9..8ab7c4f 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -6,7 +6,8 @@ # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information -html_build_dir = '../docs' +# html_build_dir = '../docs' +# html_build_dir = 'docs' project = 'evdspy' copyright = '2024, Sermet Pekin' @@ -40,7 +41,7 @@ html_theme = 'sphinx_book_theme' html_static_path = ['static'] -# extensions = ['myst_parser'] + source_suffix = { '.rst': 'restructuredtext', '.txt': 'markdown', @@ -58,7 +59,6 @@ def linkcode_resolve(domain, info): print(domain, info, "Domain info ") - time.sleep(2) if domain != 'py': return None if not info['module']: @@ -67,24 +67,3 @@ def linkcode_resolve(domain, info): return "https://github.com/SermetPekin/evdspy-repo/%s.py" % filename -def linkcode_resolveOLD(domain, info): - if domain != 'py' or not info['module']: - return None - - try: - mod = __import__(info['module']) - for part in info['module'].split('.')[1:]: - mod = getattr(mod, part) - obj = mod - if 'fullname' in info: - obj = getattr(obj, info['fullname']) - filename = inspect.getsourcefile(obj) - filename = os.path.relpath(filename, start=os.path.dirname(mod.__file__)) - lines, _ = inspect.getsourcelines(obj) - except Exception as e: - logger.warning(f"Could not get source link for module {info['module']} due to {e}") - return None - - tag_or_branch = 'main' # or 'master' or the specific tag if versioned - path_to_file = os.path.join('path_to_repository', filename) - return f"https://github.com/SermetPekin/evdspy-repo/blob/{tag_or_branch}/{path_to_file}#L{lines[0]}" \ No newline at end of file diff --git a/docs/source/home.rst b/docs/source/home.rst index baf3907..8214255 100644 --- a/docs/source/home.rst +++ b/docs/source/home.rst @@ -9,53 +9,67 @@ 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. +