"""Functionality related with node paths in a PyTables file.

Variables
=========

`__docformat`__
    The format of documentation strings in this module.

"""

import re
import keyword
import warnings

from .exceptions import NaturalNameWarning

__docformat__ = "reStructuredText"
"""The format of documentation strings in this module."""


_python_id_re = re.compile("^[a-zA-Z_][a-zA-Z0-9_]*$")
"""Python identifier regular expression."""

_reserved_id_re = re.compile("^_[cfgv]_")
"""PyTables reserved identifier regular expression.

- c: class variables
- f: class public methods
- g: class private methods
- v: instance variables
"""

_hidden_name_re = re.compile("^_[pi]_")
"""Nodes with a name *matching* this expression are considered hidden.

For instance, ``name`` would be visible while ``_i_name`` would not.
"""

_hidden_path_re = re.compile("/_[pi]_")
"""Nodes with a path *containing* this expression are considered hidden.

For instance, a node with a pathname like ``/a/b/c`` would be visible
while nodes with pathnames like ``/a/c/_i_x`` or ``/a/_p_x/y`` would
not.
"""

_warn_info = (
    "you will not be able to use natural naming to access this object; "
    "using ``getattr()`` will still work, though"
)
"""Warning printed when a name will not be reachable through natural naming"""


def check_attribute_name(name: str) -> None:
    """Check the validity of the `name` of an attribute in AttributeSet.

    If the name is not valid, a ``ValueError`` is raised.  If it is
    valid but it can not be used with natural naming, a
    `NaturalNameWarning` is issued.

    >>> warnings.simplefilter("ignore")
    >>> check_attribute_name('a')
    >>> check_attribute_name('a_b')
    >>> check_attribute_name('a:b')         # NaturalNameWarning
    >>> check_attribute_name('/a/b')        # NaturalNameWarning
    >>> check_attribute_name('/')           # NaturalNameWarning
    >>> check_attribute_name('.')           # NaturalNameWarning
    >>> check_attribute_name('__members__')
    Traceback (most recent call last):
     ...
    ValueError: ``__members__`` is not allowed as an object name
    >>> check_attribute_name(1)
    Traceback (most recent call last):
     ...
    TypeError: object name is not a string: 1
    >>> check_attribute_name('')
    Traceback (most recent call last):
     ...
    ValueError: the empty string is not allowed as an object name
    """
    if not isinstance(name, str):  # Python >= 2.3
        raise TypeError(f"object name is not a string: {name!r}")

    if name == "":
        raise ValueError("the empty string is not allowed as an object name")

    # Check whether `name` is a valid Python identifier.
    if not _python_id_re.match(name):
        warnings.warn(
            "object name is not a valid Python identifier: %r; "
            "it does not match the pattern ``%s``; %s"
            % (name, _python_id_re.pattern, _warn_info),
            NaturalNameWarning,
            stacklevel=2,
        )
        return

    # However, Python identifiers and keywords have the same form.
    if keyword.iskeyword(name):
        warnings.warn(
            f"object name is a Python keyword: {name!r}; {_warn_info}",
            NaturalNameWarning,
            stacklevel=2,
        )
        return

    # Still, names starting with reserved prefixes are not allowed.
    if _reserved_id_re.match(name):
        raise ValueError(
            "object name starts with a reserved prefix: %r; "
            "it matches the pattern ``%s``" % (name, _reserved_id_re.pattern)
        )

    # ``__members__`` is the only exception to that rule.
    if name == "__members__":
        raise ValueError("``__members__`` is not allowed as an object name")


def check_name_validity(name: str) -> None:
    """Check the validity of the `name` of a Node object.

    Validity of Node names is more limited than attribute names.

    If the name is not valid, a ``ValueError`` is raised.  If it is
    valid but it can not be used with natural naming, a
    `NaturalNameWarning` is issued.

    >>> warnings.simplefilter("ignore")
    >>> check_name_validity('a')
    >>> check_name_validity('a_b')
    >>> check_name_validity('a:b')          # NaturalNameWarning
    >>> check_name_validity('/a/b')
    Traceback (most recent call last):
     ...
    ValueError: the ``/`` character is not allowed in object names: '/a/b'
    >>> check_name_validity('.')
    Traceback (most recent call last):
     ...
    ValueError: ``.`` is not allowed as an object name
    >>> check_name_validity('')
    Traceback (most recent call last):
     ...
    ValueError: the empty string is not allowed as an object name

    """
    check_attribute_name(name)

    # Check whether `name` is a valid HDF5 name.
    # http://hdfgroup.org/HDF5/doc/UG/03_Model.html#Structure
    if name == ".":
        raise ValueError("``.`` is not allowed as an object name")
    elif "/" in name:
        raise ValueError(
            "the ``/`` character is not allowed " "in object names: %r" % name
        )


def join_path(parentpath: str, name: str) -> str:
    """Join a *canonical* `parentpath` with a *non-empty* `name`.

    .. versionchanged:: 3.0
       The *parentPath* parameter has been renamed into *parentpath*.

    >>> join_path('/', 'foo')
    '/foo'
    >>> join_path('/foo', 'bar')
    '/foo/bar'
    >>> join_path('/foo', '/foo2/bar')
    '/foo/foo2/bar'
    >>> join_path('/foo', '/')
    '/foo'

    """
    if name.startswith("./"):  # Support relative paths (mainly for links)
        name = name[2:]
    if parentpath == "/" and name.startswith("/"):
        pstr = "%s" % name
    elif parentpath == "/" or name.startswith("/"):
        pstr = f"{parentpath}{name}"
    else:
        pstr = f"{parentpath}/{name}"
    if pstr.endswith("/"):
        pstr = pstr[:-1]
    return pstr


def split_path(path: str) -> (str, str):
    """Split a *canonical* `path` into a parent path and a node name.

    The result is returned as a tuple.  The parent path does not
    include a trailing slash.

    >>> split_path('/')
    ('/', '')
    >>> split_path('/foo/bar')
    ('/foo', 'bar')

    """
    lastslash = path.rfind("/")
    ppath = path[:lastslash]
    name = path[lastslash + 1 :]

    if ppath == "":
        ppath = "/"

    return (ppath, name)


def isvisiblename(name: str) -> bool:
    """Return `True` if  `name` makes the named node visible."""
    return _hidden_name_re.match(name) is None


def isvisiblepath(path: str) -> bool:
    """Return `True` if `path` makes the named node visible."""
    return _hidden_path_re.search(path) is None


def _test() -> None:
    """Run ``doctest`` on this module."""
    import doctest

    doctest.testmod()


if __name__ == "__main__":
    _test()