chore: migrate from flat to src layout

The src layout helps prevent a number of issues during development. A
discussion by Python's packaging group of the pros can be found at
https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/.

Fundamentally, it prevents `import pact` from finding the local `pact/`
directory, and ensures that the package is installed
correctly (typically as an editable installation).

Signed-off-by: JP-Ellis <[email protected]>

.gitignore

@@ -1,11 +1,11 @@
 ################################################################################
 ## Pact Python Specific
 ################################################################################
-pact/bin
-pact/data
+src/pact/bin
+src/pact/data
 
 # Version is determined from the VCS
-pact/__version__.py
+src/pact/__version__.py
 
 ################################################################################
 ## Standard Templates

.gitmodules

@@ -1,3 +1,3 @@
 [submodule "compatibility-suite"]
-	path = tests/v3/compatiblity_suite/definition
+	path = tests/v3/compatibility_suite/definition
 	url = ../pact-compatibility-suite.git

.pre-commit-config.yaml

@@ -42,8 +42,8 @@ repos:
     hooks:
       - id: ruff
         # Exclude python files in pact/** and tests/**, except for the
-        # files in pact/v3/** and tests/v3/**.
-        exclude: ^(pact|tests)/(?!v3/).*\.py$
+        # files in src/pact/v3/** and tests/v3/**.
+        exclude: ^(src/pact|tests)/(?!v3/).*\.py$
         args: [--fix, --exit-non-zero-on-fix]
       - id: ruff-format
         exclude: ^(pact|tests)/(?!v3/).*\.py$
@@ -63,7 +63,7 @@ repos:
         entry: hatch run mypy
         language: system
         types: [python]
-        exclude: ^(pact|tests)/(?!v3/).*\.py$
+        exclude: ^(src/pact|tests)/(?!v3/).*\.py$
         stages: [pre-push]
 
   - repo: https://github.com/igorshubovych/markdownlint-cli

hatch_build.py

@@ -27,7 +27,7 @@
 from hatchling.builders.hooks.plugin.interface import BuildHookInterface
 from packaging.tags import sys_tags
 
-ROOT_DIR = Path(__file__).parent.resolve()
+PACT_ROOT_DIR = Path(__file__).parent.resolve() / "src" / "pact"
 
 # Latest version available at:
 # https://github.com/pact-foundation/pact-ruby-standalone/releases
@@ -73,7 +73,7 @@ def __init__(self, *args: Any, **kwargs: Any) -> None:  # noqa: ANN401
     def clean(self, versions: list[str]) -> None:  # noqa: ARG002
         """Clean up any files created by the build hook."""
         for subdir in ["bin", "lib", "data"]:
-            shutil.rmtree(ROOT_DIR / "pact" / subdir, ignore_errors=True)
+            shutil.rmtree(PACT_ROOT_DIR / subdir, ignore_errors=True)
 
     def initialize(
         self,
@@ -107,7 +107,7 @@ def pact_bin_install(self, version: str) -> None:
         """
         Install the Pact standalone binaries.
 
-        The binaries are installed in `pact/bin`, and the relevant version for
+        The binaries are installed in `src/pact/bin`, and the relevant version for
         the current operating system is determined automatically.
 
         Args:
@@ -188,23 +188,28 @@ def _pact_bin_extract(self, artifact: Path) -> None:
         """
         Extract the Pact binaries.
 
-        The upstream distributables contain a lot of files which are not needed
-        for this library. This function ensures that only the files in
-        `pact/bin` are extracted to avoid unnecessary bloat.
+        The binaries in the `bin` directory require the underlying Ruby runtime
+        to be present, which is included in the `lib` directory.
 
         Args:
             artifact: The path to the downloaded artifact.
         """
-        if str(artifact).endswith(".zip"):
-            with zipfile.ZipFile(artifact) as f:
-                f.extractall(ROOT_DIR)  # noqa: S202
-
-        if str(artifact).endswith(".tar.gz"):
-            with tarfile.open(artifact) as f:
-                f.extractall(ROOT_DIR)  # noqa: S202
-
-        # Cleanup the extract `README.md`
-        (ROOT_DIR / "pact" / "README.md").unlink()
+        with tempfile.TemporaryDirectory() as tmpdir:
+            if str(artifact).endswith(".zip"):
+                with zipfile.ZipFile(artifact) as f:
+                    f.extractall(tmpdir)  # noqa: S202
+
+            if str(artifact).endswith(".tar.gz"):
+                with tarfile.open(artifact) as f:
+                    f.extractall(tmpdir)  # noqa: S202
+
+            for d in ["bin", "lib"]:
+                if (PACT_ROOT_DIR / d).is_dir():
+                    shutil.rmtree(PACT_ROOT_DIR / d)
+                shutil.copytree(
+                    Path(tmpdir) / "pact" / d,
+                    PACT_ROOT_DIR / d,
+                )
 
     def pact_lib_install(self, version: str) -> None:
         """
@@ -415,7 +420,7 @@ def _pact_lib_cffi(self, includes: list[str]) -> None:
             library_dirs=[str(self.tmpdir)],
         )
         output = Path(ffibuilder.compile(verbose=True, tmpdir=str(self.tmpdir)))
