edify 0.2.2__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-1.0.0/AUTHORS.rst

@@ -0,0 +1,6 @@
+
+Authors
+=======
+
+* Bobby - https://shi.foo
+* natsuoto / 夏音 - https://github.com/natsuoto

edify-1.0.0/CHANGELOG.rst

@@ -0,0 +1,133 @@
+
+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)
+------------------
+
+A maintenance release: Edify is dragged out of 2022 and back into modern shape. No new patterns or builder API. The minimum supported Python rises to 3.8.
+
+Breaking
+~~~~~~~~
+
+* Dropped support for Python 3.7. Edify now requires Python 3.8 or newer (:pr:`32`).
+
+Added
+~~~~~
+
+* Support for Python 3.12, 3.13, and 3.14, with the matrix and Read the Docs build configuration updated to match (:pr:`31`).
+
+Tooling and CI
+~~~~~~~~~~~~~~
+
+* Bumped GitHub Actions to current major versions: ``actions/checkout@v5``, ``actions/setup-python@v5``, ``github/codeql-action@v3``. All workflow jobs now run on the Node 20 runtime instead of the deprecated Node 16. ``pypa/gh-action-pypi-publish`` SHA refreshed to ``v1.14.0`` (:pr:`35`).
+* PyPy CI matrix moved off the EOL ``pypy-3.8`` line to the maintained ``pypy-3.10`` and ``pypy-3.11`` (:pr:`37`).
+* ``.pre-commit-config.yaml`` modernised: every hook pinned to an immutable tag instead of a floating branch ref, dead repo URLs corrected (``gitlab.com/pycqa/flake8`` → ``github.com/PyCQA/flake8``, ``timothycrosley/isort`` → ``PyCQA/isort``), and ``psf/black`` swapped for the upstream-recommended ``psf/black-pre-commit-mirror`` (:pr:`33`).
+
+Dependencies
+~~~~~~~~~~~~
+
+* Bumped minimum versions: ``setuptools >=75.0``, ``pip >=26.0.1``, ``virtualenv >=21.3.0``, ``six >=1.17.0``, ``sphinx >=7.4.7`` (:pr:`25`, :pr:`26`, :pr:`27`, :pr:`28`, :pr:`29`).
+
+Repository infrastructure
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Added ``.github/CODEOWNERS`` and ``natsuoto`` to ``AUTHORS.rst`` for the new agent-driven contribution flow (:pr:`39`).
+* Locked ``main``: 1 approving code-owner review required, 31 status-check contexts required (the full matrix), linear history enforced, no force pushes or deletions, applies to administrators.
+* Repo-level ``allow_auto_merge`` enabled — PRs auto-merge once review and CI gates pass.
+
+Housekeeping
+~~~~~~~~~~~~
+
+* Dropped a dead ``py37``/``pypy37`` exclusion from the cookiecutter Jinja template and refreshed the docs copyright year (:pr:`43`).
+* Updated author website URL in ``AUTHORS.rst`` and ``.cookiecutterrc`` (:pr:`41`).
+* Removed all cookiecutter regeneration scaffolding — ``.cookiecutterrc``, ``ci/bootstrap.py``, and ``ci/templates/`` (containing dead AppVeyor config and a workflow template that lagged the live one) — along with the ``[testenv:bootstrap]`` env, related ``MANIFEST.in`` / ``setup.cfg`` / ``.pre-commit-config.yaml`` exclusions, and the dead Python 3.7 branch in ``tests.local.sh``. The local-test script's per-version ``if/elif`` chain is now a single programmatic ``tox -e py$VERSION`` lookup, which adapts automatically when Python versions are added or removed from the matrix (:pr:`47`).
+
+0.2.2 (2022-12-22)
+------------------
+* Added Support for Python 3.11
+* Added more RegexBuilder Examples
+* Fixed Documentation Typos
+
+0.2.1 (2022-11-27)
+------------------
+
+* This is a Quick Fix Release to fix the incomplete release of 0.2.0. The release was intended to drop support for 3.6, but the metadata was not updated to reflect this. This release fixes that. v0.2.0 remains available on PyPI, but is incompatible with Python 3.6. Using it with other versions of Python is not a problem. Other than the metadata, the two releases are identical.
+
+0.2.0 (2022-11-27)
+------------------
+This is a minor release with a few new built-in validators along with some small changes and bug fixes.
+
+Validators added:
+~~~~~~~~~~~~~~~~~
+* URL Validator
+* UUID Validator
+* GUID Validator
+* SSN Validator
+* Mac Address (IEEE 802) Validator
+* Zip Code Validator
+* Password Validator
+
+Documentation:
+~~~~~~~~~~~~~~
+
+* Added documentation for new validators
+* Add warning for trade-offs in email regex validation
+
+Bug Fixes:
+~~~~~~~~~~
+
+* Fixed Phone pattern failing for service numbers and 4 digit numbers (See `#16 <https://github.com/luciferreeves/edify/issues/16>`_ for more information)
+
+
+0.1.0 (2022-09-10)
+------------------
+
+* First release on PyPI.

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.