From 3b043d32723a718ff1506e0c87ed2c14af5063c8 Mon Sep 17 00:00:00 2001 From: EtWn <34377743+EtWnn@users.noreply.github.com> Date: Wed, 24 Mar 2021 15:05:43 +0100 Subject: [PATCH] Docs (#21) (#22) * remove links in comments for BinanceDataBase * add missing with spaces in doc strings * add code example for docs * switch from README.md to README.rst * add sphinx docs * increase version to 0.1.1 * update documentation links * correct maj --- BinanceWatch/BinanceManager.py | 2 +- BinanceWatch/__init__.py | 2 +- BinanceWatch/storage/BinanceDataBase.py | 149 ++++++++++++++++++++++-- README.md | 106 ----------------- README.rst | 125 ++++++++++++++++++++ docs/Makefile | 20 ++++ docs/make.bat | 35 ++++++ docs/source/binance_database.rst | 7 ++ docs/source/binance_manager.rst | 6 + docs/source/conf.py | 55 +++++++++ docs/source/index.rst | 20 ++++ docs/source/overview.rst | 98 ++++++++++++++++ setup.py | 6 +- 13 files changed, 508 insertions(+), 123 deletions(-) delete mode 100644 README.md create mode 100644 README.rst create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/source/binance_database.rst create mode 100644 docs/source/binance_manager.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst create mode 100644 docs/source/overview.rst diff --git a/BinanceWatch/BinanceManager.py b/BinanceWatch/BinanceManager.py index 1d82500..40d7da7 100644 --- a/BinanceWatch/BinanceManager.py +++ b/BinanceWatch/BinanceManager.py @@ -84,7 +84,7 @@ def update_universal_transfers(self, transfer_filter: Optional[str] = None): pbar = tqdm(total=len(transfers_types)) for transfer_type in transfers_types: pbar.set_description(f"fetching transfer type {transfer_type}") - latest_time = self.db.get_last_universal_transfer(transfer_type=transfer_type) + 1 + latest_time = self.db.get_last_universal_transfer_time(transfer_type=transfer_type) + 1 current = 1 while True: universal_transfers = self.client.query_universal_transfer_history(type=transfer_type, diff --git a/BinanceWatch/__init__.py b/BinanceWatch/__init__.py index ff90f68..863cfad 100644 --- a/BinanceWatch/__init__.py +++ b/BinanceWatch/__init__.py @@ -1,2 +1,2 @@ -__version__ = "0.1.0" +__version__ = "0.1.1" __author__ = 'EtWnn' diff --git a/BinanceWatch/storage/BinanceDataBase.py b/BinanceWatch/storage/BinanceDataBase.py index 4833767..f7fab3a 100644 --- a/BinanceWatch/storage/BinanceDataBase.py +++ b/BinanceWatch/storage/BinanceDataBase.py @@ -54,6 +54,16 @@ def get_universal_transfers(self, transfer_type: Optional[str] = None, asset: Op :type end_time: Optional[int] :return: The raw rows selected as saved in the database :rtype: List[Tuple] + + .. code-block:: python + + [ + (1206491332, # transfer id + 'MAIN_MARGIN', # transfer type + 1589121841000, # time + 'BNB', # asset + 10.594112), # amount + ] """ table = tables.UNIVERSAL_TRANSFER_TABLE @@ -76,7 +86,7 @@ def get_universal_transfers(self, transfer_type: Optional[str] = None, asset: Op end_time)) return self.get_conditions_rows(table, conditions_list=conditions_list) - def get_last_universal_transfer(self, transfer_type: str): + def get_last_universal_transfer_time(self, transfer_type: str) -> int: """ return the latest time when a universal transfer was made If None, return the millistamp corresponding to 2017/01/01 @@ -148,6 +158,15 @@ def get_margin_interests(self, margin_type: str, asset: Optional[str] = None, st :type end_time: Optional[int] :return: The raw rows selected as saved in the database :rtype: List[Tuple] + + .. code-block:: python + + [ + 1559415215400, # time + 'BNB', # asset + 0.51561, # interest + 'PERIODIC_CONVERTED'), # interest type + ] """ if margin_type == 'cross': table = tables.CROSS_MARGIN_INTEREST_TABLE @@ -255,6 +274,16 @@ def get_repays(self, margin_type: str, asset: Optional[str] = None, start_time: :type end_time: Optional[int] :return: The raw rows selected as saved in the database :rtype: List[Tuple] + + .. code-block:: python + + [ + (8289451654, # transaction id + 1559415215400, # time + 'USDT', # asset + 145.5491462, # principal + 0.51561), # interest + ] """ if margin_type == 'cross': table = tables.CROSS_MARGIN_REPAY_TABLE @@ -278,7 +307,7 @@ def get_repays(self, margin_type: str, asset: Optional[str] = None, start_time: end_time)) return self.get_conditions_rows(table, conditions_list=conditions_list) - def get_last_repay_time(self, asset: str, margin_type: str): + def get_last_repay_time(self, asset: str, margin_type: str) -> int: """ return the latest time when a repay was made on a defined asset If None, return the millistamp corresponding to 2017/01/01 @@ -358,6 +387,15 @@ def get_loans(self, margin_type: str, asset: Optional[str] = None, start_time: O :type end_time: Optional[int] :return: The raw rows selected as saved in the database :rtype: List[Tuple] + + .. code-block:: python + + [ + (8289451654, # transaction id + 1559415215400, # time + 'USDT', # asset + 145.5491462), # amount + ] """ if margin_type == 'cross': table = tables.CROSS_MARGIN_LOAN_TABLE @@ -381,7 +419,7 @@ def get_loans(self, margin_type: str, asset: Optional[str] = None, start_time: O end_time)) return self.get_conditions_rows(table, conditions_list=conditions_list) - def get_last_loan_time(self, asset: str, margin_type: str): + def get_last_loan_time(self, asset: str, margin_type: str) -> int: """ return the latest time when an loan was made on a defined asset If None, return the millistamp corresponding to 2017/01/01 @@ -442,7 +480,7 @@ def get_lending_redemptions(self, lending_type: Optional[str] = None, asset: Opt """ return lending redemptions stored in the database. Asset type and time filters can be used - :param lending_type:fetch only redemptions from this lending type + :param lending_type: fetch only redemptions from this lending type :type lending_type: Optional[str] :param asset: fetch only redemptions from this asset :type asset: Optional[str] @@ -452,6 +490,15 @@ def get_lending_redemptions(self, lending_type: Optional[str] = None, asset: Opt :type end_time: Optional[int] :return: The raw rows selected as saved in the database :rtype: List[Tuple] + + .. code-block:: python + + [ + 1612841562000, # time + 'DAILY', # lending type + 'LTC', # asset + 1.89151684), # amount + ] """ conditions_list = [] table = tables.LENDING_REDEMPTION_TABLE @@ -473,7 +520,7 @@ def get_lending_redemptions(self, lending_type: Optional[str] = None, asset: Opt end_time)) return self.get_conditions_rows(table, conditions_list=conditions_list) - def get_last_lending_redemption_time(self, lending_type: Optional[str] = None): + def get_last_lending_redemption_time(self, lending_type: Optional[str] = None) -> int: """ return the latest time when an lending redemption was made. If None, return the millistamp corresponding to 2017/01/01 @@ -530,7 +577,7 @@ def get_lending_purchases(self, lending_type: Optional[str] = None, asset: Optio """ return lending purchases stored in the database. Asset type and time filters can be used - :param lending_type:fetch only purchases from this lending type + :param lending_type: fetch only purchases from this lending type :type lending_type: Optional[str] :param asset: fetch only purchases from this asset :type asset: Optional[str] @@ -540,6 +587,16 @@ def get_lending_purchases(self, lending_type: Optional[str] = None, asset: Optio :type end_time: Optional[int] :return: The raw rows selected as saved in the database :rtype: List[Tuple] + + .. code-block:: python + + [ + (58516828, # purchase id + 1612841562000, # time + 'DAILY', # lending type + 'LTC', # asset + 1.89151684), # amount + ] """ conditions_list = [] table = tables.LENDING_PURCHASE_TABLE @@ -561,7 +618,7 @@ def get_lending_purchases(self, lending_type: Optional[str] = None, asset: Optio end_time)) return self.get_conditions_rows(table, conditions_list=conditions_list) - def get_last_lending_purchase_time(self, lending_type: Optional[str] = None): + def get_last_lending_purchase_time(self, lending_type: Optional[str] = None) -> int: """ return the latest time when an lending purchase was made. If None, return the millistamp corresponding to 2017/01/01 @@ -616,7 +673,7 @@ def get_lending_interests(self, lending_type: Optional[str] = None, asset: Optio """ return lending interests stored in the database. Asset type and time filters can be used - :param lending_type:fetch only interests from this lending type + :param lending_type: fetch only interests from this lending type :type lending_type: Optional[str] :param asset: fetch only interests from this asset :type asset: Optional[str] @@ -626,6 +683,16 @@ def get_lending_interests(self, lending_type: Optional[str] = None, asset: Optio :type end_time: Optional[int] :return: The raw rows selected as saved in the database :rtype: List[Tuple] + + .. code-block:: python + + [ + (1619846515000, # time + 'DAILY', # lending type + 'DOT', # asset + 0.00490156) # amount + ] + """ conditions_list = [] table = tables.LENDING_INTEREST_TABLE @@ -647,7 +714,7 @@ def get_lending_interests(self, lending_type: Optional[str] = None, asset: Optio end_time)) return self.get_conditions_rows(table, conditions_list=conditions_list) - def get_last_lending_interest_time(self, lending_type: Optional[str] = None): + def get_last_lending_interest_time(self, lending_type: Optional[str] = None) -> int: """ return the latest time when an interest was received. If None, return the millistamp corresponding to 2017/01/01 @@ -680,7 +747,6 @@ def add_dust(self, tran_id: str, time: int, asset: str, asset_amount: float, bnb auto_commit: bool = True): """ add dust operation to the database - https://binance-docs.github.io/apidocs/spot/en/#dustlog-user_data :param tran_id: id of the transaction (non unique) :type tran_id: str @@ -716,6 +782,17 @@ def get_spot_dusts(self, asset: Optional[str] = None, start_time: Optional[int] :type end_time: Optional[int] :return: The raw rows selected as saved in the database :rtype: List[Tuple] + + .. code-block:: python + + [ + (82156485284, # transaction id + 1605489113400, # time + 'TRX', # asset + 102.78415879, # asset amount + 0.09084498, # bnb amount + 0.00171514), # bnb fee + ] """ conditions_list = [] table = tables.SPOT_DUST_TABLE @@ -766,6 +843,16 @@ def get_spot_dividends(self, asset: Optional[str] = None, start_time: Optional[i :type end_time: Optional[int] :return: The raw rows selected as saved in the database :rtype: List[Tuple] + + .. code-block:: python + + [ + (8945138941, # dividend id + 1594513589000, # time + 'TRX', # asset + 0.18745654), # amount + ] + """ conditions_list = [] table = tables.SPOT_DIVIDEND_TABLE @@ -842,6 +929,18 @@ def get_spot_withdraws(self, asset: Optional[str] = None, start_time: Optional[i :type end_time: Optional[int] :return: The raw rows selected as saved in the database :rtype: List[Tuple] + + .. code-block:: python + + [ + ('84984dcqq5z11gyjfa', # withdraw id + 'aazd8949vredqs56dz', # transaction id + 1599138389000, # withdraw time + 'XTZ', # asset + 57.0194, # amount + 0.5), # fee + ] + """ conditions_list = [] table = tables.SPOT_WITHDRAW_TABLE @@ -912,6 +1011,16 @@ def get_spot_deposits(self, asset: Optional[str] = None, start_time: Optional[in :type end_time: Optional[int] :return: The raw rows selected as saved in the database :rtype: List[Tuple] + + .. code-block:: python + + [ + ('azdf5e6a1d5z', # transaction id + 1589479004000, # deposit time + 'LTC', # asset + 14.25), # amount + ] + """ conditions_list = [] table = tables.SPOT_DEPOSIT_TABLE @@ -934,7 +1043,8 @@ def get_last_spot_deposit_time(self) -> int: fetch the latest time a deposit has been made on the spot account. If None is found, return the millistamp corresponding to 2017/1/1 - :return: + :return: last deposit millistamp + :rtype: int """ table = tables.SPOT_DEPOSIT_TABLE selection = f"MAX({table.insertTime})" @@ -971,7 +1081,7 @@ def add_trade(self, trade_type: str, trade_id: int, trade_time: int, asset: str, :type price: float :param fee: amount kept by the exchange :type fee: float - :param fee_asset:token unit for the fee + :param fee_asset: token unit for the fee :type fee_asset: str :param is_buyer: if the trade is a buy or a sell :type is_buyer: bool @@ -1006,6 +1116,21 @@ def get_trades(self, trade_type: str, start_time: Optional[int] = None, end_time :type ref_asset: Optional[str] :return: The raw rows selected as saved in the database :rtype: List[Tuple] + + .. code-block:: python + + [ + (384518832, # trade_id + 1582892988052, # trade time + 'BTC', # asset + 'USDT', # ref asset + 0.0015, # asset quantity + 9011.2, # asset price to ref asset + 0.01425, # fee + 'USDT', # fee asset + 0), # is_buyer + ] + """ if trade_type == 'spot': table = tables.SPOT_TRADE_TABLE diff --git a/README.md b/README.md deleted file mode 100644 index 1f490b9..0000000 --- a/README.md +++ /dev/null @@ -1,106 +0,0 @@ -# Welcome to BinanceWatch v0.1.0 - - -## Note - - -This library is under development by EtWnn, feel free to drop your suggestions or remarks in -the discussion tab of the git repo. You are also welcome to contribute by submitting PRs. - -This is an unofficial tracker for binance accounts. I am in no way affiliated with Binance, use at -your own risk. - -**Source Code:** https://github.com/EtWnn/BinanceWatch - - -## Features - - -If you used quite intensively Binance, it can take some time to retrieve everything that happened -on your account. This library is made to save locally the events of your account so that you don't -need to fetch your history from the beginning every time. - - -It currently supports: - -- Spot Trades -- Spot Crypto Deposits -- Spot Crypto Withdraws -- Spot Dividends -- Spot Dusts -- Universal Transfers - - - -- Lending Purchases -- Lending Interests -- Lending Redemptions - - - -- Cross Margin Trades -- Cross Margin Repayment -- Cross Margin Loans -- Cross Margin Interests - -## Quick Tour - - -[Generate an API Key](https://www.binance.com/en/my/settings/api-management) in your binance account. Only read -permissions are needed. - -Install this library with pip: -`pip install BinanceWatch` - -```python -from BinanceWatch.BinanceManager import BinanceManager - -api_key = "" -api_secret = "" - -bm = BinanceManager(api_key, api_secret) - -# fetch the latest spot trades from Binance -bm.update_all_spot_trades() -``` -``` -Out -> fetching BIFIBUSD: 100%|██████████████████████| 1349/1349 [06:24<00:00, 3.51it/s] -``` -```python -from datetime import datetime -from BinanceWatch.utils.time_utils import datetime_to_millistamp - - -start_time = datetime_to_millistamp(datetime(2018,1,1)) - -# get the locally saved spot trades made after 2018/01/01 -spot_trades = bm.db.get_trades('spot', start_time=start_time) -``` - -You can also call update functions at an account-type level, and it will call every update -methods related to this account-type: -```python -bm.update_spot() # (trades, transfers, deposits ...) - -bm.update_cross_margin() # (trades, loans, repays, interests...) - -bm.update_lending() # (purchases, interests, redemptions..) -``` - -## Donation - - -If this library has helped you in any way, feel free to donate: -- **BTC**: 14ou4fMYoMVYbWEKnhADPJUNVytWQWx9HG -- **ETH**: 0xfb0ebcf8224ce561bfb06a56c3b9a43e1a4d1be2 -- **LTC**: LfHgc969RFUjnmyLn41SRDvmT146jUg9tE -- **EGLD**: erd1qk98xm2hgztvmq6s4jwtk06g6laattewp6vh20z393drzy5zzfrq0gaefh - - -## Known Issues: - - -Some endpoints are not yet provided by Binance, so they can't be implemented in this library: -- Fiat withdraws and deposits -- Locked stacking interests -- Direct purchases with debit card diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..dbaef29 --- /dev/null +++ b/README.rst @@ -0,0 +1,125 @@ +============================== +Welcome to BinanceWatch v0.1.1 +============================== + +Note +---- + + +This library is under development by EtWnn, feel free to drop your suggestions or remarks in +the discussion tab of the git repo. You are also welcome to contribute by submitting PRs. + +This is an unofficial tracker for binance accounts. I am in no way affiliated with Binance, use at +your own risk. + +**Source Code:** + https://github.com/EtWnn/BinanceWatch +**Documentation:** + https://binancewatch.readthedocs.io/en/latest/ + + +Features +-------- + + +If you used quite intensively Binance, it can take some time to retrieve everything that happened +on your account. This library is made to save locally the events of your account so that you don't +need to fetch your history from the beginning every time. + + +It currently supports: + +- Spot Trades +- Spot Crypto Deposits +- Spot Crypto Withdraws +- Spot Dividends +- Spot Dusts +- Universal Transfers + + + +- Lending Purchases +- Lending Interests +- Lending Redemptions + + + +- Cross Margin Trades +- Cross Margin Repayment +- Cross Margin Loans +- Cross Margin Interests + +Quick Tour +---------- + + +`Generate an API Key `_ in your binance account. Only read +permissions are needed. + +``BinanceWatch`` is available on `PYPI `_, install with ``pip``: + +.. code:: bash + + pip install BinanceWatch + +.. code:: python + + from BinanceWatch.BinanceManager import BinanceManager + + api_key = "" + api_secret = "" + + bm = BinanceManager(api_key, api_secret) + + # fetch the latest spot trades from Binance + bm.update_all_spot_trades() + +.. code:: bash + + Out -> fetching BIFIBUSD: 100%|██████████████████████| 1349/1349 [06:24<00:00, 3.51it/s] + +.. code:: python + + from datetime import datetime + from BinanceWatch.utils.time_utils import datetime_to_millistamp + + + start_time = datetime_to_millistamp(datetime(2018,1,1)) + + # get the locally saved spot trades made after 2018/01/01 + spot_trades = bm.db.get_trades('spot', start_time=start_time) + + +You can also call update functions at an account-type level, and it will call every update +methods related to this account-type: + +.. code:: python + + bm.update_spot() # (trades, transfers, deposits ...) + + bm.update_cross_margin() # (trades, loans, repays, interests...) + + bm.update_lending() # (purchases, interests, redemptions..) + + +Donation +-------- + + +If this library has helped you in any way, feel free to donate: + +- **BTC**: 14ou4fMYoMVYbWEKnhADPJUNVytWQWx9HG +- **ETH**: 0xfb0ebcf8224ce561bfb06a56c3b9a43e1a4d1be2 +- **LTC**: LfHgc969RFUjnmyLn41SRDvmT146jUg9tE +- **EGLD**: erd1qk98xm2hgztvmq6s4jwtk06g6laattewp6vh20z393drzy5zzfrq0gaefh + + +Known Issues: +------------- + + +Some endpoints are not yet provided by Binance, so they can't be implemented in this library: + +- Fiat withdraws and deposits +- Locked stacking history +- Direct purchases with debit card diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /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) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..9534b01 --- /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 + +if "%1" == "" goto help + +%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.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/binance_database.rst b/docs/source/binance_database.rst new file mode 100644 index 0000000..2301dfc --- /dev/null +++ b/docs/source/binance_database.rst @@ -0,0 +1,7 @@ +Binance DataBase +================ + +.. automodule:: BinanceWatch.storage.BinanceDataBase + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/source/binance_manager.rst b/docs/source/binance_manager.rst new file mode 100644 index 0000000..9172db2 --- /dev/null +++ b/docs/source/binance_manager.rst @@ -0,0 +1,6 @@ +BinanceManager +============== + +.. automodule:: BinanceWatch.BinanceManager + :members: + :undoc-members: \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..6744792 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,55 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys +sys.path.insert(0, os.path.abspath('../..')) + +# -- Project information ----------------------------------------------------- + +project = 'BinanceWatch' +copyright = '2021, EtWnn' +author = 'EtWnn' + +# The full version, including alpha/beta/rc tags +release = '0.1.1' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['sphinx.ext.viewcode', 'sphinx.ext.autodoc'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +source_suffix = ['.rst', '.md'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' # alavaster + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..4a3794c --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,20 @@ +.. include:: ../../README.rst + +Contents +========= + +.. toctree:: + :maxdepth: 2 + + overview + binance_manager + binance_database + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/source/overview.rst b/docs/source/overview.rst new file mode 100644 index 0000000..28f5198 --- /dev/null +++ b/docs/source/overview.rst @@ -0,0 +1,98 @@ +Getting Started +=============== + +Installation +------------ + +``BinanceWatch`` is available on `PYPI `_, install with ``pip``: + +.. code:: bash + + pip install BinanceWatch + +Register on Binance +------------------- + +If you are interested in this library, I assume that you have already a Binance account. If not you can +`register an account with Binance `_. + +Generate an API Key +------------------- + +To use signed account methods you are required to `create an API Key `_. +In this library, only read permissions are needed so don't forget to disabled the others restrictions (trading, withdrawal ...) + +Initialise the manager +---------------------- + +Pass your API Key and Secret to the manager + +.. code:: python + + from BinanceWatch.BinanceManager import BinanceManager + bm = BinanceManager(api_key, api_secret) + +API calls +--------- + +All the API calls to Binance are handled by the library `python-binance `_. +Don't hesitate to check their very useful `githib repo `_ and drop a star! + +Updates +------- + +The manager is mainly used to update the transactions saved locally. By calling an update method from the +manager, it will check if any transaction has been made between the last one saved locally and the current time. +The details of the update methods are in the section :doc:`binance_manager`. + +Retrievals +---------- + +Each manager has a database, which is where the results of the Binance API calls are stored. By calling +the get methods of the database, you will retrieve the history of your Binance account. See the :doc:`binance_database` +section for more details. + +Examples +-------- + +You can updates the elements by type, for example here with the crypto spot deposits: + +.. code-block:: python + + bm.update_spot_deposits() # will fetch the latest deposits not saved locally + + bm.db.get_spot_deposits() # return the deposits saved locally + +.. code-block:: bash + + [ + ('azdf5e6a1d5z', # transaction id + 1589479004000, # deposit time + 'LTC', # asset + 14.25), # amount + ... + ] + +You can also use larger update methods, that will update several types of elements. +Below the method will update every elements of a cross margin account: + +.. code-block:: python + + bm.update_cross_margin() # will fetch the latest transfers, trades, loans ... + + bm.db.get_trades(trade_type='cross_margin') + +.. code-block:: bash + + [ + (384518832, # trade_id + 1582892988052, # trade time + 'BTC', # asset + 'USDT', # ref asset + 0.0015, # asset quantity + 9011.2, # asset price to ref asset + 0.01425, # fee + 'USDT', # fee asset + 0), # is_buyer + ... + ] \ No newline at end of file diff --git a/setup.py b/setup.py index d1b338a..807a8ef 100644 --- a/setup.py +++ b/setup.py @@ -1,12 +1,12 @@ from setuptools import setup from os import path this_directory = path.abspath(path.dirname(__file__)) -with open(path.join(this_directory, 'README.md'), encoding='utf-8') as f: +with open(path.join(this_directory, 'README.rst'), encoding='utf-8') as f: long_description = f.read() setup( name='BinanceWatch', - version='0.1.0', + version='0.1.1', packages=['BinanceWatch', 'tests', 'BinanceWatch.storage', @@ -17,7 +17,7 @@ license='MIT', description='Local tracker of a binance account', long_description=long_description, - long_description_content_type='text/markdown', + long_description_content_type='text/x-rst', # 'text/markdown' install_requires=['numpy', 'tqdm', 'dateparser', 'requests', 'python-binance', 'appdirs'], keywords='binance exchange wallet save tracking history bitcoin ethereum btc eth', classifiers=[