{
 "cells": [
  {
   "cell_type": "raw",
   "id": "a72bb99d-4cc7-44b2-bc6c-31b2f55023a6",
   "metadata": {
    "editable": true,
    "raw_mimetype": "text/restructuredtext",
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "source": [
    ".. _include-exclude-patterns:\n",
    "\n",
    "Include Exclude Patterns\n",
    "================================================================================\n",
    "This document serves as a practical reference guide for understanding how include-exclude pattern matching works, which uses the same pattern syntax as ``.gitignore`` files. Through a series of examples, you'll learn exactly how different patterns match file paths in various directory structures. Whether you need to include specific file types, exclude certain directories, or create complex matching rules, these examples will help you identify the correct pattern syntax for your specific needs. Use this guide as a quick reference when implementing file filtering in your projects to ensure your patterns behave as expected."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "e1030477-06b8-4338-8c61-648012561006",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "import pathspec\n",
    "\n",
    "def test_pattern(\n",
    "    pattern: str,\n",
    "    path: str,\n",
    "):\n",
    "    print(f\"pattern       = {pattern}\")\n",
    "    print(f\"path          = {path}\")\n",
    "    p = pathspec.PathSpec.from_lines(pathspec.patterns.GitWildMatchPattern, [pattern])\n",
    "    is_match_flag = p.match_file(path)\n",
    "    print(f\"{is_match_flag = }\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "da697208-c572-4e22-a58b-4be0bdb6524a",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "source": [
    "## Pattern: ``README.md``\n",
    "\n",
    "Matches any file named ``README.md`` in any directory or subdirectory."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "843e19f1-4d28-4d2e-9da4-0dc8216a7331",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = README.md\n",
      "path          = README.md\n",
      "is_match_flag = True\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"README.md\", path=\"README.md\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "7fed01db-fae3-4983-9c28-80aa645eb48b",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = README.md\n",
      "path          = folder/README.md\n",
      "is_match_flag = True\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"README.md\", path=\"folder/README.md\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "c12f4ca9-36f7-4985-ae04-c07859e98bac",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = README.md\n",
      "path          = folder/subfolder/README.md\n",
      "is_match_flag = True\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"README.md\", path=\"folder/subfolder/README.md\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5d30c260-d0ec-40e2-99b1-7a612d2f5ba9",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "source": [
    "## Pattern: ``*.py``\n",
    "\n",
    "Matches any Python file (.py extension) in any directory or subdirectory."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "d0c14f17-90cd-4159-abf2-17d0583c49ff",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = *.py\n",
      "path          = example.py\n",
      "is_match_flag = True\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"*.py\", path=\"example.py\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "52540461-1431-4a4e-a411-5420a6b40986",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = *.py\n",
      "path          = folder/example.py\n",
      "is_match_flag = True\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"*.py\", path=\"folder/example.py\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "569d7198-22f8-44cc-9fa4-ca5da1342ff0",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = *.py\n",
      "path          = folder/subfolder/example.py\n",
      "is_match_flag = True\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"*.py\", path=\"folder/subfolder/example.py\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cd26a41f-2fbb-4264-ae9a-8d238dbd199d",
   "metadata": {},
   "source": [
    "## Pattern: ``src/*.py``\n",
    "\n",
    "Matches Python files directly in the src directory, but not in subdirectories of src."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "464d4c49-aa98-415b-a98c-8473e7e3eee2",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = src/*.py\n",
      "path          = example.py\n",
      "is_match_flag = False\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"src/*.py\", path=\"example.py\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "c72d6465-e1c5-4501-80c4-03b0d9a85aab",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = src/*.py\n",
      "path          = folder/example.py\n",
      "is_match_flag = False\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"src/*.py\", path=\"folder/example.py\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "85fbc22d-211c-4c33-ae93-673dc820eda8",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = src/*.py\n",
      "path          = src/example.py\n",
      "is_match_flag = True\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"src/*.py\", path=\"src/example.py\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "78b2c1ba-f77e-42d0-9ae8-0c13e989f49a",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = src/*.py\n",
      "path          = src/folder/example.py\n",
      "is_match_flag = False\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"src/*.py\", path=\"src/folder/example.py\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "897c2f4c-3440-44a3-9cf8-0fe2952d39a6",
   "metadata": {},
   "source": [
    "## Pattern: ``src/**/*.py``\n",
    "\n",
    "Matches Python files in the src directory and all of its subdirectories at any depth."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "c44f4a24-f3bf-4d3b-aac2-1d069ccb7bf2",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = src/**/*.py\n",
      "path          = src/example.py\n",
      "is_match_flag = True\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"src/**/*.py\", path=\"src/example.py\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "0b4963e6-b0dd-4d82-bad2-0e5968b2795e",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = src/**/*.py\n",
      "path          = src/folder/example.py\n",
      "is_match_flag = True\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"src/**/*.py\", path=\"src/folder/example.py\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "75d3995d-2383-4295-8234-6dbdd573ee0d",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = src/**/*.py\n",
      "path          = src/folder/subfolder/example.py\n",
      "is_match_flag = True\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"src/**/*.py\", path=\"src/folder/subfolder/example.py\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cd91ab3a-b0ea-42a2-b43c-4e11c764d963",
   "metadata": {},
   "source": [
    "## Pattern: ``tmp``\n",
    "\n",
    "Matches any path that contains \"tmp\", including files in tmp directory or any directory named tmp."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "1c4e2273-7d3c-43c1-ad12-dc46ca753fc8",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = tmp\n",
      "path          = tmp/file.txt\n",
      "is_match_flag = True\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"tmp\", path=\"tmp/file.txt\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "b9e34efe-80b8-491a-a8d3-4f77d58bc615",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = tmp\n",
      "path          = tmp/folder/file.txt\n",
      "is_match_flag = True\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"tmp\", path=\"tmp/folder/file.txt\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "id": "4ed26a00-e78d-43c4-9af2-7c389dbda591",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = tmp\n",
      "path          = tmp/folder/subfolder/file.txt\n",
      "is_match_flag = True\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"tmp\", path=\"tmp/folder/subfolder/file.txt\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "id": "4cba20fb-4cc7-4d1a-aa47-fc34012b6c17",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = tmp\n",
      "path          = tests/tmp/file.txt\n",
      "is_match_flag = True\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"tmp\", path=\"tests/tmp/file.txt\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "id": "8af6cbc6-227b-4bd8-bbb3-522d811c3988",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = tmp\n",
      "path          = tests/tmp/folder/file.txt\n",
      "is_match_flag = True\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"tmp\", path=\"tests/tmp/folder/file.txt\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "id": "c09414c2-abe2-4a43-9bc8-9ffa0ebc8a85",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = tmp\n",
      "path          = tests/tmp/subfolder/file.txt\n",
      "is_match_flag = True\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"tmp\", path=\"tests/tmp/subfolder/file.txt\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "81d2f6ee-e87d-4ac9-98c7-716bf4b2ea6e",
   "metadata": {},
   "source": [
    "## Pattern: ``tmp/``\n",
    "\n",
    "Matches contents inside tmp directories, but not the tmp directory itself."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "id": "be34c4e2-2c77-433c-8842-da01fb8b0091",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = tmp/\n",
      "path          = tmp\n",
      "is_match_flag = False\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"tmp/\", path=\"tmp\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "id": "cb420a77-9d5e-47dc-8b54-94eb548a41c4",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = tmp/\n",
      "path          = tmp/file.txt\n",
      "is_match_flag = True\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"tmp/\", path=\"tmp/file.txt\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "id": "cb6005aa-3a7c-4420-b23c-bdcbe5b94062",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = tmp/\n",
      "path          = tmp/folder/file.txt\n",
      "is_match_flag = True\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"tmp/\", path=\"tmp/folder/file.txt\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "id": "7fbb00b0-1682-4ff9-b0bc-b2b44a867a13",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = tmp/\n",
      "path          = tmp/folder/subfolder/file.txt\n",
      "is_match_flag = True\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"tmp/\", path=\"tmp/folder/subfolder/file.txt\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "id": "c391c216-02b9-45bf-bd6a-d47276c7acca",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = tmp/\n",
      "path          = tests/tmp/file.txt\n",
      "is_match_flag = True\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"tmp/\", path=\"tests/tmp/file.txt\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "id": "f3c27d1c-3b3f-4bf8-8f9e-7a6e571f85d8",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = tmp/\n",
      "path          = tests/tmp/folder/file.txt\n",
      "is_match_flag = True\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"tmp/\", path=\"tests/tmp/folder/file.txt\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "id": "f80bf082-09e8-4242-9d07-4280d949ead4",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = tmp/\n",
      "path          = tests/tmp/subfolder/file.txt\n",
      "is_match_flag = True\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"tmp/\", path=\"tests/tmp/subfolder/file.txt\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0271af1e-e37c-4663-bbe8-0f7c2e85cfdc",
   "metadata": {},
   "source": [
    "## Pattern: ``docs/source/*/**/index.rst``\n",
    "\n",
    "Matches index.rst files that are at least 2 levels deep in the directory structure under docs/source, but not directly in docs/source."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "id": "fe4d2a31-f4b7-4838-8d24-9c3238128e8f",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = docs/source/*/**/index.rst\n",
      "path          = docs/source/index.rst\n",
      "is_match_flag = False\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"docs/source/*/**/index.rst\", path=\"docs/source/index.rst\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "id": "0e2d04e7-900e-40e3-8e91-7638a7ee233c",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = docs/source/*/**/index.rst\n",
      "path          = docs/source/Section-1/index.rst\n",
      "is_match_flag = True\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"docs/source/*/**/index.rst\", path=\"docs/source/Section-1/index.rst\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "id": "c43b62dd-fc19-43f9-8362-50dd345dade5",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = docs/source/*/**/index.rst\n",
      "path          = docs/source/Section-1/Section-1-1/index.rst\n",
      "is_match_flag = True\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"docs/source/*/**/index.rst\", path=\"docs/source/Section-1/Section-1-1/index.rst\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4c40f8ce-a4ee-4793-8ba7-8756873614e5",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "source": [
    "## Pattern: ``*.py[cod]``\n",
    "\n",
    "Matches Python compiled files (.pyc, .pyo, .pyd), useful for excluding compiled Python code."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "id": "e7aa3f33-d9ee-4c98-b023-fb8fe798b9dc",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = *.py[cod]\n",
      "path          = test.pyc\n",
      "is_match_flag = True\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"*.py[cod]\", path=\"test.pyc\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "id": "8f9c5c51-eddd-46b6-a217-994ac089541e",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = *.py[cod]\n",
      "path          = test.pyo\n",
      "is_match_flag = True\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"*.py[cod]\", path=\"test.pyo\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "id": "336d7b25-3036-49f9-9e91-00a5d653d479",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pattern       = *.py[cod]\n",
      "path          = test.pyd\n",
      "is_match_flag = True\n"
     ]
    }
   ],
   "source": [
    "test_pattern(pattern=\"*.py[cod]\", path=\"test.pyd\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}