ya-tagscript 2.0.0__tar.gz → 2.0.1__tar.gz

{ya_tagscript-2.0.0 → ya_tagscript-2.0.1}/.github/workflows/black.yml

@@ -3,7 +3,7 @@ name: Lint
 on:
   push:
     branches:
-      - v1
+      - main
 
   pull_request:
 
@@ -14,14 +14,14 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
 
-      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0  # v7.1.0
         with:
           python-version-file: ".python-version"
 
       - name: Lint with black
-        uses: psf/black@87928e6d6761a4a6d22250e1fee5601b3998086e  # 26.5.1
+        uses: psf/black@258e7dbf348bc23cb70b8cdf693481c04634ebcc  # 26.10.1
         with:
           options: '--check --diff --verbose'
           src: '.'

{ya_tagscript-2.0.0 → ya_tagscript-2.0.1}/.github/workflows/coverage_comment.yml

@@ -5,7 +5,7 @@ on:
     types:
       - completed
     branches:
-      - '!v1'
+      - '!main'
 
 jobs:
   post-coverage-comment:
@@ -19,7 +19,7 @@ jobs:
 
     steps:
       - name: Post comment
-        uses: py-cov-action/python-coverage-comment-action@5d8df5979747514c914e1c5a12335a7cf9a2745f # v4.1
+        uses: py-cov-action/python-coverage-comment-action@e5fb2218463c3377f3504b0c5b5646ed53da7a2f # v4.5
         with:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           GITHUB_PR_RUN_ID: ${{ github.event.workflow_run.id }}

{ya_tagscript-2.0.0 → ya_tagscript-2.0.1}/.github/workflows/publish.yml

@@ -3,7 +3,7 @@ name: Build & Publish to PyPI
 on:
   push:
     branches:
-      - v1
+      - main
     tags:
       - v*
 
@@ -15,12 +15,12 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:
           persist-credentials: false
 
       - name: Set up Python
-        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0  # v7.1.0
         with:
           cache: pip
           python-version-file: ".python-version"
@@ -36,7 +36,7 @@ jobs:
         run: python3 -m build
 
       - name: Store the distribution packages
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9  # v7.0.2
         with:
           name: python-package-distributions
           path: dist/
@@ -55,13 +55,13 @@ jobs:
 
     steps:
       - name: Download all the dists
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333  # v8.0.2
         with:
           name: python-package-distributions
           path: dist/
 
       - name: Publish distribution 📦 to PyPI
-        uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247  # v1.14.1
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086  # v1.14.3
 
   github-release:
     name: Create GitHub Release
@@ -75,7 +75,7 @@ jobs:
 
     steps:
       - name: Download all the dists
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333  # v8.0.2
         with:
           name: python-package-distributions
           path: dist/

{ya_tagscript-2.0.0 → ya_tagscript-2.0.1}/.github/workflows/test.yml

@@ -3,14 +3,14 @@ name: Test
 on:
   push:
     branches:
-      - v1
+      - main
 
   pull_request:
 
 
 jobs:
   test:
-
+    name: Run tests on ${{ matrix.python-version }}
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -19,10 +19,10 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
 
       - name: Setup Python ${{ matrix.python-version }}
-        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0  # v7.1.0
         with:
           allow-prereleases: true
           cache: pip
@@ -36,38 +36,67 @@ jobs:
         env:
           TOX_GH_MAJOR_MINOR: ${{ matrix.python-version }}
 
-      - run: mkdir coverage
-
       - name: Run test suite
         run: tox run --skip-pkg-install
         env:
           TOX_GH_MAJOR_MINOR: ${{ matrix.python-version }}
