edify 0.3.0__tar.gz → 1.0.0__tar.gz

edify-1.0.0/.gitignore

@@ -0,0 +1,88 @@
+*.py[cod]
+__pycache__
+
+# C extensions
+*.so
+
+# Packages
+*.egg
+*.egg-info
+dist
+build
+edify/version.py
+eggs
+.eggs
+parts
+bin
+var
+sdist
+wheelhouse
+develop-eggs
+.installed.cfg
+lib
+lib64
+*venv*/
+pyvenv*/
+pip-wheel-metadata/
+
+# Installer logs
+pip-log.txt
+
+# Unit test / coverage reports
+.coverage
+.tox
+.coverage.*
+.pytest_cache/
+.ruff_cache/
+nosetests.xml
+coverage.xml
+htmlcov
+
+# Translations
+*.mo
+
+# Buildout
+.mr.developer.cfg
+
+# IDE project files
+.project
+.pydevproject
+.idea
+.vscode
+*.iml
+*.komodoproject
+
+# Complexity
+output/*.html
+output/*/index.html
+
+# Sphinx
+docs/_build
+
+.DS_Store
+*~
+.*.sw[po]
+.build
+.ve
+.env
+.cache
+.pytest
+.benchmarks
+.bootstrap
+.appveyor.token
+*.bak
+
+# Mypy Cache
+.mypy_cache/
+
+# Codecov Binary
+codecov
+
+# Design Docs
+design_docs
+
+# Docs playground wheel (built at docs-build time)
+docs/_static/edify-*.whl
+
+# Playwright test artifacts
+.playwright*

{edify-0.3.0 → edify-1.0.0}/CHANGELOG.rst

@@ -1,6 +1,54 @@
 
 Changelog
 =========
+1.0.0 (2026-08-04)
+------------------
+
+The first stable release. Edify grows from a builder into a full toolkit: a
+library of ready-to-call validators, introspection, serialization, framework
+integrations, and a closed match API — with the builder itself hardened and its
+rough edges filed off, and a documentation site you can run code inside. The
+changes worth knowing before you upgrade are below;
+the :doc:`0.3 → 1.0 guide <upgrading/0.3-to-1.0>` walks each one with
+before/after code.
+
+Added
+~~~~~
+
+* A library of 228 ready-to-call validators — email, URL, semver, IBAN, phone, postal, and hundreds more — each a callable :class:`~edify.Pattern` organised into topical categories. See :ref:`validators-callable`.
+* Five closed match verbs on every builder — ``test``, ``match``, ``search``, ``findall``, and ``sub`` — returning edify result wrappers. See :ref:`closed-match-verbs`.
+* :meth:`~edify.RegexBuilder.to_regex` accepts inline flags and an ``engine`` argument, compiling against an alternate backend when one is installed. See :ref:`engine-kwarg`.
+* Builders compare by emitted pattern: two chains that describe the same regex are equal. See :ref:`builder-equality`.
+* Introspection: render any pattern as a plain-English explanation, an ASCII or graph diagram, or an annotated ``re.VERBOSE`` form.
+* Serialization: round-trip a pattern through a dict or JSON.
+* Framework integrations shipped as opt-in extras — ``edify[pydantic]``, ``edify[fastapi]``, and ``edify[django]``.
+
+Breaking
+~~~~~~~~
+
+* Python 3.11 or newer is required (:pr:`64`). See :ref:`python-floor`.
+* Relicensed from Apache-2.0 to the `MIT License <https://github.com/luciferreeves/edify/blob/main/LICENSE>`_. No API change. See :ref:`license-mit`.
+* Invalid patterns raise an annotated error at the call site instead of emitting a subtly wrong regex. See :ref:`silent-failure-raises`.
+* Terminal methods return a :class:`~edify.result.Regex` wrapper rather than a bare :class:`re.Pattern`. See :ref:`regex-wrapper-return`.
+* :meth:`~edify.RegexBuilder.to_regex_string` returns the emitted source exactly as written into the pattern. See :ref:`to-regex-string-output`.
+* Named back-references resolve by name and named groups read off ``.captures``. See :ref:`named-backref-return`.
+* Character-class escaping is minimal and correct: only the metacharacters that need escaping inside a class are escaped. See :ref:`char-class-escape`.
+* The validator library is organised into categories, and a handful of import paths moved with it. See :ref:`library-reorg` and :ref:`moved-import-paths`.
+
+Documentation
+~~~~~~~~~~~~~
+
+* A rebuilt documentation site: a topic-first guide that works through the builder from anchors to lookaround, a page for every one of the 228 validators, and a complete API reference covering the public surface — every method, property, constant, atom, error, and type.
+* An in-browser playground. Examples throughout the guide and the library are live: edit the chain and the emitted regex and match results update as you type, with edify itself running in your browser. The :doc:`playground <playground>` page is the same widget at full size.
+* Every Python example in the documentation is executed by the test suite and snapshotted against the regex it emits, so a documented pattern cannot drift from what the code produces.
+* Method names, constants, and atoms are cross-linked to their reference entries throughout the prose and inside the code samples.
+
+Tooling and CI
+~~~~~~~~~~~~~~
+
+* Dropped the macOS and Windows runners from the CI matrix; Linux-only from here on. Edify is a pure-Python wheel with no platform-specific code, so the multi-OS jobs were buying ~zero signal and produced false negatives (:pr:`60`).
+* Bumped the minimum ``virtualenv`` floor for the CI bootstrap to ``>=21.4.2`` (:pr:`56`, :pr:`58`).
+
 0.3.0 (2026-04-29)
 ------------------
 

