Skip to content

Commit

Permalink
DOC: Updated type stubs for next release
Browse files Browse the repository at this point in the history
  • Loading branch information
@richafrank
richafrank committed Jul 22, 2020
1 parent b46a801 commit d451f0e
Show file tree
Hide file tree
Showing 2 changed files with 63 additions and 48 deletions.
7 changes: 4 additions & 3 deletions etc/gen_type_stubs.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,12 +21,12 @@ def main():
from zipline.utils.events import EventRule
from zipline.utils.security_list import SecurityList
"""))

# Sort to generate consistent stub file:
for api_func in sorted(TradingAlgorithm.all_api_methods(),
key=attrgetter('__name__')):
stub.write('\n')
sig = inspect._signature_bound_method(inspect.signature(api_func))

indent = ' ' * 4
Expand All @@ -35,10 +35,11 @@ def {func_name}{func_sig}:
"""'''.format(func_name=api_func.__name__,
func_sig=sig)))
stub.write(dedent('{indent}{func_doc}'.format(
func_doc=api_func.__doc__ or '\n', # handle None docstring
# `or '\n'` is to handle a None docstring:
func_doc=dedent(api_func.__doc__.lstrip()) or '\n',
indent=indent,
)))
stub.write('{indent}"""\n\n'.format(indent=indent))
stub.write('{indent}"""\n'.format(indent=indent))


if __name__ == '__main__':
Expand Down
104 changes: 59 additions & 45 deletions zipline/api.pyi
View file
Original file line number Diff line number Diff line change
Expand Up @@ -81,11 +81,11 @@ def continuous_future(root_symbol_str, offset=0, roll='volume', adjustment='mul'
Returns
-------
continuous_future : ContinuousFuture
continuous_future : zipline.assets.ContinuousFuture
The continuous future specifier.
"""

def fetch_csv(url, pre_func=None, post_func=None, date_column='date', date_format=None, timezone='UTC', symbol=None, mask=True, symbol_column=None, special_params_checker=None, **kwargs):
def fetch_csv(url, pre_func=None, post_func=None, date_column='date', date_format=None, timezone='UTC', symbol=None, mask=True, symbol_column=None, special_params_checker=None, country_code=None, **kwargs):
"""Fetch a csv from a remote url and register the data so that it is
queryable from the ``data`` object.
Expand Down Expand Up @@ -120,6 +120,8 @@ def fetch_csv(url, pre_func=None, post_func=None, date_column='date', date_forma
argument is the name of the column in the preprocessed dataframe
containing the symbols. This will be used along with the date
information to map the sids in the asset finder.
country_code : str, optional
Country code to use to disambiguate symbol lookups.
**kwargs
Forwarded to :func:`pandas.read_csv`.
Expand All @@ -139,7 +141,7 @@ def future_symbol(symbol):
Returns
-------
future : Future
future : zipline.assets.Future
The future that trades with the name ``symbol``.
Raises
Expand All @@ -149,18 +151,17 @@ def future_symbol(symbol):
"""

def get_datetime(tz=None):
"""
Returns the current simulation datetime.
"""Returns the current simulation datetime.
Parameters
----------
tz : tzinfo or str, optional
The timezone to return the datetime in. This defaults to utc.
Parameters
----------
tz : tzinfo or str, optional
The timezone to return the datetime in. This defaults to utc.
Returns
-------
dt : datetime
The current simulation datetime converted to ``tz``.
Returns
-------
dt : datetime
The current simulation datetime converted to ``tz``.
"""

def get_environment(field='platform'):
Expand Down Expand Up @@ -240,12 +241,12 @@ def history(bar_count, frequency, field, ffill=True):
"""

def order(asset, amount, limit_price=None, stop_price=None, style=None):
"""Place an order.
"""Place an order for a fixed number of shares.
Parameters
----------
asset : Asset
The asset that this order is for.
The asset to be ordered.
amount : int
The amount of shares to order. If ``amount`` is positive, this is
the number of shares to buy or cover. If ``amount`` is negative,
Expand Down Expand Up @@ -471,25 +472,21 @@ def order_target_value(asset, target, limit_price=None, stop_price=None, style=N
"""

def order_value(asset, value, limit_price=None, stop_price=None, style=None):
"""Place an order by desired value rather than desired number of
shares.
"""Place an order for a fixed amount of money.
Equivalent to ``order(asset, value / data.current(asset, 'price'))``.
Parameters
----------
asset : Asset
The asset that this order is for.
The asset to be ordered.
value : float
If the requested asset exists, the requested value is
divided by its price to imply the number of shares to transact.
If the Asset being ordered is a Future, the 'value' calculated
is actually the exposure, as Futures have no 'value'.
value > 0 :: Buy/Cover
value < 0 :: Sell/Short
Amount of value of ``asset`` to be transacted. The number of shares
bought or sold will be equal to ``value / current_price``.
limit_price : float, optional
The limit price for the order.
Limit price for the order.
stop_price : float, optional
The stop price for the order.
Stop price for the order.
style : ExecutionStyle
The execution style for the order.
Expand All @@ -511,13 +508,12 @@ def order_value(asset, value, limit_price=None, stop_price=None, style=None):
"""

def pipeline_output(name):
"""Get the results of the pipeline that was attached with the name:
``name``.
"""Get results of the pipeline attached by with name ``name``.
Parameters
----------
name : str
Name of the pipeline for which results are requested.
Name of the pipeline from which to fetch results.
Returns
-------
Expand Down Expand Up @@ -552,20 +548,24 @@ def record(*args, **kwargs):
"""

def schedule_function(func, date_rule=None, time_rule=None, half_days=True, calendar=None):
"""Schedules a function to be called according to some timed rules.
"""Schedule a function to be called repeatedly in the future.
Parameters
----------
func : callable[(context, data) -> None]
The function to execute when the rule is triggered.
date_rule : EventRule, optional
The rule for the dates to execute this function.
time_rule : EventRule, optional
The rule for the times to execute this function.
func : callable
The function to execute when the rule is triggered. ``func`` should
have the same signature as ``handle_data``.
date_rule : zipline.utils.events.EventRule, optional
Rule for the dates on which to execute ``func``. If not
passed, the function will run every trading day.
time_rule : zipline.utils.events.EventRule, optional
Rule for the time at which to execute ``func``. If not passed, the
function will execute at the end of the first market minute of the
day.
half_days : bool, optional
Should this rule fire on half days?
Should this rule fire on half days? Default is True.
calendar : Sentinel, optional
Calendar used to reconcile date and time rules.
Calendar used to compute rules that depend on the trading calendar.
See Also
--------
Expand All @@ -591,7 +591,7 @@ def set_benchmark(benchmark):
Parameters
----------
benchmark : Asset
benchmark : zipline.assets.Asset
The asset to set as the new benchmark.
Notes
Expand Down Expand Up @@ -624,6 +624,11 @@ def set_commission(us_equities=None, us_futures=None):
us_futures : FutureCommissionModel
The commission model to use for trading US futures.
Notes
-----
This function can only be called during
:func:`~zipline.api.initialize`.
See Also
--------
:class:`zipline.finance.commission.PerShare`
Expand Down Expand Up @@ -728,6 +733,11 @@ def set_slippage(us_equities=None, us_futures=None):
us_futures : FutureSlippageModel
The slippage model to use for trading US futures.
Notes
-----
This function can only be called during
:func:`~zipline.api.initialize`.
See Also
--------
:class:`zipline.finance.slippage.SlippageModel`
Expand All @@ -754,7 +764,7 @@ def sid(sid):
Returns
-------
asset : Asset
asset : zipline.assets.Asset
The asset with the given ``sid``.
Raises
Expand All @@ -763,17 +773,19 @@ def sid(sid):
When a requested ``sid`` does not map to any asset.
"""

def symbol(symbol_str):
def symbol(symbol_str, country_code=None):
"""Lookup an Equity by its ticker symbol.
Parameters
----------
symbol_str : str
The ticker symbol for the equity to lookup.
country_code : str or None, optional
A country to limit symbol searches to.
Returns
-------
equity : Equity
equity : zipline.assets.Equity
The equity that held the ticker symbol on the current
symbol lookup date.
Expand All @@ -787,17 +799,19 @@ def symbol(symbol_str):
:func:`zipline.api.set_symbol_lookup_date`
"""

def symbols(*args):
def symbols(*args, **kwargs):
"""Lookup multuple Equities as a list.
Parameters
----------
*args : iterable[str]
The ticker symbols to lookup.
country_code : str or None, optional
A country to limit symbol searches to.
Returns
-------
equities : list[Equity]
equities : list[zipline.assets.Equity]
The equities that held the given ticker symbols on the current
symbol lookup date.
Expand Down

0 comments on commit d451f0e

Please sign in to comment.