docs: call builder

docs/api.rst

@@ -22,6 +22,87 @@ Asset
    :members:
    :inherited-members:
 
+Call Builder
+^^^^^^^^^^^^
+
+BaseCallBuilder
+-------------------
+.. autoclass:: stellar_sdk.call_builder.BaseCallBuilder
+   :members:
+   :inherited-members:
+
+AccountsCallBuilder
+-------------------
+.. autoclass:: stellar_sdk.call_builder.AccountsCallBuilder
+   :members:
+   :inherited-members:
+
+AssetsCallBuilder
+-----------------
+.. autoclass:: stellar_sdk.call_builder.AssetsCallBuilder
+   :members:
+   :inherited-members:
+
+EffectsCallBuilder
+------------------
+.. autoclass:: stellar_sdk.call_builder.EffectsCallBuilder
+   :members:
+   :inherited-members:
+
+LedgersCallBuilder
+------------------
+.. autoclass:: stellar_sdk.call_builder.LedgersCallBuilder
+   :members:
+   :inherited-members:
+
+OffersCallBuilder
+---------------------
+.. autoclass:: stellar_sdk.call_builder.OffersCallBuilder
+   :members:
+   :inherited-members:
+
+OperationsCallBuilder
+---------------------
+.. autoclass:: stellar_sdk.call_builder.OperationsCallBuilder
+   :members:
+   :inherited-members:
+
+OrderbookCallBuilder
+--------------------
+.. autoclass:: stellar_sdk.call_builder.OrderbookCallBuilder
+   :members:
+   :inherited-members:
+
+PathsCallBuilder
+----------------
+.. autoclass:: stellar_sdk.call_builder.PathsCallBuilder
+   :members:
+   :inherited-members:
+
+PaymentsCallBuilder
+-------------------
+.. autoclass:: stellar_sdk.call_builder.PaymentsCallBuilder
+   :members:
+   :inherited-members:
+
+TradeAggregationsCallBuilder
+----------------------------
+.. autoclass:: stellar_sdk.call_builder.TradeAggregationsCallBuilder
+   :members:
+   :inherited-members:
+
+TradesCallBuilder
+-----------------
+.. autoclass:: stellar_sdk.call_builder.TradesCallBuilder
+   :members:
+   :inherited-members:
+
+TransactionsCallBuilder
+-----------------------
+.. autoclass:: stellar_sdk.call_builder.TransactionsCallBuilder
+   :members:
+   :inherited-members:
+
 Keypair
 ^^^^^^^
 
@@ -151,8 +232,15 @@ Price
    :members:
    :inherited-members:
 
+Server
+^^^^^^
+
+.. autoclass:: stellar_sdk.server.Server
+   :members:
+   :inherited-members:
+
 Signer
-^^^^^^^^^^
+^^^^^^
 
 .. autoclass:: stellar_sdk.signer.Signer
    :members:

stellar_sdk/call_builder/__init__.py

@@ -3,6 +3,7 @@
 from .base_call_builder import BaseCallBuilder
 from .effects_call_builder import EffectsCallBuilder
 from .ledgers_call_builder import LedgersCallBuilder
+from .offers_call_builder import OffersCallBuilder
 from .operations_call_builder import OperationsCallBuilder
 from .orderbook_call_builder import OrderbookCallBuilder
 from .paths_call_builder import PathsCallBuilder
@@ -17,6 +18,7 @@
     "BaseCallBuilder",
     "EffectsCallBuilder",
     "LedgersCallBuilder",
+    "OffersCallBuilder",
     "OperationsCallBuilder",
     "OrderbookCallBuilder",
     "PathsCallBuilder",

stellar_sdk/call_builder/accounts_call_builder.py

@@ -6,12 +6,27 @@
 
 
 class AccountsCallBuilder(BaseCallBuilder):
+    """ Creates a new :class:`AccountsCallBuilder` pointed to server defined by horizon_url.
+    Do not create this object directly, use :func:`stellar_sdk.server.Server.accounts`.
+
+    :param horizon_url: Horizon server URL.
+    :param client: The client instance used to send request.
+    """
+
     def __init__(
         self, horizon_url, client: Union[BaseAsyncClient, BaseSyncClient]
     ) -> None:
         super().__init__(horizon_url, client)
         self.endpoint = "accounts"
 
     def account_id(self, account_id: str) -> "AccountsCallBuilder":
+        """Returns information and links relating to a single account.
+        The balances section in the returned JSON will also list all the trust lines this account has set up.
+
+        See `Account Details <https://www.stellar.org/developers/horizon/reference/endpoints/accounts-single.html>`_
+
+        :param account_id: account id, for example: `GDGQVOKHW4VEJRU2TETD6DBRKEO5ERCNF353LW5WBFW3JJWQ2BRQ6KDD`
+        :return: current AccountCallBuilder instance
+        """
         self.endpoint = "accounts/{account_id}".format(account_id=account_id)
         return self

