.. _ImportConstraintsRule:

=====================
ImportConstraintsRule
=====================

Rule to impose import constraints in certain directories to improve runtime performance.
The directories specified in the ImportConstraintsRule setting in the ``.fixit.config.yaml`` file's
``rule_config`` section can impose import constraints for that directory and its children as follows::

    rule_config:
        ImportConstraintsRule:
            dir_under_repo_root:
                rules: [
                    ["module_under_repo_root", "allow"],
                    ["another_module_under_repo_root, "deny"],
                    ["*", "deny"]
                ]
                ignore_tests: True
                ignore_types: True
                message: "'{imported}' cannot be imported from within '{current_file}'."

Each rule under ``rules`` is evaluated in order from top to bottom and the last rule for each directory
should be a wildcard rule. Rules can be ``"allow"``, ``"deny"``, ``"allow_global"``, ``"allow_local"``,
``"deny_global"`` or ``"deny_local"``.
``ignore_tests`` and `ignore_types` should carry boolean values and can be omitted. They are both set to
`True` by default.
If ``ignore_types`` is True, this rule will ignore imports inside ``if TYPE_CHECKING`` blocks since those
imports do not have an affect on runtime performance.
If ``ignore_tests`` is True, this rule will not lint any files found in a testing module.
If ``message`` is passed, it must be a string containing a custom message. The string will be formatted
passing ``imported`` and ``current_file`` variables to be used if needed, with the symbol being imported
and the current file, respectively.

-------
Message
-------
According to the settings for this directory in the .fixit.config.yaml configuration file, '{imported}' cannot be imported from within '{current_file}'.

---------------
Has Autofix: No
---------------

-------------------
VALID Code Examples
-------------------

# 1:







.. code-block:: python

            import common




# 2:


config:

.. code-block:: yaml

    rule_config:
      ImportConstraintsRule:
        some_dir:
          rules:
          - - '*'
            - allow





path: :file:`some_dir/file.py`

.. code-block:: python

            import common




# 3:


config:

.. code-block:: yaml

    rule_config:
      ImportConstraintsRule:
        some_dir:
          rules:
          - - common
            - allow
          - - '*'
            - deny





path: :file:`some_dir/file.py`

.. code-block:: python

            import common




.. container:: toggle


    # 4:


    config:

    .. code-block:: yaml

        rule_config:
          ImportConstraintsRule:
            some_dir:
              rules:
              - - common
                - allow
              - - '*'
                - deny





    path: :file:`some_dir/file.py`

    .. code-block:: python

                from common.foo import bar





    # 5:


    config:

    .. code-block:: yaml

        rule_config:
          ImportConstraintsRule:
            some_dir:
              rules:
              - - common.foo.bar
                - allow
              - - common
                - deny
              - - '*'
                - deny





    path: :file:`some_dir/file.py`

    .. code-block:: python

                from common.foo import bar





    # 6:


    config:

    .. code-block:: yaml

        rule_config:
          ImportConstraintsRule:
            some_dir:
              rules:
              - - '*'
                - deny





    path: :file:`some_dir/file.py`

    .. code-block:: python

                import ast





    # 7:


    config:

    .. code-block:: yaml

        rule_config:
          ImportConstraintsRule:
            .:
              rules:
              - - common.safe
                - allow
              - - '*'
                - deny





    path: :file:`common/safe/file.py`

    .. code-block:: python

                from . import module





    # 8:


    config:

    .. code-block:: yaml

        rule_config:
          ImportConstraintsRule:
            common:
              rules:
              - - common.safe
                - allow
              - - '*'
                - deny





    path: :file:`common/unsafe/file.py`

    .. code-block:: python

                from ..safe import module





    # 9:


    config:

    .. code-block:: yaml

        rule_config:
          ImportConstraintsRule:
            .:
              rules:
              - - '*'
                - deny





    path: :file:`file.py`

    .. code-block:: python

                from ....................................... import module





    # 10:


    config:

    .. code-block:: yaml

        rule_config:
          ImportConstraintsRule:
            dir_1:
              rules:
              - - common.foo.bar
                - deny
              - - '*'
                - deny
            dir_1/dir_2:
              rules:
              - - common.foo.bar
                - allow
              - - '*'
                - deny





    path: :file:`dir_1/dir_2/file.py`

    .. code-block:: python

                from common.foo import bar





    # 11:


    config:

    .. code-block:: yaml

        rule_config:
          ImportConstraintsRule:
            dir_1:
              rules:
              - - common.foo.bar
                - deny
              - - '*'
                - deny
            dir_1/dir_2:
              rules:
              - - common.foo.bar
                - allow
              - - '*'
                - deny





    path: :file:`dir_1/dir_2/file.py`

    .. code-block:: python

                from common.foo import bar





    # 12:


    config:

    .. code-block:: yaml

        rule_config:
          ImportConstraintsRule:
            dir:
              rules:
              - - '*'
                - deny_global





    path: :file:`dir/file.py`

    .. code-block:: python


        def local_scope():
            import common






    # 13:


    config:

    .. code-block:: yaml

        rule_config:
          ImportConstraintsRule:
            dir:
              rules:
              - - '*'
                - deny_local





    path: :file:`dir/file.py`

    .. code-block:: python


        import common






    # 14:


    config:

    .. code-block:: yaml

        rule_config:
          ImportConstraintsRule:
            dir:
              rules:
              - - '*'
                - allow_global





    path: :file:`dir/file.py`

    .. code-block:: python


        import common






    # 15:


    config:

    .. code-block:: yaml

        rule_config:
          ImportConstraintsRule:
            dir:
              rules:
              - - '*'
                - allow_local





    path: :file:`dir/file.py`

    .. code-block:: python


        def local_scope():
            import common






---------------------
INVALID Code Examples
---------------------

# 1:


config:

.. code-block:: yaml

    rule_config:
      ImportConstraintsRule:
        some_dir:
          rules:
          - - '*'
            - deny





path: :file:`some_dir/file.py`

.. code-block:: python

            import common




# 2:


config:

.. code-block:: yaml

    rule_config:
      ImportConstraintsRule:
        '*/file.py':
          rules:
          - - '*'
            - deny





path: :file:`some_dir/file.py`

.. code-block:: python

            import common




# 3:


config:

.. code-block:: yaml

    rule_config:
      ImportConstraintsRule:
        some_dir:
          rules:
          - - common.foo.bar
            - deny
          - - common
            - allow
          - - '*'
            - allow





path: :file:`some_dir/file.py`

.. code-block:: python

            from common.foo import bar




.. container:: toggle


    # 4:


    config:

    .. code-block:: yaml

        rule_config:
          ImportConstraintsRule:
            some_dir:
              rules:
              - - common
                - deny
              - - '*'
                - allow





    path: :file:`some_dir/file.py`

    .. code-block:: python

                import common as not_common





    # 5:


    config:

    .. code-block:: yaml

        rule_config:
          ImportConstraintsRule:
            some_dir:
              rules:
              - - common.bar
                - deny
              - - '*'
                - allow





    path: :file:`some_dir/file.py`

    .. code-block:: python

                from common import bar as not_bar





    # 6:


    config:

    .. code-block:: yaml

        rule_config:
          ImportConstraintsRule:
            common:
              rules:
              - - '*'
                - deny





    path: :file:`common/a.py`

    .. code-block:: python

                from . import b





    # 7:


    config:

    .. code-block:: yaml

        rule_config:
          ImportConstraintsRule:
            dir_1:
              rules:
              - - common.foo.bar
                - allow
              - - '*'
                - deny
            dir_1/dir_2:
              rules:
              - - '*'
                - deny





    path: :file:`dir_1/dir_2/file.py`

    .. code-block:: python

                from common.foo import bar





    # 8:


    config:

    .. code-block:: yaml

        rule_config:
          ImportConstraintsRule:
            dir_1:
              rules:
              - - common
                - allow
              - - '*'
                - deny
            dir_1/dir_2:
              rules:
              - - '*'
                - deny





    path: :file:`dir_1/dir_2/file.py`

    .. code-block:: python

                import common





    # 9:


    config:

    .. code-block:: yaml

        rule_config:
          ImportConstraintsRule:
            dir:
              rules:
              - - '*'
                - deny_global





    path: :file:`dir/file.py`

    .. code-block:: python


        import common






    # 10:


    config:

    .. code-block:: yaml

        rule_config:
          ImportConstraintsRule:
            dir:
              rules:
              - - '*'
                - deny_local





    path: :file:`dir/file.py`

    .. code-block:: python


        def local_scope():
            import common






    # 11:


    config:

    .. code-block:: yaml

        rule_config:
          ImportConstraintsRule:
            dir:
              rules:
              - - '*'
                - allow_global





    path: :file:`dir/file.py`

    .. code-block:: python


        def local_scope():
            import common






    # 12:


    config:

    .. code-block:: yaml

        rule_config:
          ImportConstraintsRule:
            dir:
              rules:
              - - '*'
                - allow_local





    path: :file:`dir/file.py`

    .. code-block:: python


        import common






    # 13:


    config:

    .. code-block:: yaml

        rule_config:
          ImportConstraintsRule:
            dir:
              message: '''{imported}'' cannot be imported from ''{current_file}'''
              rules:
              - - '*'
                - deny





    path: :file:`dir/file.py`

    .. code-block:: python


        import common





