Update docstrings

This commit is contained in:
ines 2017-05-14 01:30:29 +02:00
parent 48de4ed49f
commit 36bebe7164
2 changed files with 48 additions and 63 deletions

View File

@ -10,9 +10,9 @@ PRON_LEMMA = "-PRON-"
def depr_model_download(lang): def depr_model_download(lang):
""" """Replace en/de download modules within, warn and ownload default models.
Replace download modules within en and de with deprecation warning and
download default language model (using shortcut). lang (unicode): Language shortcut, 'en' or 'de'.
""" """
prints("The spacy.%s.download command is now deprecated. Please use " prints("The spacy.%s.download command is now deprecated. Please use "
"python -m spacy download [model name or shortcut] instead. For " "python -m spacy download [model name or shortcut] instead. For "
@ -24,6 +24,12 @@ def depr_model_download(lang):
def resolve_load_name(name, **overrides): def resolve_load_name(name, **overrides):
"""Resolve model loading if deprecated path kwarg is specified in overrides.
name (unicode): Name of model to load.
**overrides: Overrides specified in spacy.load().
RETURNS: Model name or value of path kwarg.
"""
if overrides.get('path') not in (None, False, True): if overrides.get('path') not in (None, False, True):
name = overrides.get('path') name = overrides.get('path')
prints("To load a model from a path, you can now use the first argument. " prints("To load a model from a path, you can now use the first argument. "

View File

@ -46,10 +46,8 @@ def load_lang_class(lang):
def get_data_path(require_exists=True): def get_data_path(require_exists=True):
"""Get path to spaCy data directory. """Get path to spaCy data directory.
Args: require_exists (bool): Only return path if it exists, otherwise None.
require_exists (bool): Only return path if it exists, otherwise None. RETURNS (Path or None): Data path or None.
Returns:
Path or None: Data path or None.
""" """
if not require_exists: if not require_exists:
return _data_path return _data_path
@ -60,14 +58,18 @@ def get_data_path(require_exists=True):
def set_data_path(path): def set_data_path(path):
"""Set path to spaCy data directory. """Set path to spaCy data directory.
Args: path (unicode or Path): Path to new data directory.
path (unicode or Path): Path to new data directory.
""" """
global _data_path global _data_path
_data_path = ensure_path(path) _data_path = ensure_path(path)
def ensure_path(path): def ensure_path(path):
"""Ensure string is converted to a Path.
path: Anything. If string, it's converted to Path.
RETURNS: Path or original argument.
"""
if isinstance(path, basestring_): if isinstance(path, basestring_):
return Path(path) return Path(path)
else: else:
@ -77,10 +79,8 @@ def ensure_path(path):
def resolve_model_path(name): def resolve_model_path(name):
"""Resolve a model name or string to a model path. """Resolve a model name or string to a model path.
Args: name (unicode): Package name, shortcut link or model path.
name (unicode): Package name, shortcut link or model path. RETURNS (Path): Path to model data directory.
Returns:
Path: Path to model data directory.
""" """
data_path = get_data_path() data_path = get_data_path()
if not data_path or not data_path.exists(): if not data_path or not data_path.exists():
@ -100,11 +100,8 @@ def resolve_model_path(name):
def is_package(name): def is_package(name):
"""Check if string maps to a package installed via pip. """Check if string maps to a package installed via pip.
Args: name (unicode): Name of package.
name (unicode): Name of package. RETURNS (bool): True if installed package, False if not.
Returns:
bool: True if installed package, False if not.
""" """
packages = pip.get_installed_distributions() packages = pip.get_installed_distributions()
for package in packages: for package in packages:
@ -116,10 +113,8 @@ def is_package(name):
def get_model_package_path(package_name): def get_model_package_path(package_name):
"""Get path to a model package installed via pip. """Get path to a model package installed via pip.
Args: package_name (unicode): Name of installed package.
package_name (unicode): Name of installed package. RETURNS (Path): Path to model data directory.
Returns:
Path: Path to model data directory.
""" """
# Here we're importing the module just to find it. This is worryingly # Here we're importing the module just to find it. This is worryingly
# indirect, but it's otherwise very difficult to find the package. # indirect, but it's otherwise very difficult to find the package.
@ -134,11 +129,9 @@ def get_model_package_path(package_name):
def parse_package_meta(package_path, require=True): def parse_package_meta(package_path, require=True):
"""Check if a meta.json exists in a package and return its contents. """Check if a meta.json exists in a package and return its contents.
Args: package_path (Path): Path to model package directory.
package_path (Path): Path to model package directory. require (bool): If True, raise error if no meta.json is found.
require (bool): If True, raise error if no meta.json is found. RETURNS (dict or None): Model meta.json data or None.
Returns:
dict or None: Model meta.json data or None.
""" """
location = package_path / 'meta.json' location = package_path / 'meta.json'
if location.is_file(): if location.is_file():
@ -190,11 +183,9 @@ def compile_infix_regex(entries):
def update_exc(base_exceptions, *addition_dicts): def update_exc(base_exceptions, *addition_dicts):
"""Update and validate tokenizer exceptions. Will overwrite exceptions. """Update and validate tokenizer exceptions. Will overwrite exceptions.
Args: base_exceptions (dict): Base exceptions.
base_exceptions (dict): Base exceptions. *addition_dicts (dict): Exceptions to add to the base dict, in order.
*addition_dicts (dict): Exceptions to add to the base dict, in order. RETURNS (dict): Combined tokenizer exceptions.
Returns:
dict: Combined tokenizer exceptions.
""" """
exc = dict(base_exceptions) exc = dict(base_exceptions)
for additions in addition_dicts: for additions in addition_dicts:
@ -218,12 +209,10 @@ def expand_exc(excs, search, replace):
"""Find string in tokenizer exceptions, duplicate entry and replace string. """Find string in tokenizer exceptions, duplicate entry and replace string.
For example, to add additional versions with typographic apostrophes. For example, to add additional versions with typographic apostrophes.
Args: excs (dict): Tokenizer exceptions.
excs (dict): Tokenizer exceptions. search (unicode): String to find and replace.
search (unicode): String to find and replace. replace (unicode): Replacement.
replace (unicode): Replacement. RETURNS (dict): Combined tokenizer exceptions.
Returns:
dict:
""" """
def _fix_token(token, search, replace): def _fix_token(token, search, replace):
fixed = dict(token) fixed = dict(token)
@ -267,10 +256,8 @@ def check_renamed_kwargs(renamed, kwargs):
def read_json(location): def read_json(location):
"""Open and load JSON from file. """Open and load JSON from file.
Args: location (Path): Path to JSON file.
location (Path): Path to JSON file. RETURNS (dict): Loaded JSON content.
Returns:
dict: Loaded JSON content.
""" """
with location.open('r', encoding='utf8') as f: with location.open('r', encoding='utf8') as f:
return ujson.load(f) return ujson.load(f)
@ -279,11 +266,9 @@ def read_json(location):
def get_raw_input(description, default=False): def get_raw_input(description, default=False):
"""Get user input from the command line via raw_input / input. """Get user input from the command line via raw_input / input.
Args: description (unicode): Text to display before prompt.
description (unicode): Text to display before prompt. default (unicode or False/None): Default value to display with prompt.
default (unicode or False/None): Default value to display with prompt. RETURNS (unicode): User input.
Returns:
unicode: User input.
""" """
additional = ' (default: %s)' % default if default else '' additional = ' (default: %s)' % default if default else ''
prompt = ' %s%s: ' % (description, additional) prompt = ' %s%s: ' % (description, additional)
@ -294,9 +279,8 @@ def get_raw_input(description, default=False):
def print_table(data, title=None): def print_table(data, title=None):
"""Print data in table format. """Print data in table format.
Args: data (dict or list of tuples): Label/value pairs.
data (dict or list of tuples): Label/value pairs. title (unicode or None): Title, will be printed above.
title (unicode or None): Title, will be printed above.
""" """
if isinstance(data, dict): if isinstance(data, dict):
data = list(data.items()) data = list(data.items())
@ -310,9 +294,8 @@ def print_table(data, title=None):
def print_markdown(data, title=None): def print_markdown(data, title=None):
"""Print data in GitHub-flavoured Markdown format for issues etc. """Print data in GitHub-flavoured Markdown format for issues etc.
Args: data (dict or list of tuples): Label/value pairs.
data (dict or list of tuples): Label/value pairs. title (unicode or None): Title, will be rendered as headline 2.
title (unicode or None): Title, will be rendered as headline 2.
""" """
def excl_value(value): def excl_value(value):
return Path(value).exists() # contains path (personal info) return Path(value).exists() # contains path (personal info)
@ -328,10 +311,8 @@ def print_markdown(data, title=None):
def prints(*texts, **kwargs): def prints(*texts, **kwargs):
"""Print formatted message (manual ANSI escape sequences to avoid dependency) """Print formatted message (manual ANSI escape sequences to avoid dependency)
Args: *texts (unicode): Texts to print. Each argument is rendered as paragraph.
*texts (unicode): Texts to print. Each argument is rendered as paragraph. **kwargs: 'title' becomes coloured headline. 'exits'=True performs sys exit.
**kwargs: 'title' is rendered as coloured headline. 'exits'=True performs
system exit after printing.
""" """
exits = kwargs.get('exits', False) exits = kwargs.get('exits', False)
title = kwargs.get('title', None) title = kwargs.get('title', None)
@ -345,12 +326,10 @@ def prints(*texts, **kwargs):
def _wrap(text, wrap_max=80, indent=4): def _wrap(text, wrap_max=80, indent=4):
"""Wrap text at given width using textwrap module. """Wrap text at given width using textwrap module.
Args: text (unicode): Text to wrap. If it's a Path, it's converted to string.
text (unicode): Text to wrap. If it's a Path, it's converted to string. wrap_max (int): Maximum line length (indent is deducted).
wrap_max (int): Maximum line length (indent is deducted). indent (int): Number of spaces for indentation.
indent (int): Number of spaces for indentation. RETURNS (unicode): Wrapped text.
Returns:
unicode: Wrapped text.
""" """
indent = indent * ' ' indent = indent * ' '
wrap_width = wrap_max - len(indent) wrap_width = wrap_max - len(indent)