ya-tagscript 1.0.0__tar.gz

ya_tagscript-1.0.0/.github/workflows/black.yml

@@ -0,0 +1,22 @@
+name: Lint
+
+on: [ push, pull_request ]
+
+jobs:
+  lint:
+
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [ "3.11", "3.12", "3.13" ]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Lint with black
+        uses: psf/black@stable
+        with:
+          options: '--check --diff'
+          src: '.'
+          version: '~= 25.0'

ya_tagscript-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,121 @@
+name: Publish Python 🐍 distribution 📦 to PyPI and TestPyPI
+
+on: push
+
+jobs:
+  build:
+    name: Build distribution 📦
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+
+      - name: Install the project
+        run: uv sync --all-extras --dev
+
+      - name: Build a binary wheel and a source tarball
+        run: uv build
+
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: Publish Python 🐍 distribution 📦 to PyPI
+    if: startsWith(github.ref, 'refs/tags/')  # only publish to PyPI on tag pushes
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/ya_tagscript
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distribution 📦 to PyPI
+        uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc
+
+  github-release:
+    name: >-
+      Sign the Python 🐍 distribution 📦 with Sigstore
+      and upload them to GitHub Release
+    needs:
+      - publish-to-pypi
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Sign the dists with Sigstore
+        uses: sigstore/gh-action-sigstore-python@f514d46b907ebcd5bedc05145c03b69c1edd8b46
+        with:
+          inputs: >-
+            ./dist/*.tar.gz
+            ./dist/*.whl
+
+      - name: Create GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: >-
+          gh release create
+          "$GITHUB_REF_NAME"
+          --repo "$GITHUB_REPOSITORY"
+          --notes ""
+
+      - name: Upload artifact signatures to GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: >-
+          gh release upload
+          "$GITHUB_REF_NAME" dist/**
+          --repo "$GITHUB_REPOSITORY"
+
+  publish-to-testpypi:
+    name: Publish Python 🐍 distribution 📦 to TestPyPI
+    needs:
+      - build
+    runs-on: ubuntu-latest
+
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/ya_tagscript
+
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distribution 📦 to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

ya_tagscript-1.0.0/.github/workflows/test.yml

@@ -0,0 +1,32 @@
+name: Test
+
+on: [ push, pull_request ]
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [ "3.11", "3.12", "3.13" ]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Run tests
+        run: uv run pytest tests

ya_tagscript-1.0.0/.gitignore

@@ -0,0 +1,27 @@
+__pycache__/
+
+# Distribution / packaging
+dist/
+
+# Unit test / coverage reports
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+
+# Sphinx documentation
+docs/_build/
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+
+.DS_Store
+
+.idea/
+.local/

ya_tagscript-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,33 @@
+default_language_version:
+  python: python3.11
+fail_fast: false
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-toml
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-builtin-literals
+      - id: check-ast
+      - id: check-json
+      - id: detect-private-key
+      - id: requirements-txt-fixer
+      - id: trailing-whitespace
+        args: [ --markdown-linebreak-ext=md ]
+
+  - repo: https://github.com/psf/black
+    rev: 25.1.0
+    hooks:
+      - id: black
+
+  - repo: https://github.com/pycqa/isort
+    rev: 6.0.1
+    hooks:
+      - id: isort
+
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.7.3
+    hooks:
+      - id: uv-lock

ya_tagscript-1.0.0/.python-version

@@ -0,0 +1 @@
+3.13

ya_tagscript-1.0.0/.readthedocs.yaml

@@ -0,0 +1,14 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: true
+
+python:
+  install:
+    - requirements: docs/requirements.txt

ya_tagscript-1.0.0/LICENSE.md

@@ -0,0 +1 @@
+This work is licensed under the Creative Commons Attribution 4.0 International License. To view a copy of this license, visit https://creativecommons.org/licenses/by/4.0/ or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.

ya_tagscript-1.0.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: ya_tagscript
+Version: 1.0.0
+Summary: Yet Another TagScript fork. An easy drop in user-provided Templating system.
+Project-URL: GitHub, https://github.com/MajorTanya/ya_tagscript
+Project-URL: Issues, https://github.com/MajorTanya/ya_tagscript/issues
+Author-email: MajorTanya <tanya@majortanya.eu>
+License-Expression: CC-BY-4.0
+License-File: LICENSE.md
+Keywords: tagscript
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: <3.14,>=3.11
+Requires-Dist: discord-py>=2.5.2
+Requires-Dist: pyparsing>=3.2.3
+Requires-Dist: python-dateutil>=2.9.0.post0
+Description-Content-Type: text/markdown
+
+# ya_tagscript - Yet Another TagScript fork
+
+## Information
+
+This is a fork of PhenoM4n4n's [TagScript](https://github.com/phenom4n4n/TagScript),
+which itself is a fork of JonSnowbd's
+[TagScript](https://github.com/JonSnowbd/TagScript), a string templating language.
+
+The main purpose of this fork is to align the Discord-specific blocks with the most
+recent Discord and discord.py changes (new username system, etc.).
+
+## What?
+
+TagScript is a drop-in, easy-to-use string interpreter that lets you provide users with
+ways of customizing their profiles or chat rooms with interactive text.
+
+For example TagScript comes out of the box with a random block that would let users
+provide a template that produces a new result each time its ran, or assign math and
+variables for later use.
+
+## Changes in v1
+
+The newly released v1 includes a complete rewrite of the entire parsing and
+interpretation performed by the TagScriptInterpreter class. This comes with some subtle
+behavioural changes but great care was taken to keep v1 behaviourally similar to v0 and
+PhenoM4n4n's fork. Most simple uses *should* behave the same but especially deeply
+nested scripts or dynamically assembled ones will most likely require adjustments.
+Some documentation examples were also outright wrong, so those were also adjusted to
+reflect the actual behaviour of the pre-existing interpreter.
+
+### Oh, no! Behaviour changes?!
+
+To remove the need for dynamically assembled blocks (e.g. command blocks that only
+happen under some circumstances), v1 only performs interpretation of branches that were
+actually hit (to the best of its ability).
+
+Take this (very bad) password check script:
+
+```tagscript
+{if({args}==123):{command:echo password accepted!}|something else}
+```
+
+If `{args}` is not in fact equal to `123`, the interpreter WILL NOT interpret the
+command block AT ALL. It jumps straight to the `else` section after the `|` and only
+interprets that. This means that for any incorrect values of `{args}`, the `echo`
+command is NOT included in the list of commands in `response.actions.get("commands")`.
+
+Other blocks with some conditional executions (like `all` or `any`) do the same.
+
+## Installation
+
+Download the latest version through pip:
+
+```
+pip3 install ya_tagscript
+```
+
+or
+
+```
+pip3 install git+https://github.com/MajorTanya/ya_tagscript.git@v1.0.0.alpha03
+```
+
+Download from a commit:
+
+```
+pip3 install git+https://github.com/MajorTanya/ya_tagscript.git@<COMMIT_HASH>
+```
+
+Install for editing/development:
+
+```
+git clone https://github.com/MajorTanya/ya_tagscript.git
+pip3 install -e ./TagScript
+```
+
+## Dependencies
+
+- `Python>=3.11`
+- `discord.py>=2.5.2`
+- `pyparsing>=3.2.3`
+- `python-dateutil>=2.9.0.post0`

ya_tagscript-1.0.0/README.md

@@ -0,0 +1,82 @@
+# ya_tagscript - Yet Another TagScript fork
+
+## Information
+
+This is a fork of PhenoM4n4n's [TagScript](https://github.com/phenom4n4n/TagScript),
+which itself is a fork of JonSnowbd's
+[TagScript](https://github.com/JonSnowbd/TagScript), a string templating language.
+
+The main purpose of this fork is to align the Discord-specific blocks with the most
+recent Discord and discord.py changes (new username system, etc.).
+
+## What?
+
+TagScript is a drop-in, easy-to-use string interpreter that lets you provide users with
+ways of customizing their profiles or chat rooms with interactive text.
+
+For example TagScript comes out of the box with a random block that would let users
+provide a template that produces a new result each time its ran, or assign math and
+variables for later use.
+
+## Changes in v1
+
+The newly released v1 includes a complete rewrite of the entire parsing and
+interpretation performed by the TagScriptInterpreter class. This comes with some subtle
+behavioural changes but great care was taken to keep v1 behaviourally similar to v0 and
+PhenoM4n4n's fork. Most simple uses *should* behave the same but especially deeply
+nested scripts or dynamically assembled ones will most likely require adjustments.
+Some documentation examples were also outright wrong, so those were also adjusted to
+reflect the actual behaviour of the pre-existing interpreter.
+
+### Oh, no! Behaviour changes?!
+
+To remove the need for dynamically assembled blocks (e.g. command blocks that only
+happen under some circumstances), v1 only performs interpretation of branches that were
+actually hit (to the best of its ability).
+
+Take this (very bad) password check script:
+
+```tagscript
+{if({args}==123):{command:echo password accepted!}|something else}
+```
+
+If `{args}` is not in fact equal to `123`, the interpreter WILL NOT interpret the
+command block AT ALL. It jumps straight to the `else` section after the `|` and only
+interprets that. This means that for any incorrect values of `{args}`, the `echo`
+command is NOT included in the list of commands in `response.actions.get("commands")`.
+
+Other blocks with some conditional executions (like `all` or `any`) do the same.
+
+## Installation
+
+Download the latest version through pip:
+
+```
+pip3 install ya_tagscript
+```
+
+or
+
+```
+pip3 install git+https://github.com/MajorTanya/ya_tagscript.git@v1.0.0.alpha03
+```
+
+Download from a commit:
+
+```
+pip3 install git+https://github.com/MajorTanya/ya_tagscript.git@<COMMIT_HASH>
+```
+
+Install for editing/development:
+
+```
+git clone https://github.com/MajorTanya/ya_tagscript.git
+pip3 install -e ./TagScript
+```
+
+## Dependencies
+
+- `Python>=3.11`
+- `discord.py>=2.5.2`
+- `pyparsing>=3.2.3`
+- `python-dateutil>=2.9.0.post0`

ya_tagscript-1.0.0/docs/Makefile

@@ -0,0 +1,23 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+livehtml:
+	sphinx-autobuild --watch ../src --re-ignore "\.py(?:c|c\.*)|__pycache__" "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

ya_tagscript-1.0.0/docs/_ext/glossary_backlink_checker.py

@@ -0,0 +1,173 @@
+import dataclasses
+from typing import Any
+
+from docutils import nodes
+from sphinx.addnodes import desc, desc_signature, pending_xref
+from sphinx.application import Sphinx
+from sphinx.util import logging as sphinx_logging
+
+logger = sphinx_logging.getLogger(__name__)
+
+
+def setup(app: Sphinx) -> dict[str, Any]:
+    collector = GlossaryRefChecker()
+    # Capture pending cross-refs before resolution
+    app.connect("doctree-read", collector.process_doc_read)
+    app.connect("doctree-resolved", collector.check_glossary_refs)
+    return {
+        "version": "1.0",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }
+
+
+@dataclasses.dataclass
+class MismatchedTermData:
+    found_undeclared: set[str]
+    declared_not_found: set[str]
+    ref_col_seen: bool
+
+
+class GlossaryRefChecker:
+    """
+    A Sphinx extension to validate glossary term references and their back-references.
+
+    This extension ensures that all glossary terms referenced in the documentation
+    are properly declared and that their "Referenced by" sections are consistent.
+    It helps maintain the integrity of cross-references in the documentation,
+    improving its accuracy and reliability for users.
+
+    This validation approach allows for all references to be resolved fully before
+    checking their validity without a need to modify the documents in progress, which
+    would spawn further reference objects.
+    """
+
+    def process_doc_read(self, app: Sphinx, doctree: nodes.document) -> None:
+        docname = app.env.docname
+        if not hasattr(app.env, "glossary_term_refs"):
+            app.env.glossary_term_refs = {}  # type: ignore
+
+        for node in doctree.findall(
+            lambda n: isinstance(n, (pending_xref, nodes.reference))
+        ):
+            if node.get("reftype") != "term":
+                continue
+
+            term = node.get("reftarget", "")
+            anchor = None
+
+            # Check if inside an autodoc class directive
+            parent = node
+            while parent and not (
+                isinstance(parent, desc) and parent.get("objtype") == "class"
+            ):
+                parent = parent.parent
+
+            if parent:
+                # It's inside a class doc
+                sig_node = parent.next_node(desc_signature)
+                if sig_node and sig_node.get("ids"):
+                    anchor = sig_node["ids"][0]
+            else:
+                # fallback: use nearest parent with an ID (like a section)
+                parent = node
+                while parent:
+                    if parent.get("ids"):
+                        anchor = parent["ids"][0]
+                        break
+                    parent = parent.parent
+
+            if not anchor:
+                # fallback to synthetic anchor if no ID found (should be rare)
+                anchor = f"auto-ref-{hash(node.astext()) % 100000}"
+
+            logger.verbose(
+                f"[GlossaryRefCheck] Glossary term reference found: term=%r, doc=%r, anchor=%r",
+                term,
+                docname,
+                anchor,
+            )
+
+            app.env.glossary_term_refs.setdefault(term, set()).add((docname, anchor))  # type: ignore
+
+    def check_glossary_refs(self, app: Sphinx, doctree: nodes.document, docname: str):
+        if docname != "glossary":
+            return
+
+        mismatched_terms: dict[str, MismatchedTermData] = {}
+
+        for node in doctree.findall(nodes.definition_list_item):
+            term_definitions: set[str] = set()
+            for child in node.findall(nodes.term):
+                child_text = child.astext()
+                term_definitions.add(child_text)
+                mismatched_terms[child_text] = MismatchedTermData(
+                    set(),
+                    set(),
+                    ref_col_seen=False,
+                )
+
+            refs_map: dict[str, set[tuple[str, str]]] = getattr(
+                app.env,
+                "glossary_term_refs",
+                {},
+            )
+
+            for ul in node.findall(nodes.bullet_list):
+                if "x-ref-col" not in ul.get("classes", []):
+                    continue
+
+                listed_refs: set[str] = set()
+                for ul_li in ul.findall(nodes.list_item):
+                    for para in ul_li.findall(nodes.paragraph):
+                        for ref in para.findall(nodes.reference):
+                            refuri = ref.attributes.get("refuri")
+                            listed_refs.add(str(refuri).split("#")[-1])
+
+                combined_found_refs = set()
+                for t_def in term_definitions:
+                    if (refs := refs_map.get(t_def)) is None:
+                        continue
+                    combined_found_refs.update({rm_entry[1] for rm_entry in refs})
+
+                found_but_undeclared = combined_found_refs.difference(listed_refs)
+                declared_but_not_found = listed_refs.difference(combined_found_refs)
+                for t_def in term_definitions:
+                    mismatched_terms[t_def] = MismatchedTermData(
+                        found_but_undeclared,
+                        declared_but_not_found,
+                        ref_col_seen=True,
+                    )
+
+        if any(
+            (
+                not term_data.ref_col_seen
+                or len(term_data.found_undeclared) != 0
+                or len(term_data.declared_not_found) != 0
+            )
+            for term_data in mismatched_terms.values()
+        ):
+            problem_terms: dict[str, MismatchedTermData] = {}
+            for term, term_data in mismatched_terms.items():
+                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",
+                        term,
+                    )
+                elif (
+                    len(term_data.found_undeclared) != 0
+                    or len(term_data.declared_not_found) != 0
+                ):
+                    problem_terms[term] = term_data
+                    logger.error(
+                        "[GlossaryRefCheck] 'Referenced by' section mismatch for "
+                        "term %r: %r",
+                        term,
+                        term_data,
+                    )
+        else:
+            logger.info(
+                "[GlossaryRefCheck] All glossary term references back-referenced correctly!"
+            )

ya_tagscript-1.0.0/docs/_ext/styled_list_directive.py

@@ -0,0 +1,33 @@
+from docutils import nodes
+from docutils.parsers.rst import Directive
+from docutils.parsers.rst.directives import class_option
+
+
+class StyledList(Directive):
+    has_content = True
+    option_spec = {
+        "class": class_option,
+    }
+
+    def run(self) -> list[nodes.Node]:
+        node = nodes.Element()
+        self.state.nested_parse(self.content, self.content_offset, node)
+
+        list_node = next(
+            (
+                child
+                for child in node
+                if isinstance(child, (nodes.bullet_list, nodes.enumerated_list))
+            ),
+            None,
+        )
+        if list_node is None:
+            error = self.state_machine.reporter.error(
+                "Expected a bullet list or enumerated list in 'styled-list' content.",
+                nodes.literal_block(self.block_text, self.block_text),
+                line=self.lineno,
+            )
+            return [error]
+
+        list_node["classes"] += self.options.get("class", [])
+        return [list_node]