edify-1.0.0/CONTRIBUTING.rst

@@ -0,0 +1,87 @@
+============
+Contributing
+============
+
+Thanks for helping improve Edify. This guide gets you from a fresh clone to a
+green pull request.
+
+Setup
+=====
+
+Edify uses `uv <https://docs.astral.sh/uv/>`_ for everything. Install it, then
+sync the full development environment:
+
+.. code-block:: bash
+
+    git clone https://github.com/luciferreeves/edify
+    cd edify
+    uv sync --all-groups
+
+That creates ``.venv`` with the library, its optional extras, and every
+development tool. Prefix commands with ``uv run`` to use it.
+
+The gate
+========
+
+Every change must pass the same checks CI runs. Run them locally before you push:
+
+.. code-block:: bash
+
+    uv run ruff check .            # lint
+    uv run ruff format --check .   # formatting
+    uv run mypy edify tools        # type-check the library and tooling
+    uv run pyright                 # strict type-check (library, tests, tools)
+    uv run pytest                  # tests — 100% coverage is required
+
+All of these must be clean. Coverage is enforced at 100%: a line that isn't
+exercised by a test through the public API fails the build.
+
+House style
+===========
+
+- **No suppressions.** No ``# noqa``, ``# type: ignore``, or ``# pragma`` — if a
+  check complains, restructure the code so it doesn't.
+- **Single-purpose files with single-word names.** ``edify/builder/anchors.py``,
+  not ``edify/builder/anchor_helpers.py``.
+- **Tests mirror the source tree** under ``tests/`` and are named ``*.test.py``
+  (for example ``tests/builder/anchors.test.py``).
+- **Tests exercise the public API.** Reach behavior through the documented
+  surface, never by importing private helpers — that's what keeps coverage
+  honest.
+
+Public surface and changelog
+============================
+
+The exported API is captured in ``tools/surface/.public``. If your change adds,
+removes, or alters a public name, regenerate the snapshot and record the change:
+
+.. code-block:: bash
+
+    uv run python tools/surface/surface.py --write
+
+For a **breaking** change, also add a fragment under ``changes/`` describing the
+migration (see ``changes/README.rst`` for the format). A CI gate fails any pull
+request whose public surface moves without one.
+
+Docs
+====
+
+The documentation is a custom Sphinx site in ``docs/``. Build the playground
+wheel and serve the site with live reload:
+
+.. code-block:: bash
+
+    uv run python tools/docs/build.py
+    uv run --with sphinx-autobuild sphinx-autobuild docs docs/_build/html
+
+Commits and pull requests
+=========================
+
+- **Commits** use a single-line, imperative, `conventional-commit
+  <https://www.conventionalcommits.org>`_ subject — ``feat(builder): ...``,
+  ``fix(compile): ...``, ``docs: ...``. Keep rationale for the pull-request
+  description, not the commit body.
+- **Pull requests** describe *what changed and why*. Reference the issues they
+  close with ``Closes #123`` so they land together.
+
+That's it — open the pull request and the checks will tell you if anything's off.