-        shutil.copy(output, ROOT_DIR / "pact" / "v3")
+        shutil.copy(output, PACT_ROOT_DIR / "v3")
 
     def _download(self, url: str) -> Path:
         """
@@ -431,7 +436,7 @@ def _download(self, url: str) -> Path:
             The path to the downloaded artifact.
         """
         filename = url.split("/")[-1]
-        artifact = ROOT_DIR / "pact" / "data" / filename
+        artifact = PACT_ROOT_DIR / "data" / filename
         artifact.parent.mkdir(parents=True, exist_ok=True)
 
         if not artifact.exists():

pyproject.toml

@@ -100,15 +100,33 @@ build-backend = "hatchling.build"
 source = "vcs"
 
 [tool.hatch.build.hooks.vcs]
-version-file = "pact/__version__.py"
-
-[tool.hatch.build]
-include = ["**/py.typed", "**/*.md", "LICENSE", "pact/**/*.py", "pact/**/*.pyi"]
+version-file = "src/pact/__version__.py"
+
+[tool.hatch.build.targets.sdist]
+include = [
+  # Source
+  "/src/pact/**/*.py",
+  "/src/pact/**/*.pyi",
+  "/src/pact/**/py.typed",
+
+  # Metadata
+  "*.md",
+  "LICENSE",
+]
 
 [tool.hatch.build.targets.wheel]
-# Ignore the data files in the wheel as their contents are already included
-# in the package.
-artifacts = ["pact/bin/*", "pact/lib/*", "pact/v3/_ffi.*"]
+packages = ["/src/pact"]
+include = [
+  # Source
+  "/src/pact/**/*.py",
+  "/src/pact/**/*.pyi",
+  "/src/pact/**/py.typed",
+]
+artifacts = [
+  "/src/pact/bin/*",    # Ruby executables
+  "/src/pact/lib/*",    # Ruby library
+  "/src/pact/v3/_ffi.*" # Rust library
+]
 
 [tool.hatch.build.targets.wheel.hooks.custom]
 
@@ -135,8 +153,8 @@ format     = "ruff format {args}"
 test       = "pytest tests/ {args}"
 example    = "pytest examples/ {args}"
 all        = ["format", "lint", "typecheck", "test", "example"]
-docs       = ["mkdocs serve {args}"]
-docs-build = ["mkdocs build {args}"]
+docs       = "mkdocs serve {args}"
+docs-build = "mkdocs build {args}"
 
 # Test environment for running unit tests. This automatically tests against all
 # supported Python versions.