-          COVERAGE_FILE: coverage/.coverage.${{ matrix.python-version }}
+
+  checks:
+    name: Check (${{ matrix.check }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        check:
+          - mypy_check
+          - pyright_check
+          - lowest_bounds
+          - coverage
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+
+      - name: Setup Python
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0  # v7.1.0
+        with:
+          python-version: "3.14"
+
+      - name: Install tox
+        run: pip install tox
+
+      - name: Prepare coverage directory
+        if: matrix.check == 'coverage'
+        run: mkdir -p coverage
+
+      - name: Run check
+        run: tox run -e "${{ matrix.check }}"
 
       - name: Store coverage file
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        if: matrix.python-version == '3.14'
+        if: matrix.check == 'coverage'
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
-          name: coverage-${{ matrix.python-version }}
+          name: coverage-3.14
           path: coverage
           include-hidden-files: true
 
   coverage:
-    needs: test
+    name: Create Coverage report
+    needs: [ test, checks ]
     runs-on: ubuntu-latest
 
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
 
       - name: Setup Python
-        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0  # v7.1.0
         with:
           cache: pip
           python-version-file: .python-version
 
       - name: Get coverage files
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
           merge-multiple: true
           pattern: coverage-*
@@ -83,19 +112,20 @@ jobs:
         run: coverage html --data-file coverage/.coverage
 
       - name: Store coverage data
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           path: coverage
           name: coverage-data
           include-hidden-files: true
 
       - name: Store coverage HTML report
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           path: htmlcov
           name: coverage-html
 
   coverage-pr-comment:
+    name: Create Coverage PR comment
     needs: coverage
     runs-on: ubuntu-latest
     if: github.event_name == 'pull_request'
@@ -105,21 +135,21 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
 
       - name: Download coverage data
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
           name: coverage-3.14
 
       - name: Generate coverage comment
         id: coverage-comment
-        uses: py-cov-action/python-coverage-comment-action@5d8df5979747514c914e1c5a12335a7cf9a2745f # v4.1
+        uses: py-cov-action/python-coverage-comment-action@e5fb2218463c3377f3504b0c5b5646ed53da7a2f # v4.5
         with:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Store coverage comment
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         if: steps.coverage-comment.outputs.COMMENT_FILE_WRITTEN == 'true'
         with:
           name: python-coverage-comment-action

{ya_tagscript-2.0.0 → ya_tagscript-2.0.1}/.pre-commit-config.yaml

@@ -2,13 +2,19 @@ default_language_version:
   python: python3.11
 fail_fast: false
 repos:
+  - repo: https://github.com/asottile/pyupgrade
+    rev: v3.22.0
+    hooks:
+      - id: pyupgrade
+        args: [ --py311-plus ]
+
   - repo: https://github.com/codespell-project/codespell
-    rev: v2.4.2
+    rev: v2.4.3
     hooks:
       - id: codespell
 
   - repo: https://github.com/pycqa/flake8
-    rev: 7.3.0
+    rev: 7.5.0
     hooks:
       - id: flake8
         additional_dependencies:
@@ -37,11 +43,11 @@ repos:
       - id: add-trailing-comma
 
   - repo: https://github.com/psf/black-pre-commit-mirror
-    rev: 26.5.0
+    rev: 26.10.1
     hooks:
       - id: black
 
   - repo: https://github.com/pycqa/isort
-    rev: 8.0.1
+    rev: 9.0.2
     hooks:
       - id: isort

{ya_tagscript-2.0.0 → ya_tagscript-2.0.1}/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 *Currently none*
 
+# v2.0.1 (2026-11-03)
+
+- Parser performance improvements
+    - Some **internals** have been removed/replaced:
+        - `TagScriptParser` -> `parse_tagscript`
+        - `BlockParseState` -> partially inlined with state transitions via
+          `transition_state`
+        - `TagScriptInterpreter._parser` removed without replacement
+        - Further private helper functions in several locations (which were all marked
+          with `_` already)
+    - Because these are internals, this is **not considered a breaking change**.
+
 # v2.0.0 (2026-07-24)
 
 - BREAKING: Remove `_accepted_names` in favour of `_VALID_NAMES`

{ya_tagscript-2.0.0 → ya_tagscript-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: ya_tagscript
-Version: 2.0.0
+Version: 2.0.1
 Summary: Yet Another TagScript fork. An easy drop in user-provided Templating system.
 Project-URL: Changelog, https://ya-tagscript.readthedocs.io/en/latest/changelog.html
 Project-URL: Documentation, https://ya-tagscript.readthedocs.io
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Requires-Python: >=3.11
 Requires-Dist: discord-py>=2.5.0
 Requires-Dist: pyparsing>=3.2.0
@@ -30,7 +31,7 @@ Description-Content-Type: text/markdown
 ![Read the Docs (version)](https://img.shields.io/readthedocs/ya_tagscript/latest)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
-Current stable version: v2.0.0
+Current stable version: v2.0.1
 
 ## Information
 
@@ -92,7 +93,7 @@ or
 <!--VERSIONED TAG SECTION START-->
 
 ```
-pip install git+https://github.com/MajorTanya/ya_tagscript.git@v2.0.0
+pip install git+https://github.com/MajorTanya/ya_tagscript.git@v2.0.1
 ```
 
 <!--VERSIONED TAG SECTION END-->

{ya_tagscript-2.0.0 → ya_tagscript-2.0.1}/README.md

@@ -5,7 +5,7 @@
 ![Read the Docs (version)](https://img.shields.io/readthedocs/ya_tagscript/latest)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
-Current stable version: v2.0.0
+Current stable version: v2.0.1
 
 ## Information
 
@@ -67,7 +67,7 @@ or
 <!--VERSIONED TAG SECTION START-->
 
 ```
-pip install git+https://github.com/MajorTanya/ya_tagscript.git@v2.0.0
+pip install git+https://github.com/MajorTanya/ya_tagscript.git@v2.0.1
 ```
 
 <!--VERSIONED TAG SECTION END-->

{ya_tagscript-2.0.0 → ya_tagscript-2.0.1}/docs/_ext/glossary_backlink_checker.py

@@ -161,8 +161,10 @@ class GlossaryRefChecker:
                 if not term_data.ref_col_seen:
                     problem_terms[term] = term_data
                     _logger.error(
-                        "[GlossaryRefCheck] Could not find a 'Referenced by' "
-                        "section with an 'x-ref-col' class for term %r",
+                        (
+                            "[GlossaryRefCheck] Could not find a 'Referenced by' "
+                            "section with an 'x-ref-col' class for term %r"
+                        ),
                         term,
                     )
                 elif (
@@ -171,8 +173,10 @@ class GlossaryRefChecker:
                 ):
                     problem_terms[term] = term_data
                     _logger.error(
-                        "[GlossaryRefCheck] 'Referenced by' section mismatch for "
-                        "term %r: %r",
+                        (
+                            "[GlossaryRefCheck] 'Referenced by' section mismatch for "
+                            "term %r: %r"
+                        ),
                         term,
                         term_data,
                     )

{ya_tagscript-2.0.0 → ya_tagscript-2.0.1}/docs/conf.py

@@ -17,7 +17,7 @@ project_copyright = "2025, MajorTanya"
 author = "MajorTanya"
 
 ### VERSION SECTION START
-version = "2.0.0"
+version = "2.0.1"
 ### VERSION SECTION END
 release = version
 

{ya_tagscript-2.0.0 → ya_tagscript-2.0.1}/make_release.py

@@ -128,7 +128,7 @@ def commit_release_with_tag(project_version: str, *, dry_run: bool, verbose: boo
 
 
 def update_changelog(project_version: str, *, dry_run: bool, verbose: bool):
-    with open("./CHANGELOG.md", mode="r", encoding="utf8") as cf:
+    with open("./CHANGELOG.md", encoding="utf8") as cf:
         old_changelog_text = cf.read()
         already_released_version = re.search(
             rf"^# v{project_version}$",
@@ -190,7 +190,7 @@ def update_changelog(project_version: str, *, dry_run: bool, verbose: bool):
 
 
 def update_pyproject(project_version: str, *, dry_run: bool, verbose: bool):
-    with open("./pyproject.toml", mode="r", encoding="utf8") as pypf:
+    with open("./pyproject.toml", encoding="utf8") as pypf:
         old_pyproject_content = pypf.read()
 
     match = re.search(
@@ -228,7 +228,7 @@ def update_pyproject(project_version: str, *, dry_run: bool, verbose: bool):
 
 
 def update_readme(project_version: str, *, dry_run: bool, verbose: bool):
-    with open("./README.md", mode="r", encoding="utf8") as rf:
+    with open("./README.md", encoding="utf8") as rf:
         old_readme_text = rf.read()
 
     new_readme_text = re.sub(
@@ -273,7 +273,7 @@ def update_readme(project_version: str, *, dry_run: bool, verbose: bool):
 
 
 def update_sphinx_conf(project_version: str, *, dry_run: bool, verbose: bool):
-    with open("./docs/conf.py", mode="r", encoding="utf8") as scf:
+    with open("./docs/conf.py", encoding="utf8") as scf:
         old_sphinx_conf = scf.read()
 
     updated_version_section = textwrap.dedent(
@@ -320,7 +320,7 @@ def main():
 
     _log.debug(f"Invoked with {args=}")
 
-    with open("./pyproject.toml", mode="r", encoding="utf8") as pf:
+    with open("./pyproject.toml", encoding="utf8") as pf:
         pyproject_config = tomllib.loads(pf.read())
         current_version = str(pyproject_config["project"]["version"])
 

{ya_tagscript-2.0.0 → ya_tagscript-2.0.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ya_tagscript"
-version = "2.0.0"
+version = "2.0.1"
 description = "Yet Another TagScript fork. An easy drop in user-provided Templating system."
 readme = "README.md"
 license = "CC-BY-4.0"
@@ -19,6 +19,7 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
     "Operating System :: OS Independent",
 ]
 requires-python = ">=3.11"
@@ -42,7 +43,7 @@ dev = [
     "docutils-stubs>=0.0.22",
     "enum-tools[sphinx]>=0.13.0",
     "hatchling>=1.28.0",
-    "isort>=8.0.1",
+    "isort>=9.0.2",
     "jinja2>=3.1.6",
     "mypy>=1.19.1",
     "myst-parser>=4.0.1",
@@ -56,9 +57,18 @@ dev = [
     "types-python-dateutil>=2.9.0.20260305",
 ]
 
+# ========== BLACK ==========
 [tool.black]
 target-version = ["py311", "py312", "py313", "py314"]
 
+# ========== ISORT ==========
+[tool.isort]
+profile = "black"
+py_version = 311
+reverse_relative = true
+sort_reexports = true
+
+# ========== COVERAGE ==========
 [tool.coverage.report]
 fail_under = 100
 show_missing = true
@@ -73,14 +83,11 @@ branch = true
 source = ['src/', 'tests/']
 relative_files = true
 
-[tool.isort]
-profile = "black"
-py_version = 311
-reverse_relative = true
-
+# ========== MYPY ==========
 [tool.mypy]
 strict = true
 
+# ========== PYRIGHT ==========
 [tool.pyright]
 typeCheckingMode = 'strict'
 # enable some non-default rules
@@ -92,6 +99,7 @@ reportUnknownLambdaType = "none"
 reportUnknownMemberType = "none"
 reportUnknownVariableType = "none"
 
+# ========== PYTEST ==========
 [tool.pytest]
 filterwarnings = [
     "error",
@@ -99,6 +107,7 @@ filterwarnings = [
     'ignore:Deprecated since v1.7. Use _VALID_NAMES instead:DeprecationWarning'
 ]
 
+# ========== TOX ==========
 [tool.tox]
 requires = ["tox>=4"]
 env_list = [
@@ -162,7 +171,7 @@ commands = [
 
 [tool.tox.gh.python]
 "3.15" = ["3.15"]
-"3.14" = ["3.14", "mypy_check", "pyright_check", "lowest_bounds", "coverage"]
+"3.14" = ["3.14"]
 "3.13" = ["3.13"]
 "3.12" = ["3.12"]
 "3.11" = ["3.11"]

{ya_tagscript-2.0.0 → ya_tagscript-2.0.1}/src/ya_tagscript/interpreter/interpreter.py

@@ -19,7 +19,7 @@ from ya_tagscript.interfaces import (
 from .context import Context
 from .node import Node
 from .response import Response
-from .ts_parser import TagScriptParser
+from .ts_parser import parse_tagscript
 
 _logger = logging.getLogger(__name__)
 
@@ -28,7 +28,6 @@ class TagScriptInterpreter(InterpreterABC):
 
     __slots__ = (
         "blocks",
-        "_parser",
         "work_limit",
         "total_work",
         "_named_blocks",
@@ -39,7 +38,6 @@ class TagScriptInterpreter(InterpreterABC):
         self,
         blocks: Sequence[BlockABC],
     ) -> None:
-        self._parser = TagScriptParser()
         self.blocks: Sequence[BlockABC] = blocks
         self.work_limit: int | None = None
         self.total_work: int = 0
@@ -104,7 +102,7 @@ class TagScriptInterpreter(InterpreterABC):
             # if we don't have even one of each brace, this is uninterpretable
             # in other words, this is plaintext to us
             return subject
-        ast = self._parser.parse(subject)
+        ast = parse_tagscript(subject)
         output: str = ""
         node_processing_fn = self._process_node
         for node in ast:

ya_tagscript-2.0.1/src/ya_tagscript/interpreter/parse_state.py

@@ -0,0 +1,99 @@
+from enum import Enum, auto
+from typing import Literal, overload
+
+
+class ParseState(Enum):
+    """
+    Represents the current state of parsing within a block.
+    States transition in a specific order based on block structure.
+    """
+
+    EXPECTING_DECLARATION = auto()  # Initial state when a block starts
+    IN_DECLARATION = auto()  # Collecting declaration text
+    IN_PARAMETER = auto()  # Between parameter parentheses
+    # After completed parameter parentheses, maybe end, maybe payload next
+    POST_PARAMETER = auto()
+    IN_PAYLOAD = auto()  # After the colon
+
+
+@overload
+def transition_state(
+    current_state: Literal[ParseState.EXPECTING_DECLARATION],
+    next_state: Literal[ParseState.IN_DECLARATION],
+) -> Literal[ParseState.IN_DECLARATION]: ...
+
+
+@overload
+def transition_state(
+    current_state: Literal[ParseState.IN_DECLARATION],
+    next_state: Literal[ParseState.IN_PARAMETER],
+) -> Literal[ParseState.IN_PARAMETER]: ...
+
+
+@overload
+def transition_state(
+    current_state: Literal[ParseState.IN_PARAMETER],
+    next_state: Literal[ParseState.POST_PARAMETER],
+) -> Literal[ParseState.POST_PARAMETER]: ...
+
+
+@overload
+def transition_state(
+    current_state: Literal[ParseState.IN_DECLARATION, ParseState.POST_PARAMETER],
+    next_state: Literal[ParseState.IN_PAYLOAD],
+) -> Literal[ParseState.IN_PAYLOAD]: ...
+
+
+def transition_state(
+    current_state: ParseState,
+    next_state: ParseState,
+) -> Literal[
+    ParseState.IN_DECLARATION,
+    ParseState.IN_PARAMETER,
+    ParseState.POST_PARAMETER,
+    ParseState.IN_PAYLOAD,
+]:
+    """
+    Attempts to transition the block's state to the next state.
+    Raises ValueError if the transition is invalid.
+
+    Valid transitions are:
+
+        - EXPECTING_DECLARATION -> IN_DECLARATION (on text)
+        - IN_DECLARATION -> IN_PARAMETER (on opening parenthesis)
+        - IN_DECLARATION -> IN_PAYLOAD (on colon)
+        - IN_PARAMETER -> POST_PARAMETER (on closing parenthesis)
+        - POST_PARAMETER -> IN_PAYLOAD (on colon)
+
+    Note:
+
+        - IN_PAYLOAD has no valid target state because the only way out is to
+            finalize the block.
+        - EXPECTING_DECLARATION can transition to the base None state if the tokens
+            are "{}"
+    """
+    if (
+        current_state is ParseState.EXPECTING_DECLARATION
+        and next_state is ParseState.IN_DECLARATION
+    ):
+        return next_state
+
+    elif current_state is ParseState.IN_DECLARATION and (
+        next_state is ParseState.IN_PARAMETER or next_state is ParseState.IN_PAYLOAD
+    ):
+        return next_state
+
+    elif (
+        current_state is ParseState.IN_PARAMETER
+        and next_state is ParseState.POST_PARAMETER
+    ):
+        return next_state
+
+    elif (
+        current_state is ParseState.POST_PARAMETER
+        and next_state is ParseState.IN_PAYLOAD
+    ):
+        return next_state
+
+    else:
+        raise ValueError(f"Invalid state transition: {current_state} -> {next_state}")