:orphan:

:mod:`snowmobile.core.scope`
============================

.. py:module:: snowmobile.core.scope

.. autoapi-nested-parse::

   Defines the Scope for a given statement; invoked internally as the
   scope/context of statements being considered by a :class:`snowmobile.Script`
   is being altered through
   :meth:`script.filter()<snowmobile.core.script.Script.filter()>`



Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   snowmobile.core.scope.Scope



.. class:: Scope(arg: str, base: str)


   Bases: :class:`snowmobile.core.Generic`

   Handles the scope/context for :class:`Statement` objects and derived classes.

   Should never be interacted with from the user-facing API.

   .. attribute:: base

      The left-most word within a statement wrap. For **generic**
      st this will be the `keyword` and for **QA** statements
      this will be the literal word ``qa``.

      :type: str

   .. attribute:: component

      The component within a given wrap that is being evaluated; this will
      be exactly **one** of `kw`, `obj`, `anchor`, `desc`, or `nm`.

      :type: str

   .. attribute:: incl_arg

      The keyword argument that would be used to exclude a given
      component;
          *   e.g. if :attr:`component` is `kw`, :attr:`incl_arg` would
              be ``incl_kw``.

      :type: str

   .. attribute:: excl_arg

      The keyword argument that would be used to exclude a given
      component; this would be the same as the above example except
      the value would be ``excl_kw`` as opposed to ``incl_kw``.

      :type: str

   .. attribute:: fallback_to

      The default values to fall back to for :attr:`incl_arg` and
      :attr:`excl_arg` if they are not passed as a keyword argument
      by the user in :class:`Script`; defaults to including the
      :attr:`base` and excluding an empty list.

      :type: dict

    provided_args (dict):
           The set of keyword arguments provided at the time of the last call
           to :meth:`eval()`.
       check_against_args (dict):
           The set of keyword arguments checked against at the time of the
           last call to :meth:`eval()`; will use provided arguments if they
           exist and the arguments from :attr:`fallback_to` otherwise.
       is_included (bool):
           Name is included based on the results of the last call to
           :meth:`eval()`.
       is_excluded (bool):
           Name is excluded based on the results of the last call to
           :meth:`eval()`.


   Instantiates a :class:`Scope` object.

   .. method:: parse_kwargs(self, **kwargs) -> None

      Parses all filter arguments looking for those that match its base.

      Looks for include/exclude arguments within kwargs, populating
      :attr:`provided_args` with those that were provided and populates
      :attr:`check_against_args` with the same values if they were provided         and fills in defaults from :attr:`fallback_to` otherwise.

      :param \*\*kwargs: Keyword arguments passed to :class:`Script.filter()` (e.g.
                         `incl_kw`, `excl_kw`, ..)


   .. method:: matches_patterns(self, arg: str) -> bool

      Returns indication of if :attr:`base` matches a given set of patterns.

      :param arg: Will either be the value of :attr:`incl_arg` or
                  :attr:`exclude_arg`.
      :type arg: str

      Returns (bool):
          Indication of whether any matches were found.


   .. method:: included(self)
      :property:

      Name is included based on results of last :meth:`eval()`.


   .. method:: eval(self, **kwargs) -> bool

      Evaluates filter arguments and updates context accordingly.

      Updates the values of :attr:`is_included`, :attr:`is_excluded`, and
      :attr:`included`.

      :param \*\*kwargs: Keyword arguments passed to :class:`Script.filter()` (e.g.
                         `incl_kw`, `excl_kw`, ..)

      Returns (bool):
          Indicator of whether or not the statement should be
          included/excluded based on the context/keyword arguments pr.