DOC: Add return type annotations for buy and sell methods (#975)

* ENH: Explicitly import annotations everywhere

Type annotations are now explicitly imported
from `__future__` to allow forward references
and postponed evaluation (faster import time).
See PEP 563 for details.

* ENH: add return type annotations for `buy`/`sell`

The return type annotations are now added for `buy`
and `sell` methods. The documentation is updated to
mention that the `Order` is returned. Now it should
be crystal clear how to cancel a non-executed order.

This should address #957.

backtesting/_plotting.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import os
 import re
 import sys

backtesting/_stats.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from typing import TYPE_CHECKING, List, Union
 
 import numpy as np

backtesting/_util.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import warnings
 from numbers import Number
 from typing import Dict, List, Optional, Sequence, Union, cast

backtesting/backtesting.py

@@ -5,6 +5,9 @@
 
     from backtesting import Backtest, Strategy
 """
+
+from __future__ import annotations
+
 import multiprocessing as mp
 import os
 import sys
@@ -200,9 +203,10 @@ def buy(self, *,
             stop: Optional[float] = None,
             sl: Optional[float] = None,
             tp: Optional[float] = None,
-            tag: object = None):
+            tag: object = None) -> 'Order':
         """
-        Place a new long order. For explanation of parameters, see `Order` and its properties.
+        Place a new long order and return it. For explanation of parameters, see `Order`
+        and its properties.
 
         See `Position.close()` and `Trade.close()` for closing existing positions.
 
@@ -218,9 +222,10 @@ def sell(self, *,
              stop: Optional[float] = None,
              sl: Optional[float] = None,
              tp: Optional[float] = None,
-             tag: object = None):
+             tag: object = None) -> 'Order':
         """
-        Place a new short order. For explanation of parameters, see `Order` and its properties.
+        Place a new short order and return it. For explanation of parameters, see `Order`
+        and its properties.
 
         See also `Strategy.buy()`.
 
@@ -745,7 +750,7 @@ def new_order(self,
                   tp: Optional[float] = None,
                   tag: object = None,
                   *,
-                  trade: Optional[Trade] = None):
+                  trade: Optional[Trade] = None) -> Order:
         """
         Argument size indicates whether the order is long or short
         """

backtesting/lib.py

@@ -11,6 +11,8 @@
 [issue tracker]: https://github.com/kernc/backtesting.py
 """
 
+from __future__ import annotations
+
 from collections import OrderedDict
 from inspect import currentframe
 from itertools import compress

backtesting/test/__init__.py

@@ -1,4 +1,7 @@
 """Data and utilities for testing."""
+
+from __future__ import annotations
+
 import pandas as pd