Merge branch 'master' of github.com:kcdodd/partis-pyproj

Author: kcdodd

README.md

@@ -13,6 +13,51 @@ The guiding principles adopted for ``partis.pyproj`` are:
 * A distribution is simply a collection of files,
   plus package meta-data for either source or binary (wheel) distribution formats.
 
+### Quickstart
+
+Below is a minimal example project structure for a pure Python package
+named `myproj`, and backend configuration in `pyproject.toml` to build
+source and binary (wheel) distributions for installation:
+
+- `src/myproj/__init__.py`
+- `tests/test_everything.py`
+- `LICENSE.txt`
+- `pyproject.toml`
+- `README.md`
+
+
+```toml
+# pyproject.toml
+[project]
+name = "myproj"
+description = "Project myproj"
+version = "0.0.1"
+readme = { file = "README.md" }
+license = { file = "LICENSE.txt" }
+dependencies = ['typing-extensions']
+
+[dependency-groups]
+test = ['pytest']
+
+[build-system]
+requires = ["partis-pyproj"]
+# point the frontend to the backend partis-pyproj
+build-backend = "partis.pyproj.backend"
+
+# configure the backend
+[tool.pyproj.dist]
+# patterns to ignore for both source and wheel distributions
+ignore = ['__pycache__', '*.py[cod]', '*.so', '*.egg-info', '.nox', '.pytest_cache', '.coverage']
+
+[tool.pyproj.dist.source]
+# copy everything needed to re-distribute the source code (pyproject.toml, readme, and license are added automatically)
+copy = ["src", "tests"]
+
+[tool.pyproj.dist.binary.purelib]
+# copy how it should appear installed in site-packages
+copy = [{ src = "src/myproj", dst = "myproj" }]
+```
+
 The process of building a source or binary distribution is broken down into
 three general stages:
 
@@ -24,7 +69,8 @@ three general stages:
   configuration, but otherwise avoids taking on the responsibility of a full build system.
 - **copy** - Copy files into the distribution.
 
-
+Running `python -m build` (or `pip wheel .`, `pip install .`, etc.) executes the `prepare`, `build`,
+and `copy` stages in order and writes the resulting sdist or wheel.
 The sequence of actions for a distribution is roughly:
 
 - `tool.pyproj.prep`: Run before anything else, used to fill in dynamic metadata or
@@ -55,10 +101,18 @@ formats and behaviors.
 * `dst` is relative, specifically depending on whether it is a source or binary (wheel) distribution and which install scheme is desired (`purelib`, `platlib`, etc.).
 * Destination file paths are constructed from matched source paths roughly equivalent
   to `{scheme}/dst/match.relative_to(src)`.
+* Symlinks that resolve within the project root are preserved; links that point
+  outside the tree or are dangling result in an error. Hidden files are treated
+  like any other path unless ignored.
+* Pattern matching uses POSIX-style `/` separators. On case-insensitive file
+  systems (e.g. Windows) different source files that would map to the same
+  destination path are considered collisions and abort the copy.
+* If multiple include rules map to the same destination file, the backend raises
+  an error to avoid silent overwrites.
 
 **Include patterns**
 