stellar_sdk/call_builder/assets_call_builder.py

@@ -6,16 +6,36 @@
 
 
 class AssetsCallBuilder(BaseCallBuilder):
+    """ Creates a new :class:`AssetsCallBuilder` pointed to server defined by horizon_url.
+    Do not create this object directly, use :func:`stellar_sdk.server.Server.assets`.
+
+    See `All Assets <https://www.stellar.org/developers/horizon/reference/endpoints/assets-all.html>`_
+
+    :param horizon_url: Horizon server URL.
+    :param client: The client instance used to send request.
+    """
+
     def __init__(
         self, horizon_url: str, client: Union[BaseAsyncClient, BaseSyncClient]
     ) -> None:
         super().__init__(horizon_url, client)
         self.endpoint = "assets"
 
     def for_code(self, asset_code: str) -> "AssetsCallBuilder":
+        """ This endpoint filters all assets by the asset code.
+
+        :param asset_code: asset code, for example: `USD`
+        :return: current AssetCallBuilder instance
+        """
         self._add_query_param("asset_code", asset_code)
         return self
 
     def for_issuer(self, asset_issuer: str) -> "AssetsCallBuilder":
+        """ This endpoint filters all assets by the asset issuer.
+
+        :param asset_issuer: asset issuer,
+            for example: `GDGQVOKHW4VEJRU2TETD6DBRKEO5ERCNF353LW5WBFW3JJWQ2BRQ6KDD`
+        :return: current AssetCallBuilder instance
+        """
         self._add_query_param("asset_issuer", asset_issuer)
         return self

stellar_sdk/call_builder/base_call_builder.py

@@ -7,6 +7,14 @@
 
 
 class BaseCallBuilder:
+    """Creates a new :class:`BaseCallBuilder` pointed to server defined by horizon_url.
+
+    This is an **abstract** class. Do not create this object directly, use :class:`stellar_sdk.server.Server` class.
+
+    :param horizon_url: Horizon server URL.
+    :param client: The client instance used to send request.
+    """
+
     def __init__(
         self, horizon_url: str, client: Union[BaseAsyncClient, BaseSyncClient]
     ) -> None:
@@ -21,6 +29,11 @@ def __init__(
         self.endpoint = ""
 
     def call(self) -> Union[Response, Coroutine[Any, Any, Response]]:
+        """Triggers a HTTP request using this builder's current configuration.
+
+        :return: If it is called synchronous, the response will be returned. If
+            it is called asynchronously, it will return Coroutine.
+        """
         if self.__async:
             return self.__call_async()
         else:
@@ -35,6 +48,15 @@ async def __call_async(self) -> Response:
         return await self.client.get(url, self.params)
 
     def stream(self):
+        """Creates an EventSource that listens for incoming messages from the server.
+
+        See `Horizon Response Format <https://www.stellar.org/developers/horizon/reference/responses.html>`_
+
+        See `MDN EventSource <https://developer.mozilla.org/en-US/docs/Web/API/EventSource>`_
+
+        :return: If it is called synchronous, it will return `Generator`, If
+            it is called asynchronously, it will return `AsyncGenerator`.
+        """
         if self.__async:
             return self.__stream_async()
         else:
@@ -51,14 +73,33 @@ def __stream_sync(self):
         return self.client.stream(url, self.params)
 
     def cursor(self, cursor):
+        """Sets `cursor` parameter for the current call. Returns the CallBuilder object on which this method has been called.
+
+        See `Paging <https://www.stellar.org/developers/horizon/reference/paging.html>`_
+
+        :param cursor: A cursor is a value that points to a specific location in a collection of resources.
+        :return: current CallBuilder instance
+        """
         self._add_query_param("cursor", cursor)
         return self
 
     def limit(self, limit):
+        """Sets `limit` parameter for the current call. Returns the CallBuilder object on which this method has been called.
+
+        See `Paging <https://www.stellar.org/developers/horizon/reference/paging.html>`_
+
+        :param limit: Number of records the server should return.
+        :return:
+        """
         self._add_query_param("limit", limit)
         return self
 
     def order(self, desc=True):
+        """Sets `order` parameter for the current call. Returns the CallBuilder object on which this method has been called.
+
+        :param desc: Sort direction, `True` to get desc sort direction, the default setting is `True`.
+        :return: current CallBuilder instance
+        """
         order = "asc"
         if desc:
             order = "desc"

stellar_sdk/call_builder/effects_call_builder.py

@@ -6,27 +6,66 @@
 
 
 class EffectsCallBuilder(BaseCallBuilder):
+    """ Creates a new :class:`EffectsCallBuilder` pointed to server defined by horizon_url.
+    Do not create this object directly, use :func:`stellar_sdk.server.Server.effects`.
+
+    See `All Effects <https://www.stellar.org/developers/horizon/reference/endpoints/effects-all.html>`_
+
+    :param horizon_url: Horizon server URL.
+    :param client: The client instance used to send request.
+    """
+
     def __init__(
         self, horizon_url: str, client: Union[BaseAsyncClient, BaseSyncClient]
     ) -> None:
         super().__init__(horizon_url, client)
         self.endpoint = "effects"
 
     def for_account(self, account_id: str) -> "EffectsCallBuilder":
+        """This endpoint represents all effects that changed a given account. It will return relevant
+        effects from the creation of the account to the current ledger.
+
+        See `Effects for Account <https://www.stellar.org/developers/horizon/reference/endpoints/effects-all.html>`_
+
+        :param account_id: account id, for example: `GDGQVOKHW4VEJRU2TETD6DBRKEO5ERCNF353LW5WBFW3JJWQ2BRQ6KDD`
+        :return: this EffectCallBuilder instance
+        """
         self.endpoint = "accounts/{account_id}/effects".format(account_id=account_id)
         return self
 
     def for_ledger(self, sequence: Union[int, str]) -> "EffectsCallBuilder":
+        """Effects are the specific ways that the ledger was changed by any operation.
+        This endpoint represents all effects that occurred in the given ledger.
+
+        See `Effects for Ledger <https://www.stellar.org/developers/horizon/reference/endpoints/effects-for-account.html>`_
+
+        :param sequence: ledger sequence
+        :return: this EffectCallBuilder instance
+        """
         self.endpoint = "ledgers/{sequence}/effects".format(sequence=sequence)
         return self
 
     def for_transaction(self, transaction_hash: str) -> "EffectsCallBuilder":
+        """This endpoint represents all effects that occurred as a result of a given transaction.
+
+        See `Effects for Transaction <https://www.stellar.org/developers/horizon/reference/endpoints/effects-for-transaction.html>`_
+
+        :param transaction_hash: transaction hash
+        :return: this EffectCallBuilder instance
+        """
         self.endpoint = "transactions/{transaction_hash}/effects".format(
             transaction_hash=transaction_hash
         )
         return self
 
     def for_operation(self, operation_id: Union[int, str]) -> "EffectsCallBuilder":
+        """This endpoint represents all effects that occurred as a result of a given operation.
+
+        See `Effects for Operation <https://www.stellar.org/developers/horizon/reference/endpoints/effects-for-operation.html>`_
+
+        :param operation_id: operation ID
+        :return: this EffectCallBuilder instance
+        """
         self.endpoint = "operations/{operation_id}/effects".format(
             operation_id=operation_id
         )

stellar_sdk/call_builder/ledgers_call_builder.py

@@ -6,12 +6,28 @@
 
 
 class LedgersCallBuilder(BaseCallBuilder):
+    """ Creates a new :class:`LedgersCallBuilder` pointed to server defined by horizon_url.
+    Do not create this object directly, use :func:`stellar_sdk.server.Server.ledgers`.
+
+    See `All Ledgers <https://www.stellar.org/developers/horizon/reference/endpoints/ledgers-all.html>`_
+
+    :param horizon_url: Horizon server URL.
+    :param client: The client instance used to send request.
+    """
+
     def __init__(
         self, horizon_url: str, client: Union[BaseAsyncClient, BaseSyncClient]
     ) -> None:
         super().__init__(horizon_url, client)
         self.endpoint = "ledgers"
 
     def ledger(self, sequence: Union[int, str]) -> "LedgersCallBuilder":
+        """Provides information on a single ledger.
+
+        See `Ledger Details <https://www.stellar.org/developers/horizon/reference/endpoints/ledgers-single.html>`_
+
+        :param sequence: Ledger sequence
+        :return: current LedgerCallBuilder instance
+        """
         self.endpoint = "ledgers/{sequence}".format(sequence=sequence)
         return self

stellar_sdk/call_builder/offers_call_builder.py

@@ -6,6 +6,16 @@
 
 
 class OffersCallBuilder(BaseCallBuilder):
+    """ Creates a new :class:`OffersCallBuilder` pointed to server defined by horizon_url.
+    Do not create this object directly, use :func:`stellar_sdk.server.Server.offers`.
+
+    See `Offers for Account <https://www.stellar.org/developers/horizon/reference/endpoints/offers-for-account.html>`_
+
+    :param horizon_url: Horizon server URL.
+    :param client: The client instance used to send request.
+    :param account_id: Account ID.
+    """
+
     def __init__(
         self,
         horizon_url: str,