ROS stack access
================

.. currentmodule:: rospkg

The :class:`RosStack` classes provides APIs similar to the
``rosstack`` command-line tool distributed with ROS.  Like
``rosstack``, it provides information about stack dependency
information, filesystem locations, and manifest access. The Python API
is more efficient than shelling out to ``rosstack`` as it provides
caching and other optimizations for repeated querying.

.. data:: STACK_FILE

   Name of stack manifest file, i.e. 'stack.xml'.

.. class:: RosStack([ros_root=None, [ros_package_path=None]])

   Query information about ROS stacks on the local filesystem. This
   includes information about dependencies, retrieving stack
   :class:`Manifest` instances, and determining the contents of
   stacks.  

   ``RosStack`` can be initialized with the default environment, or
   its environment configuration can be overridden with alternate
   :envvar:`ROS_ROOT` and :envvar:`ROS_PACKAGE_PATH` settings.

   NOTE: for performance reasons, ``RosPack`` caches information about
   packages.

   :param ros_root: (optional) override :envvar:`ROS_ROOT`.
   :param ros_package_path: (optional) override
     :envvar:`ROS_PACKAGE_PATH`.  To specify no
     :envvar:`ROS_PACKAGE_PATH`, use the empty string.  An assignment
     of ``None`` will use the default path.
            
   .. method:: get_ros_root() -> str

      Get the :envvar:`ROS_ROOT` configuration of this instance.

   .. method:: get_ros_package_path() -> str

      Get the :envvar:`ROS_PACKAGE_PATH` configuration of this instance.
        
   .. attribute:: ros_root

      Get the :envvar:`ROS_ROOT` configuration of this instance. Read-only.

   .. attribute:: ros_package_path

      Get the :envvar:`ROS_PACKAGE_PATH` configuration of this instance. Read-only.

   .. method:: get_manifest(name) -> Manifest

      Get the :class:`Manifest` of the specified package.

      :param name: package name, ``str``
      :raises: :exc:`InvalidManifest`
    
   .. method:: list() -> [str]

      List stacks.

      :returns: complete list of package names in ROS environment

   .. method:: get_path(name) -> str

      :param name: stack name, ``str``
      :returns: filesystem path of stack
      :raises: :exc:`ResourceNotFound`
        
   .. method:: get_direct_depends(name) -> [str]

      Get the explicit dependencies of a stack.
        
      :param name: stack name, ``str``
      :returns: list of names of direct dependencies
      :raises: :exc:`ResourceNotFound`
      :raises: :exc:`InvalidManifest`

   .. method::  get_depends(name) -> [str]

      Get explicit and implicit dependencies of a stack.

      :param name: stack name, ``str``
      :returns: list of names of dependencies.
      :raises: :exc:`InvalidManifest`        

   .. method:: packages_of(stack) -> [str]

      :returns: name of packages that are part of stack
      :raises: :exc:`ResourceNotFound` if stack cannot be located

   .. method:: get_stack_version(stack) -> str

      :param env: override environment variable dictionary
      :returns: version number of stack, or None if stack is unversioned.

.. function:: expand_to_packages(names, rospack, rosstack) -> ([str], [str])

    Expand names into a list of packages. Names can either be of packages or stacks.

    :param names: list of names of stacks or packages, ``[str]``
    :param rospack: :class:`RosPack` instance
    :param rosstack: :class:`RosStack` instance
    :returns: ([packages], [not_found]). ``expand_packages()`` returns
      two lists. The first is of packages names. The second is a list
      of names for which no matching stack or package was found. Lists
      may have duplicates.

.. function:: get_stack_version_by_dir(stack_dir) -> str

    Get stack version where stack_dir points to root directory of stack.
    
    :param env: override environment variable dictionary
    :returns: version number of stack, or None if stack is unversioned.