"""
Provide package primitives (mainly for syntax sugar)
"""
from core.pkg.find import pkg_find
from core.pkg.clone import pkg_clone

__all__ = [
    'find',
    'clone',
]

#---
# Public
#---

def find(name, version=None, local=True, remote=True):
    r"""Try to find a particular package.

    @args
    > name    (str) - exact valid package name
    > version (str) - version query string
    > local  (bool) - enable local search
    > remote (bool) - enable remote search

    @return
    > a list of all matched package dictionnary :
        [
            {
                'name'    : <package name>,
                'version' : [
                    <list of all available (or matched) version>
                    ...
                ]
        ]
    > None if error
    """
    return pkg_find(name, version, local, remote)

def clone(name, version=None, prefix=None, confirm=False):
    r""" Clone package with appropriate version

    This function will try to find the wanted package with the appropriate
    version then clone it into <`prefix`> if provided or in the internal
    <config.pkg.home_prefix> configuration key otherwise.

    The `name` should be a valid package name. However, the `version` argument
    can contains version operation like carret (^), tilde (~) and start (*) as
    described in <vxsdk/core/pkg/version.py>

    @args
    > prefix   (str) - clone path prefix
    > name     (str) - exact valid package name
    > version  (str) - version query string
    > confirm (bool) - display user input to confirm the clone

    @return
    > the package path if successfully cloned, None otherwise
    """
    return pkg_clone(name, version, prefix, confirm)