plain-parser 0.1.0__tar.gz

plain_parser-0.1.0/.flake8

@@ -0,0 +1,13 @@
+[flake8]
+max-line-length = 120
+extend-ignore = E203, E501, B001, N803, N806, N813, U101
+exclude =
+    .git,
+    __pycache__,
+    .venv,
+    build,
+    dist,
+    tests
+per-file-ignores =
+    __init__.py: F401
+max-complexity = 15

plain_parser-0.1.0/.github/workflows/lint-and-test.yml

@@ -0,0 +1,44 @@
+name: Code Quality & Tests
+
+on:
+  # Pushes to PR branches are covered by pull_request; listening to every push
+  # too would run the suite twice per commit.
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  check:
+    name: Lint and test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.11"
+      - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('pyproject.toml') }}
+      - name: Install dependencies
+        id: install
+        run: python -m pip install --upgrade pip && pip install -e ".[dev]"
+
+      # Each check runs even if an earlier one failed, so one run reports
+      # every failure.
+      - name: Black Formatting
+        if: ${{ !cancelled() && steps.install.outcome == 'success' }}
+        run: black . --check
+      - name: Import Sorting
+        if: ${{ !cancelled() && steps.install.outcome == 'success' }}
+        run: isort . --check-only --diff
+      - name: Flake8 Linting
+        if: ${{ !cancelled() && steps.install.outcome == 'success' }}
+        run: flake8 .
+      - name: MyPy Type Checking
+        if: ${{ !cancelled() && steps.install.outcome == 'success' }}
+        run: mypy src
+      - name: Tests
+        if: ${{ !cancelled() && steps.install.outcome == 'success' }}
+        run: pytest tests -v

plain_parser-0.1.0/.github/workflows/publish-dev-to-pypi.yml