edify-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022-2026 Bobby
+
+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.

edify-1.0.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: edify
+Version: 1.0.0
+Summary: Regular Expressions Made Simple
+Project-URL: Documentation, https://edify.readthedocs.io/
+Project-URL: Changelog, https://edify.readthedocs.io/en/latest/changelog.html
+Project-URL: Issue Tracker, https://github.com/luciferreeves/edify/issues
+Author-email: Bobby <me@shi.foo>, natsuoto <natsuoto@thatcomputerscientist.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: Unix
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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 :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Provides-Extra: all
+Requires-Dist: django>=4.2; extra == 'all'
+Requires-Dist: fastapi>=0.100; extra == 'all'
+Requires-Dist: graphviz>=0.20; extra == 'all'
+Requires-Dist: pydantic>=2.0; extra == 'all'
+Requires-Dist: regex>=2024.11.6; extra == 'all'
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == 'django'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Provides-Extra: graphviz
+Requires-Dist: graphviz>=0.20; extra == 'graphviz'
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=2.0; extra == 'pydantic'
+Provides-Extra: regex
+Requires-Dist: regex>=2024.11.6; extra == 'regex'
+Description-Content-Type: text/x-rst
+
+=====
+Edify
+=====
+
+.. image:: https://raw.githubusercontent.com/luciferreeves/edify/main/images/cover.png
+    :alt: Edify — simple regular expressions
+
+|
+
+**Edify builds regular expressions you can actually read.** It's a fluent,
+immutable regex builder for Python: you describe a pattern step by step in plain
+English, and Edify hands you a compiled regex — one your teammates can review in
+a pull request instead of squinting at.
+
+Why Edify
+=========
+
+A regular expression is easy to write and hard to read. Six months later nobody
+remembers what ``^(?:0x)?([0-9a-fA-F]{4})$`` was meant to accept, and the person
+reviewing the change that touches it has no way to be sure either. The syntax
+gives you nowhere to put a name, a comment, or a seam.
+
+Edify moves the pattern into ordinary Python, where all three fit:
+
+- Methods say what they do. ``.one_or_more().digit()`` needs no decoding.
+- The quantity comes before the thing it counts, the way you say it aloud —
+  ``.exactly(4).digit()`` is *exactly four digits*.
+- Every call returns a new builder, so a pattern you share can be extended in
+  two directions without either one disturbing the other.
+- A mistake raises an error that points at the call that caused it and names the
+  fix, rather than emitting a regex that is subtly wrong.
+
+A first pattern
+===============
+
+.. code-block:: python
+
+    from edify import RegexBuilder
+
+    # A 16-bit hex literal like "0xC0DE" — with the four hex digits captured.
+    hex_literal = (
+        RegexBuilder()
+        .start_of_input()
+        .optional().string("0x")
+        .capture()
+            .exactly(4).any_of().range("0", "9").range("a", "f").range("A", "F").end()
+        .end()
+        .end_of_input()
+    )
+
+    hex_literal.to_regex_string()   # '^(?:0x)?([0-9a-fA-F]{4})$'
+    hex_literal.test("0xC0DE")      # True
+    hex_literal.test("0xZZZZ")      # False
+
+Read the chain top to bottom and it tells you what it accepts.
+
+Patterns you don't have to write
+================================
+
+Edify ships 228 ready-made validators. Each is a callable pattern, so checking a
+value is a function call:
+
+.. code-block:: python
+
+    from edify.library import email, ipv4, semver
+
+    email("a@b.com")      # True
+    semver("1.4.0")       # True
+    ipv4("10.0.0.1")      # True
+    ipv4("999.1.1.1")     # False — the octet range is enforced
+
+They are assembled from 83 named fragments you can build with too, so a pattern
+of your own inherits the same range checks rather than approximating them:
+
+.. code-block:: python
+
+    from edify import Pattern, atoms
+
+    endpoint = (
+        Pattern().start_of_input()
+        .named_capture("host").use(atoms.ipv4).end()
+        .char(":")
+        .named_capture("port").use(atoms.port).end()
+        .end_of_input()
+    )
+
+    endpoint.to_regex().match("10.0.0.1:8080").groupdict()
+    # {'host': '10.0.0.1', 'port': '8080'}
+    endpoint("10.0.0.1:99999")   # False — 99999 is not a port
+
+Ask a pattern what it means
+===========================
+
+Because Edify keeps the structure rather than a string, it can describe a
+pattern back to you — in prose, as a diagram, or as an annotated verbose regex:
+
+.. code-block:: python
+
+    from edify import RegexBuilder
+
+    year = RegexBuilder().start_of_input().exactly(4).digit().end_of_input()
+    print(year.to_regex().explain())
+
+    # - The text must start with exactly 4 digits (0-9).
+    #
+    # Text this pattern accepts:
+    #     1234
+
+That same structure is what lets Edify warn you at build time about a pattern
+shaped for catastrophic backtracking, and round-trip a pattern through JSON.
+
+Install
+=======
+
+Edify requires **Python 3.11+**:
+
+.. code-block:: bash
+
+    pip install edify
+
+Optional extras add the alternate regex engine and the framework integrations:
+``edify[regex]``, ``edify[pydantic]``, ``edify[fastapi]``, ``edify[django]``, or
+``edify[all]``.
+
+Also in the box
+===============
+
+- **Introspection** — a plain-English explanation, an ASCII or rendered diagram,
+  or an annotated ``re.VERBOSE`` form of any pattern.
+- **Serialization** — round-trip a pattern through a dict or JSON and keep a
+  first-class pattern on the other side, not a flattened string.
+- **Integrations** — pydantic, FastAPI, and Django validators from a pattern.
+- **Testing helpers** — assert a pattern's contract beside its definition, and
+  snapshot what it emits.
+- **Reverse parsing** — turn an existing regex string back into a chain and read
+  what it does.
+
+Documentation
+=============
+
+`edify.readthedocs.io <https://edify.readthedocs.io>`_ has the guide, a page for
+every validator, and the full API reference. Examples throughout the site are
+live — edit the chain and the emitted regex and match results update as you
+type, with Edify running in your browser.
+
+License and contributing
+========================
+
+Edify is released under the `MIT License
+<https://github.com/luciferreeves/edify/blob/main/LICENSE>`_. Contributions are
+welcome — see `CONTRIBUTING.rst
+<https://github.com/luciferreeves/edify/blob/main/CONTRIBUTING.rst>`_ to get set up.