-* An `include` list is used to filter files or directories to be copied, expanded
+* An include list is used to filter files or directories to be copied, expanded
   to zero or more matches relative to `src`.
 * `glob` follows the format of [Path.glob](https://docs.python.org/3/library/pathlib.html#pathlib.Path.glob).
   If recursive pattern `**` is used, the glob will *not* match directories,
@@ -70,6 +124,14 @@ formats and behaviors.
 * `strip` can remove (up to) the given number of path components from the relative
   `src` path.
 
+  For example,
+
+  ```toml
+  include = [{ glob = "src/**/*.py", rematch = "src/(.*)", replace = "{0}", strip = 1 }]
+  ```
+
+  copies `src/pkg/mod.py` into the destination as `pkg/mod.py`.
+
 **Ignore patterns**
 
 * An `ignore` list follows the format of [git-ignore](https://git-scm.com/docs/gitignore#_pattern_format).
@@ -267,6 +329,11 @@ build_clean: BOOL?           # control cleanup (ie for development builds)
 enabled: (BOOL|MARKER)?      # environment marker
 ```
 
+Targets are executed sequentially. If a target fails or its entry point cannot
+be resolved, the remaining targets are skipped and the build aborts with an
+error message. Parallel execution is intentionally unsupported to keep ordering
+and cleanup deterministic.
+
 There are several entry points available as-is:
 
 - `partis.pyproj.builder:meson` - Support for [Meson Build system](https://mesonbuild.com/)  with the 'extra' ``partis-pyproj[meson]``
@@ -468,6 +535,10 @@ are available in any processing hook.
 Combined with an entry-point `kwargs`, these can be used to keep all
 conditional dependencies listed in ``pyproject.toml``.
 
+Passing an option that is not declared in `tool.pyproj.config` or providing a
+value of the wrong type results in a validation error before any build hooks are
+executed.
+
 
 The type is derived from the value parsed from ``pyproject.toml``.
 For example, the value of `3` is parsed as an integer, while ``3.0`` is parsed

src/pyproj/builder/__init__.py

@@ -3,5 +3,4 @@
 from .process import process
 from .download import download
 from .meson import meson
-from .cmake import cmake
-from .cargo import cargo
+from .cmake import cmake

src/pyproj/builder/cargo.py

@@ -63,13 +63,14 @@ def _init_pyproj(
   license_file: str = None
   copy_sources: list[str] = []
 
-  root.mkdir(exist_ok = True)
+  if not root.exists():
+    root.mkdir()
 
-  if not root.is_dir():
-    raise ValueError(f"Project is not a directory: {root}")
+  elif not root.is_dir():
+    raise FileExistsError(f"Project is not a directory: {root}")
 
   if pptoml_file.exists():
-    raise ValueError(f"Project already exists: {pptoml_file}")
+    raise FileExistsError(f"Project already exists: {pptoml_file}")
 
   if project is None:
     project = root.name

src/pyproj/cli/init_pyproj.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+from pathlib import Path
+import sys
+import tomli
+import pytest
+from partis.pyproj.cli.init_pyproj import _init_pyproj
+from partis.pyproj.cli import __main__ as cli
+
+#==============================================================================
+
+def _stub_metadata(_pkg: str):
+    return {"version": "1.0.0"}
+
+#==============================================================================
+
+def test_init_pyproj_creates_files(tmp_path, monkeypatch):
+    project_dir = tmp_path / "sample"
+    project_dir.mkdir()
+    pkg_dir = project_dir / "sample"
+    pkg_dir.mkdir()
+    (pkg_dir / "__init__.py").write_text("# pkg init\n")
+    (project_dir / "extra.txt").write_text("data")
+
+    monkeypatch.setattr("partis.pyproj.cli.init_pyproj.metadata", _stub_metadata)
+    monkeypatch.setattr("builtins.input", lambda *args, **kwargs: "y")
+
+    _init_pyproj(path=project_dir, project="sample", version="0.1.0", description="example")
+
+    pptoml_path = project_dir / "pyproject.toml"
+    assert pptoml_path.exists()
+    data = tomli.loads(pptoml_path.read_text())
+    assert data["project"]["name"] == "sample"
+    assert data["project"]["version"] == "0.1.0"
+    assert (project_dir / "README.md").exists()
+    assert (project_dir / "LICENSE.txt").exists()
+
+#==============================================================================
+
+def test_init_pyproj_abort(tmp_path, monkeypatch):
+    project_dir = tmp_path / "abort"
+    monkeypatch.setattr("partis.pyproj.cli.init_pyproj.metadata", _stub_metadata)
+    monkeypatch.setattr("builtins.input", lambda *args, **kwargs: "n")
+
+    _init_pyproj(path=project_dir, project="abort", version="0.1.0", description="")
+
+    assert not (project_dir / "pyproject.toml").exists()
+    assert not (project_dir / "README.md").exists()
+    assert not (project_dir / "LICENSE.txt").exists()
+
+#==============================================================================
+def test_cli_main_help(tmp_path, monkeypatch):
+  def _input(*args, **kwargs):
+    assert False
+
+  monkeypatch.setattr("builtins.input", _input)
+  monkeypatch.setattr(sys, "argv", ["partis-pyproj"])
+
+  cli.main()
+
+#==============================================================================
+def test_cli_main_creates_project(tmp_path, monkeypatch):
+    project_dir = tmp_path / "cli_proj"
+    monkeypatch.setattr("partis.pyproj.cli.init_pyproj.metadata", _stub_metadata)
+    monkeypatch.setattr("builtins.input", lambda *args, **kwargs: "y")
+    monkeypatch.setattr(sys, "argv", [
+        "partis-pyproj", "init", "--name", "cli_proj", "--version", "2.0.0", "--desc", "cli", str(project_dir)
+    ])
+
+    cli.main()
+
+    pptoml_path = project_dir / "pyproject.toml"
+    assert pptoml_path.exists()
+    data = tomli.loads(pptoml_path.read_text())
+    assert data["project"]["name"] == "cli_proj"
+    assert data["project"]["version"] == "2.0.0"
+
+#==============================================================================
+
+
+def test_init_pyproj_defaults(tmp_path, monkeypatch):
+    project_dir = tmp_path / "auto"
+    monkeypatch.setattr("partis.pyproj.cli.init_pyproj.metadata", _stub_metadata)
+    monkeypatch.setattr("builtins.input", lambda *args, **kwargs: "y")
+
+    _init_pyproj(path=project_dir, project=None, version="0.1.0", description="")
+
+    data = tomli.loads((project_dir / "pyproject.toml").read_text())
+    assert data["project"]["name"] == "auto"
+    assert data["project"]["description"] == "Package for auto"
+
+
+def test_init_pyproj_description_default_with_name(tmp_path, monkeypatch):
+    project_dir = tmp_path / "desc_only"
+    project_dir.mkdir()
+    monkeypatch.setattr("partis.pyproj.cli.init_pyproj.metadata", _stub_metadata)
+    monkeypatch.setattr("builtins.input", lambda *args, **kwargs: "y")
+
+    _init_pyproj(path=project_dir, project="pkg", version="0.1.0", description="")
+
+    data = tomli.loads((project_dir / "pyproject.toml").read_text())
+    assert data["project"]["name"] == "pkg"
+    assert data["project"]["description"] == "Package for pkg"
+
+
+def test_init_pyproj_path_not_directory(tmp_path, monkeypatch):
+    project_file = tmp_path / "notdir"
+    project_file.write_text("data")
+    monkeypatch.setattr("partis.pyproj.cli.init_pyproj.metadata", _stub_metadata)
+
+    with pytest.raises(FileExistsError):
+        _init_pyproj(path=project_file, project="x", version="0.1.0", description="x")
+
+
+def test_init_pyproj_existing_pyproject(tmp_path, monkeypatch):
+    project_dir = tmp_path / "exists"
+    project_dir.mkdir()
+    (project_dir / "pyproject.toml").write_text("[project]\nname='exists'\n")
+    monkeypatch.setattr("partis.pyproj.cli.init_pyproj.metadata", _stub_metadata)
+
+    with pytest.raises(FileExistsError):
+        _init_pyproj(path=project_dir, project="exists", version="0.1.0", description="")
+
+
+def test_init_pyproj_respects_gitignore(tmp_path, monkeypatch):
+    project_dir = tmp_path / "gitignore"
+    project_dir.mkdir()
+    pkg_dir = project_dir / "gitignore"
+    pkg_dir.mkdir()
+    (pkg_dir / "__init__.py").write_text("# pkg init\n")
+    (project_dir / ".gitignore").write_text("skip.txt\n")
+    (project_dir / "skip.txt").write_text("data")
+    (project_dir / "keep.txt").write_text("data")
+
+    monkeypatch.setattr("partis.pyproj.cli.init_pyproj.metadata", _stub_metadata)
+    monkeypatch.setattr("builtins.input", lambda *args, **kwargs: "y")
+
+    _init_pyproj(path=project_dir, project="gitignore", version="0.1.0", description="gi")
+
+    data = tomli.loads((project_dir / "pyproject.toml").read_text())
+    sources = data["tool"]["pyproj"]["dist"]["source"]["copy"]
+    assert "keep.txt" in sources
+    assert "skip.txt" not in sources
+
+
+def test_init_pyproj_preserves_existing_readme_and_license(tmp_path, monkeypatch):
+    project_dir = tmp_path / "preserve"
+    project_dir.mkdir()
+    (project_dir / "README.md").write_text("existing readme")
+    (project_dir / "LICENSE.txt").write_text("existing license")
+    monkeypatch.setattr("partis.pyproj.cli.init_pyproj.metadata", _stub_metadata)
+    monkeypatch.setattr("builtins.input", lambda *args, **kwargs: "y")
+
+    _init_pyproj(path=project_dir, project="preserve", version="0.1.0", description="desc")
+
+    assert (project_dir / "README.md").read_text() == "existing readme"
+    assert (project_dir / "LICENSE.txt").read_text() == "existing license"
+
+