@@ -0,0 +1,147 @@
+name: Publish dev build to PyPI
+
+# Every merge to main publishes a PEP 440 dev release (e.g. 0.1.1.dev7) to
+# PyPI, so the latest main is always installable from the real index with real
+# dependency resolution. Dev releases are pre-releases: pip and uv skip them
+# unless asked, so ordinary installs keep getting the latest stable.
+#
+# Tagged releases (including rc/beta/alpha) are handled by publish-to-pypi.yml.
+on:
+  push:
+    branches: [main]
+  # Ad-hoc runs, e.g. re-publishing after a PyPI outage.
+  workflow_dispatch:
+
+# Least privilege by default: jobs get no GITHUB_TOKEN scopes unless they
+# opt in below.
+permissions: {}
+
+# Serialize publishes so versions land in merge order. Queued runs are not
+# cancelled — each merge should still get its own dev build.
+concurrency:
+  group: publish-dev-to-pypi
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build dev distribution
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      should-publish: ${{ steps.version.outputs.should-publish }}
+      version: ${{ steps.version.outputs.version }}
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          # hatch-vcs derives the version from git tags, so we need full history.
+          fetch-depth: 0
+
+      - name: Install uv
+        # uv provisions its own Python (honoring requires-python), so no
+        # separate actions/setup-python step is needed.
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Compute dev version
+        id: version
+        # Between releases hatch-vcs produces something like
+        # "0.3.10.dev16+gb710c2982". The "+g..." local version segment is valid
+        # PEP 440 but is rejected by PyPI on upload, so it has to go. We keep
+        # setuptools-scm's own next-version guess (0.3.10 — the patch bump
+        # after the latest tag) rather than re-deriving it here, and use the
+        # run number as the dev counter: it is strictly increasing, so each
+        # merge sorts after the last and re-runs never collide.
+        run: |
+          RAW=$(uvx --from setuptools-scm python -c \
+            "from setuptools_scm import get_version; print(get_version())")
+          echo "setuptools-scm reports: $RAW"
+
+          # On a commit that IS a release tag, setuptools-scm returns a clean
+          # version with no .dev component (e.g. "0.3.9" or "0.4.0rc1").
+          # Appending ".dev<run>" to that yields 0.3.9.dev42, which sorts BELOW
+          # the released 0.3.9 — newer code would look older. A tagged commit
+          # is a real release and is published by publish-to-pypi.yml, so there
+          # is no dev build to make here.
+          case "$RAW" in
+            *.dev*) ;;
+            *)
+              echo "::notice::$RAW is a tagged release; skipping dev build."
+              echo "should-publish=false" >> $GITHUB_OUTPUT
+              exit 0
+              ;;
+          esac
+
+          BASE=${RAW%%+*}
+          BASE=${BASE%%.dev*}
+          VERSION="${BASE}.dev${GITHUB_RUN_NUMBER}"
+          echo "Derived version: $RAW -> $VERSION"
+          echo "SETUPTOOLS_SCM_PRETEND_VERSION=$VERSION" >> $GITHUB_ENV
+          echo "should-publish=true" >> $GITHUB_OUTPUT
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Build package
+        if: steps.version.outputs.should-publish == 'true'
+        # hatch-vcs reads SETUPTOOLS_SCM_PRETEND_VERSION in place of the tag.
+        run: |
+          uv build
+          echo "Built distributions:"
+          ls -l dist/
+
+      - name: Store the distribution packages
+        if: steps.version.outputs.should-publish == 'true'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dev-package-distributions
+          path: dist/
+
+  publish-dev:
+    name: Publish dev build to PyPI
+    needs: build
+    if: needs.build.outputs.should-publish == 'true'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/plain-parser
+    permissions:
+      # Mint a short-lived OIDC token so PyPI Trusted Publishing can
+      # authenticate this run — no long-lived API token needed.
+      id-token: write
+
+    env:
+      SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dev-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          # PyPI uploads are immutable, so a re-run of an already-published
+          # version should be a no-op, not a red build.
+          skip-existing: true
+
+      - name: Notify Slack (success)
+        if: ${{ success() && env.SLACK_WEBHOOK_URL != '' }}
+        env:
+          VERSION: ${{ needs.build.outputs.version }}
+        run: |
+          # Spell out the --pre install: a plain "pip install plain-parser" will
+          # NOT pick this up, which otherwise reads as a broken publish.
+          TEXT="*plain-parser*: dev build \`$VERSION\` published to PyPI :test_tube:. Normal installs are unaffected — try it with \`pip install --pre plain-parser==$VERSION\`."
+          curl -s -X POST "$SLACK_WEBHOOK_URL" \
+            -H 'Content-type: application/json' \
+            --data "$(jq -n --arg t "$TEXT" '{text:$t}')"
+
+      - name: Notify Slack (failure)
+        if: ${{ failure() && env.SLACK_WEBHOOK_URL != '' }}
+        run: |
+          curl -s -X POST "$SLACK_WEBHOOK_URL" \
+            -H 'Content-type: application/json' \
+            --data "{\"text\":\"*plain-parser*: Publishing dev build to PyPI FAILED :x: (commit \`${{ github.sha }}\`). See <${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}|the run log>.\"}"

plain_parser-0.1.0/.github/workflows/publish-to-pypi.yml