edify-1.0.0/README.rst

@@ -0,0 +1,152 @@
+=====
+Edify
+=====
+
+.. image:: https://raw.githubusercontent.com/luciferreeves/edify/main/images/cover.png
+    :alt: Edify — simple regular expressions
+
+|
+
+**Edify builds regular expressions you can actually read.** It's a fluent,
+immutable regex builder for Python: you describe a pattern step by step in plain
+English, and Edify hands you a compiled regex — one your teammates can review in
+a pull request instead of squinting at.
+
+Why Edify
+=========
+
+A regular expression is easy to write and hard to read. Six months later nobody
+remembers what ``^(?:0x)?([0-9a-fA-F]{4})$`` was meant to accept, and the person
+reviewing the change that touches it has no way to be sure either. The syntax
+gives you nowhere to put a name, a comment, or a seam.
+
+Edify moves the pattern into ordinary Python, where all three fit:
+
+- Methods say what they do. ``.one_or_more().digit()`` needs no decoding.
+- The quantity comes before the thing it counts, the way you say it aloud —
+  ``.exactly(4).digit()`` is *exactly four digits*.
+- Every call returns a new builder, so a pattern you share can be extended in
+  two directions without either one disturbing the other.
+- A mistake raises an error that points at the call that caused it and names the
+  fix, rather than emitting a regex that is subtly wrong.
+
+A first pattern
+===============
+
+.. code-block:: python
+
+    from edify import RegexBuilder
+
+    # A 16-bit hex literal like "0xC0DE" — with the four hex digits captured.
+    hex_literal = (
+        RegexBuilder()
+        .start_of_input()
+        .optional().string("0x")
+        .capture()
+            .exactly(4).any_of().range("0", "9").range("a", "f").range("A", "F").end()
+        .end()
+        .end_of_input()
+    )
+
+    hex_literal.to_regex_string()   # '^(?:0x)?([0-9a-fA-F]{4})$'
+    hex_literal.test("0xC0DE")      # True
+    hex_literal.test("0xZZZZ")      # False
+
+Read the chain top to bottom and it tells you what it accepts.
+
+Patterns you don't have to write
+================================
+
+Edify ships 228 ready-made validators. Each is a callable pattern, so checking a
+value is a function call:
+
+.. code-block:: python
+
+    from edify.library import email, ipv4, semver
+
+    email("a@b.com")      # True
+    semver("1.4.0")       # True
+    ipv4("10.0.0.1")      # True
+    ipv4("999.1.1.1")     # False — the octet range is enforced
+
+They are assembled from 83 named fragments you can build with too, so a pattern
+of your own inherits the same range checks rather than approximating them:
+
+.. code-block:: python
+
+    from edify import Pattern, atoms
+
+    endpoint = (
+        Pattern().start_of_input()
+        .named_capture("host").use(atoms.ipv4).end()
+        .char(":")
+        .named_capture("port").use(atoms.port).end()
+        .end_of_input()
+    )
+
+    endpoint.to_regex().match("10.0.0.1:8080").groupdict()
+    # {'host': '10.0.0.1', 'port': '8080'}
+    endpoint("10.0.0.1:99999")   # False — 99999 is not a port
+
+Ask a pattern what it means
+===========================
+
+Because Edify keeps the structure rather than a string, it can describe a
+pattern back to you — in prose, as a diagram, or as an annotated verbose regex:
+
+.. code-block:: python
+
+    from edify import RegexBuilder
+
+    year = RegexBuilder().start_of_input().exactly(4).digit().end_of_input()
+    print(year.to_regex().explain())
+
+    # - The text must start with exactly 4 digits (0-9).
+    #
+    # Text this pattern accepts:
+    #     1234
+
+That same structure is what lets Edify warn you at build time about a pattern
+shaped for catastrophic backtracking, and round-trip a pattern through JSON.
+
+Install
+=======
+
+Edify requires **Python 3.11+**:
+
+.. code-block:: bash
+
+    pip install edify
+
+Optional extras add the alternate regex engine and the framework integrations:
+``edify[regex]``, ``edify[pydantic]``, ``edify[fastapi]``, ``edify[django]``, or
+``edify[all]``.
+
+Also in the box
+===============
+
+- **Introspection** — a plain-English explanation, an ASCII or rendered diagram,
+  or an annotated ``re.VERBOSE`` form of any pattern.
+- **Serialization** — round-trip a pattern through a dict or JSON and keep a
+  first-class pattern on the other side, not a flattened string.
+- **Integrations** — pydantic, FastAPI, and Django validators from a pattern.
+- **Testing helpers** — assert a pattern's contract beside its definition, and
+  snapshot what it emits.
+- **Reverse parsing** — turn an existing regex string back into a chain and read
+  what it does.
+
+Documentation
+=============
+
+`edify.readthedocs.io <https://edify.readthedocs.io>`_ has the guide, a page for
+every validator, and the full API reference. Examples throughout the site are
+live — edit the chain and the emitted regex and match results update as you
+type, with Edify running in your browser.
+
+License and contributing
+========================
+
+Edify is released under the `MIT License
+<https://github.com/luciferreeves/edify/blob/main/LICENSE>`_. Contributions are
+welcome — see `CONTRIBUTING.rst
+<https://github.com/luciferreeves/edify/blob/main/CONTRIBUTING.rst>`_ to get set up.