@@ -173,6 +191,10 @@ markers = [
 ## Coverage
 ################################################################################
 
+[tool.coverage.paths]
+pact = ["/src/pact"]
+tests = ["/examples", "/tests"]
+
 [tool.coverage.report]
 exclude_lines = [
   "if __name__ == .__main__.:", # Ignore non-runnable code
@@ -191,25 +213,25 @@ target-version = "py38"
 # TODO: Remove the explicity extend-exclude once astral-sh/ruff#6262 is fixed.
 # https://github.com/pact-foundation/pact-python/issues/458
 extend-exclude = [
-  # "pact/*.py",
-  # "pact/cli/*.py",
-  # "tests/*.py",
-  # "tests/cli/*.py",
-  "pact/__init__.py",
-  "pact/__version__.py",
-  "pact/broker.py",
-  "pact/cli/*.py",
-  "pact/constants.py",
-  "pact/consumer.py",
-  "pact/http_proxy.py",
-  "pact/matchers.py",
-  "pact/message_consumer.py",
-  "pact/message_pact.py",
-  "pact/message_provider.py",
-  "pact/pact.py",
-  "pact/provider.py",
-  "pact/verifier.py",
-  "pact/verify_wrapper.py",
+  # "src/pact/*.py",
+  # "src/pact/cli/*.py",
+  # "src/tests/*.py",
+  # "src/tests/cli/*.py",
+  "src/pact/__init__.py",
+  "src/pact/__version__.py",
+  "src/pact/broker.py",
+  "src/pact/cli/*.py",
+  "src/pact/constants.py",
+  "src/pact/consumer.py",
+  "src/pact/http_proxy.py",
+  "src/pact/matchers.py",
+  "src/pact/message_consumer.py",
+  "src/pact/message_pact.py",
+  "src/pact/message_provider.py",
+  "src/pact/pact.py",
+  "src/pact/provider.py",
+  "src/pact/verifier.py",
+  "src/pact/verify_wrapper.py",
   "tests/__init__.py",
   "tests/cli/*.py",
   "tests/conftest.py",
@@ -264,7 +286,7 @@ docstring-code-format = true
 ################################################################################
 
 [tool.mypy]
-exclude = '^(pact|tests)/(?!v3).+\.py$'
+exclude = '^(src/pact|tests)/(?!v3).+\.py$'
 
 ################################################################################
 ## CI Build Wheel

tests/v3/compatiblity_suite/test_v1_consumer.py → tests/v3/compatibility_suite/test_v1_consumer.py

@@ -7,8 +7,11 @@
 import pytest
 from pytest_bdd import given, parsers, scenario
 
-from tests.v3.compatiblity_suite.util import InteractionDefinition, parse_markdown_table
-from tests.v3.compatiblity_suite.util.consumer import (
+from tests.v3.compatibility_suite.util import (
+    InteractionDefinition,
+    parse_markdown_table,
+)
+from tests.v3.compatibility_suite.util.consumer import (
     a_response_is_returned,
     request_n_is_made_to_the_mock_server,
     request_n_is_made_to_the_mock_server_with_the_following_changes,

tests/v3/compatiblity_suite/test_v2_consumer.py → tests/v3/compatibility_suite/test_v2_consumer.py

@@ -6,8 +6,11 @@
 
 from pytest_bdd import given, parsers, scenario
 
-from tests.v3.compatiblity_suite.util import InteractionDefinition, parse_markdown_table
-from tests.v3.compatiblity_suite.util.consumer import (
+from tests.v3.compatibility_suite.util import (
+    InteractionDefinition,
+    parse_markdown_table,
+)
+from tests.v3.compatibility_suite.util.consumer import (
     a_response_is_returned,
     request_n_is_made_to_the_mock_server,
     request_n_is_made_to_the_mock_server_with_the_following_changes,

tests/v3/compatiblity_suite/test_v3_consumer.py → tests/v3/compatibility_suite/test_v3_consumer.py

@@ -10,8 +10,8 @@
 from pytest_bdd import given, parsers, scenario, then
 
 from pact.v3.pact import HttpInteraction, Pact
-from tests.v3.compatiblity_suite.util import parse_markdown_table
-from tests.v3.compatiblity_suite.util.consumer import (
+from tests.v3.compatibility_suite.util import parse_markdown_table
+from tests.v3.compatibility_suite.util.consumer import (
     the_pact_file_for_the_test_is_generated,
 )
 

tests/v3/compatiblity_suite/test_v4_consumer.py → tests/v3/compatibility_suite/test_v4_consumer.py

@@ -9,8 +9,8 @@
 from pytest_bdd import given, parsers, scenario, then
 
 from pact.v3.pact import HttpInteraction, Pact
-from tests.v3.compatiblity_suite.util import string_to_int
-from tests.v3.compatiblity_suite.util.consumer import (
+from tests.v3.compatibility_suite.util import string_to_int
+from tests.v3.compatibility_suite.util.consumer import (
     the_pact_file_for_the_test_is_generated,
 )
 

tests/v3/compatiblity_suite/util/consumer.py → tests/v3/compatibility_suite/util/consumer.py

@@ -15,7 +15,7 @@
 from yarl import URL
 
 from pact.v3 import Pact
-from tests.v3.compatiblity_suite.util import (
+from tests.v3.compatibility_suite.util import (
     FIXTURES_ROOT,
     parse_markdown_table,
     string_to_int,
@@ -27,7 +27,7 @@
     from pathlib import Path
 
     from pact.v3.pact import HttpInteraction, PactServer
-    from tests.v3.compatiblity_suite.util import InteractionDefinition
+    from tests.v3.compatibility_suite.util import InteractionDefinition
 
 logger = logging.getLogger(__name__)