@@ -0,0 +1,117 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+# Least privilege by default: jobs get no GITHUB_TOKEN scopes unless they
+# opt in below.
+permissions: {}
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    env:
+      SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          # hatch-vcs derives the version from git tags, so we need full history.
+          fetch-depth: 0
+
+      - name: Notify Slack (start)
+        if: ${{ env.SLACK_WEBHOOK_URL != '' }}
+        run: |
+          curl -s -X POST "$SLACK_WEBHOOK_URL" \
+            -H 'Content-type: application/json' \
+            --data "{\"text\":\"*plain-parser*: Release \`${{ github.ref_name }}\` published by *${{ github.actor }}* — building and publishing to PyPI...\"}"
+
+      - name: Install uv
+        # uv provisions its own Python (honoring requires-python), so no
+        # separate actions/setup-python step is needed.
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Build package
+        # hatch-vcs reads the version straight from the release tag.
+        run: |
+          uv build
+          echo "Built distributions:"
+          ls -l dist/
+
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Upload assets to GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release upload ${{ github.ref_name }} dist/* --clobber
+
+      - name: Notify Slack (build failure)
+        if: ${{ failure() && env.SLACK_WEBHOOK_URL != '' }}
+        run: |
+          curl -s -X POST "$SLACK_WEBHOOK_URL" \
+            -H 'Content-type: application/json' \
+            --data "{\"text\":\"*plain-parser*: Build of \`${{ github.ref_name }}\` FAILED :x:. Nothing was published to PyPI. See <${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}|the run log>.\"}"
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/plain-parser
+    permissions:
+      # Mint a short-lived OIDC token so PyPI Trusted Publishing can
+      # authenticate this run — no long-lived API token needed.
+      id-token: write
+
+    env:
+      SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+
+      - name: Notify Slack (success)
+        if: ${{ success() && env.SLACK_WEBHOOK_URL != '' }}
+        env:
+          # GitHub marks the release itself as a pre-release; the tag
+          # (v0.2.0rc1) carries the same intent for PEP 440.
+          IS_PRERELEASE: ${{ github.event.release.prerelease }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          VERSION="${TAG#v}"
+          if [ "$IS_PRERELEASE" = "true" ]; then
+            # pip and uv skip pre-releases by default, so "--upgrade" would
+            # NOT pick this up. Tell people the command that actually works.
+            TEXT="*plain-parser*: pre-release \`$TAG\` published to PyPI :test_tube:. Normal installs are unaffected — try it with \`pip install --pre plain-parser==$VERSION\`."
+          else
+            TEXT="*plain-parser*: \`$TAG\` published to PyPI :white_check_mark:. Install with \`pip install --upgrade plain-parser\`."
+          fi
+          curl -s -X POST "$SLACK_WEBHOOK_URL" \
+            -H 'Content-type: application/json' \
+            --data "$(jq -n --arg t "$TEXT" '{text:$t}')"
+
+      - name: Notify Slack (failure)
+        if: ${{ failure() && env.SLACK_WEBHOOK_URL != '' }}
+        run: |
+          curl -s -X POST "$SLACK_WEBHOOK_URL" \
+            -H 'Content-type: application/json' \
+            --data "{\"text\":\"*plain-parser*: Publishing \`${{ github.ref_name }}\` to PyPI FAILED :x:. See <${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}|the run log>.\"}"

plain_parser-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/

plain_parser-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Codeplain Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

plain_parser-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.5
+Name: plain-parser
+Version: 0.1.0
+Summary: Parser for ***plain specification files
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Compilers
+Requires-Python: >=3.11
+Requires-Dist: mistletoe<2,>=1.6.0
+Requires-Dist: networkx<4,>=3.6.1
+Requires-Dist: python-frontmatter<2,>=1.3.0
+Requires-Dist: python-liquid2<0.5,>=0.4.0
+Provides-Extra: dev
+Requires-Dist: black==26.5.1; extra == 'dev'
+Requires-Dist: flake8==7.3.0; extra == 'dev'
+Requires-Dist: isort==8.0.1; extra == 'dev'
+Requires-Dist: mypy==2.3.0; extra == 'dev'
+Requires-Dist: pytest==9.1.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# plain-parser
+
+Python parser for [`***plain`](https://www.plainlang.org/docs/) specification files.
+
+Reads a `.plain`  module and its `import` / `requires` chain, resolves Liquid templates,
+validates concepts and linked resources, and returns the marshalled specification tree
+plus the ordered list of functionalities (FRIDs).
+
+## Install
+
+```bash
+pip install plain-parser
+```
+
+## Usage
+
+```python
+from plain_parser import plain_file_parser
+
+module_name, plain_source_tree, required_modules = plain_file_parser("my_spec.plain", ["."])
+```
+
+`plain_source_tree` is a dict keyed by section (`definitions`, `implementation reqs`,
+`test reqs`, `functional specs`), each a list of `{"markdown": ..., "linked_resources": [...]}`
+entries. `plain_parser.plain_spec` has helpers for walking functionalities
+(`get_frids`, `get_specifications_for_frid`, `collect_linked_resources`).
+
+## Development
+
+```bash
+uv venv --python 3.11 && source .venv/bin/activate
+uv pip install -e ".[dev]"
+pytest
+black . --check && isort . --check-only && flake8 . && mypy src
+```
+
+## License
+
+MIT, see [LICENSE](LICENSE).

plain_parser-0.1.0/README.md

@@ -0,0 +1,39 @@
+# plain-parser
+
+Python parser for [`***plain`](https://www.plainlang.org/docs/) specification files.
+
+Reads a `.plain`  module and its `import` / `requires` chain, resolves Liquid templates,
+validates concepts and linked resources, and returns the marshalled specification tree
+plus the ordered list of functionalities (FRIDs).
+
+## Install
+
+```bash
+pip install plain-parser
+```
+
+## Usage
+
+```python
+from plain_parser import plain_file_parser
+
+module_name, plain_source_tree, required_modules = plain_file_parser("my_spec.plain", ["."])
+```
+
+`plain_source_tree` is a dict keyed by section (`definitions`, `implementation reqs`,
+`test reqs`, `functional specs`), each a list of `{"markdown": ..., "linked_resources": [...]}`
+entries. `plain_parser.plain_spec` has helpers for walking functionalities
+(`get_frids`, `get_specifications_for_frid`, `collect_linked_resources`).
+
+## Development
+
+```bash
+uv venv --python 3.11 && source .venv/bin/activate
+uv pip install -e ".[dev]"
+pytest
+black . --check && isort . --check-only && flake8 . && mypy src
+```
+
+## License
+
+MIT, see [LICENSE](LICENSE).

plain_parser-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "plain-parser"
+dynamic = ["version"]
+description = "Parser for ***plain specification files"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+classifiers = [
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Compilers",
+]
+dependencies = [
+    "python-liquid2>=0.4.0,<0.5",
+    "mistletoe>=1.6.0,<2",
+    "python-frontmatter>=1.3.0,<2",
+    "networkx>=3.6.1,<4",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest==9.1.1",
+    "flake8==7.3.0",
+    "black==26.5.1",
+    "isort==8.0.1",
+    "mypy==2.3.0",
+]
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/plain_parser"]
+
+[tool.black]
+line-length = 120
+target-version = ['py311']
+extend-exclude = '''
+^/(.git|.venv|dist|tests/data)/
+'''
+
+[tool.isort]
+profile = "black"
+line_length = 120
+skip = [".git", ".venv", "dist", "tests/data"]
+skip_gitignore = true
+
+[tool.mypy]
+python_version = "3.11"
+ignore_missing_imports = true
+show_error_codes = true
+disable_error_code = [
+    "var-annotated", "import-untyped", "assignment", "return-value", "attr-defined",
+    "no-redef", "func-returns-value", "override", "index", "union-attr", "valid-type",
+    "misc", "operator", "unreachable", "has-type", "return", "type-arg",
+]
+exclude = ["^\\.git/", "^\\.venv/", "^tests/"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"
+norecursedirs = ["tests/data"]

plain_parser-0.1.0/src/plain_parser/__init__.py

@@ -0,0 +1,27 @@
+"""Parser for ***plain specification files."""
+
+from plain_parser import concept_utils, exceptions, loaders, plain_file, plain_spec
+from plain_parser.plain_file import (
+    PlainFileParseResult,
+    get_filename_from_module_name,
+    get_module_name_from_filename,
+    marshall_plain_source,
+    parse_plain_file,
+    parse_plain_source,
+    plain_file_parser,
+)
+
+__all__ = [
+    "PlainFileParseResult",
+    "concept_utils",
+    "exceptions",
+    "get_filename_from_module_name",
+    "get_module_name_from_filename",
+    "loaders",
+    "marshall_plain_source",
+    "parse_plain_file",
+    "parse_plain_source",
+    "plain_file",
+    "plain_file_parser",
+    "plain_spec",
+]