plowman 0.1.0__tar.gz

plowman-0.1.0/LICENSE.md

@@ -0,0 +1,11 @@
+# BSD 3-Clause License
+
+Copyright © 2025 Stephanos Kuma.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

plowman-0.1.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.3
+Name: plowman
+Version: 0.1.0
+Summary: Dotfile farm manager
+Home-page: https://plowman.readthedocs.io/en/stable/
+License: BSD-3-Clause
+Keywords: dotfiles
+Author: Stephanos Kuma
+Author-email: "Stephanos Kuma" <stephanos@kuma.ai>
+Requires-Python: >=3.10
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Dist: dj-settings (~=8.0)
+Requires-Dist: jinja2 (~=3.1)
+Requires-Dist: pyutilkit (~=0.10)
+Project-URL: Documentation, https://plowman.readthedocs.io/en/stable/
+Project-URL: Repository, https://github.com/spapanik/plowman/
+Description-Content-Type: text/markdown
+
+# plowman: Dotfile farm manager
+
+[![build][build_badge]][build_url]
+[![lint][lint_badge]][lint_url]
+[![tests][tests_badge]][tests_url]
+[![license][licence_badge]][licence_url]
+[![codecov][codecov_badge]][codecov_url]
+[![readthedocs][readthedocs_badge]][readthedocs_url]
+[![pypi][pypi_badge]][pypi_url]
+[![downloads][pepy_badge]][pepy_url]
+[![build automation: yam][yam_badge]][yam_url]
+[![Lint: ruff][ruff_badge]][ruff_url]
+
+Long project description and tldr goes here
+
+## Links
+
+- [Documentation]
+- [Changelog]
+
+[build_badge]: https://github.com/spapanik/plowman/actions/workflows/build.yml/badge.svg
+[build_url]: https://github.com/spapanik/plowman/actions/workflows/build.yml
+[lint_badge]: https://github.com/spapanik/plowman/actions/workflows/lint.yml/badge.svg
+[lint_url]: https://github.com/spapanik/plowman/actions/workflows/lint.yml
+[tests_badge]: https://github.com/spapanik/plowman/actions/workflows/tests.yml/badge.svg
+[tests_url]: https://github.com/spapanik/plowman/actions/workflows/tests.yml
+[licence_badge]: https://img.shields.io/pypi/l/plowman
+[licence_url]: https://plowman.readthedocs.io/en/stable/LICENSE/
+[codecov_badge]: https://codecov.io/github/spapanik/plowman/graph/badge.svg?token=Q20F84BW72
+[codecov_url]: https://codecov.io/github/spapanik/plowman
+[readthedocs_badge]: https://readthedocs.org/projects/plowman/badge/?version=latest
+[readthedocs_url]: https://plowman.readthedocs.io/en/latest/
+[pypi_badge]: https://img.shields.io/pypi/v/plowman
+[pypi_url]: https://pypi.org/project/plowman
+[pepy_badge]: https://pepy.tech/badge/plowman
+[pepy_url]: https://pepy.tech/project/plowman
+[yam_badge]: https://img.shields.io/badge/build%20automation-yamk-success
+[yam_url]: https://github.com/spapanik/yamk
+[ruff_badge]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v1.json
+[ruff_url]: https://github.com/charliermarsh/ruff
+[Documentation]: https://plowman.readthedocs.io/en/stable/
+[Changelog]: https://plowman.readthedocs.io/en/stable/CHANGELOG/

plowman-0.1.0/docs/README.md

@@ -0,0 +1,42 @@
+# plowman: Dotfile farm manager
+
+[![build][build_badge]][build_url]
+[![lint][lint_badge]][lint_url]
+[![tests][tests_badge]][tests_url]
+[![license][licence_badge]][licence_url]
+[![codecov][codecov_badge]][codecov_url]
+[![readthedocs][readthedocs_badge]][readthedocs_url]
+[![pypi][pypi_badge]][pypi_url]
+[![downloads][pepy_badge]][pepy_url]
+[![build automation: yam][yam_badge]][yam_url]
+[![Lint: ruff][ruff_badge]][ruff_url]
+
+Long project description and tldr goes here
+
+## Links
+
+- [Documentation]
+- [Changelog]
+
+[build_badge]: https://github.com/spapanik/plowman/actions/workflows/build.yml/badge.svg
+[build_url]: https://github.com/spapanik/plowman/actions/workflows/build.yml
+[lint_badge]: https://github.com/spapanik/plowman/actions/workflows/lint.yml/badge.svg
+[lint_url]: https://github.com/spapanik/plowman/actions/workflows/lint.yml
+[tests_badge]: https://github.com/spapanik/plowman/actions/workflows/tests.yml/badge.svg
+[tests_url]: https://github.com/spapanik/plowman/actions/workflows/tests.yml
+[licence_badge]: https://img.shields.io/pypi/l/plowman
+[licence_url]: https://plowman.readthedocs.io/en/stable/LICENSE/
+[codecov_badge]: https://codecov.io/github/spapanik/plowman/graph/badge.svg?token=Q20F84BW72
+[codecov_url]: https://codecov.io/github/spapanik/plowman
+[readthedocs_badge]: https://readthedocs.org/projects/plowman/badge/?version=latest
+[readthedocs_url]: https://plowman.readthedocs.io/en/latest/
+[pypi_badge]: https://img.shields.io/pypi/v/plowman
+[pypi_url]: https://pypi.org/project/plowman
+[pepy_badge]: https://pepy.tech/badge/plowman
+[pepy_url]: https://pepy.tech/project/plowman
+[yam_badge]: https://img.shields.io/badge/build%20automation-yamk-success
+[yam_url]: https://github.com/spapanik/yamk
+[ruff_badge]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v1.json
+[ruff_url]: https://github.com/charliermarsh/ruff
+[Documentation]: https://plowman.readthedocs.io/en/stable/
+[Changelog]: https://plowman.readthedocs.io/en/stable/CHANGELOG/

plowman-0.1.0/pyproject.toml

@@ -0,0 +1,174 @@
+[build-system]
+requires = [
+    "phosphorus>=0.10",
+]
+build-backend = "phosphorus.construction.api"
+
+[project]
+name = "plowman"
+dynamic = [
+    "version",
+]
+
+authors = [
+    { name = "Stephanos Kuma", email = "stephanos@kuma.ai" },
+]
+license = { text = "BSD-3-Clause" }
+
+readme = "docs/README.md"
+description = "Dotfile farm manager"
+keywords = [
+    "dotfiles",
+]
+classifiers = [
+    "Development Status :: 1 - Planning",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "License :: OSI Approved :: BSD License",
+    "Intended Audience :: Developers",
+]
+
+requires-python = ">=3.10"
+dependencies = [
+    "dj_settings~=8.0",
+    "jinja2~=3.1",
+    "pyutilkit~=0.10",
+]
+
+[project.urls]
+homepage = "https://plowman.readthedocs.io/en/stable/"
+repository = "https://github.com/spapanik/plowman/"
+documentation = "https://plowman.readthedocs.io/en/stable/"
+
+[project.scripts]
+plm = "plowman.__main__:main"
+
+[dependency-groups]
+dev = [
+    "ipdb~=0.13",
+    "ipython~=8.37",
+    "ptpython~=3.0",
+    { include-group = "lint" },
+    { include-group = "test" },
+    { include-group = "docs" },
+]
+lint = [
+    "mypy~=1.18",
+    "ruff~=0.14",
+    { include-group = "test_core" },
+]
+test = [
+    "pytest-cov~=7.0",
+    { include-group = "test_core" },
+]
+test_core = [
+    "pytest~=9.0",
+]
+docs = [
+    "mkdocs~=1.6",
+    "mkdocs-material~=9.6",
+    "mkdocs-material-extensions~=1.3",
+    "pygments~=2.19",
+    "pymdown-extensions~=10.15",
+]
+
+[tool.phosphorus.dynamic.version]
+file = "src/plowman/__version__.py"
+
+[tool.mypy]
+check_untyped_defs = true
+disallow_any_decorated = true
+disallow_any_explicit = true
+disallow_any_expr = false          # many builtins are Any
+disallow_any_generics = true
+disallow_any_unimported = true
+disallow_incomplete_defs = true
+disallow_subclassing_any = true
+disallow_untyped_calls = true
+disallow_untyped_decorators = true
+disallow_untyped_defs = true
+extra_checks = true
+ignore_missing_imports = true
+no_implicit_reexport = true
+show_column_numbers = true
+show_error_codes = true
+strict_equality = true
+warn_redundant_casts = true
+warn_return_any = true
+warn_unused_configs = true
+warn_unused_ignores = true
+warn_unreachable = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_any_decorated = false # mock.MagicMock is Any
+
+[tool.ruff]
+src = [
+    "src",
+]
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "ALL",
+]
+ignore = [
+    "C901",   # Adding a limit to complexity is too arbitrary
+    "COM812", # Avoid conflicts with the formatter
+    "D10",    # Not everything needs a docstring
+    "D203",   # Prefer `no-blank-line-before-class` (D211)
+    "D213",   # Prefer `multi-line-summary-first-line` (D212)
+    "PLR09",  # Adding a limit to complexity is too arbitrary
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "FBT001",  # Test arguments are handled by pytest
+    "PLR2004", # Tests should contain magic number comparisons
+    "S101",    # Pytest needs assert statements
+]
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "all"
+
+[tool.ruff.lint.flake8-tidy-imports.banned-api]
+"mock".msg = "Use unittest.mock"
+"pytz".msg = "Use zoneinfo"
+
+[tool.ruff.lint.isort]
+combine-as-imports = true
+forced-separate = [
+    "tests",
+]
+split-on-trailing-comma = false
+
+[tool.pytest]
+minversion = "9.0"
+strict = true
+addopts = ["-ra", "-v"]
+testpaths = [
+    "tests",
+]
+
+[tool.coverage.run]
+branch = true
+source = [
+    "src/",
+]
+data_file = ".cov_cache/coverage.dat"
+omit = [
+    "src/**/type_defs.py",
+]
+
+[tool.coverage.report]
+exclude_also = [
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+    "raise UnreachableCodeError",
+]
+fail_under = 100
+precision = 2
+show_missing = true
+skip_covered = true
+skip_empty = true

plowman-0.1.0/src/plowman/__main__.py

@@ -0,0 +1,9 @@
+from plowman.commands.sow import SowCommand
+from plowman.lib.cli import parse_args
+
+
+def main() -> None:
+    args = parse_args()
+    match args.subcommand:
+        case "sow":
+            SowCommand(verbosity=args.verbosity).run()

plowman-0.1.0/src/plowman/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

plowman-0.1.0/src/plowman/commands/base.py

@@ -0,0 +1,22 @@
+from pathlib import Path
+
+from dj_settings.settings import ConfigParser
+
+from plowman.lib.constants import CONFIG_PATH
+from plowman.lib.exceptions import MissingConfigError
+
+
+class BaseCommand:
+    __slots__ = ("config",)
+
+    def __init__(self) -> None:
+        self.config = self._get_config()
+
+    def _get_config(self) -> dict[Path, list[str]]:
+        if not CONFIG_PATH.exists():
+            raise MissingConfigError
+        config = ConfigParser([CONFIG_PATH]).data["config"]
+        return {Path(path): granaries for path, granaries in config.items()}
+
+    def run(self) -> None:
+        raise NotImplementedError

plowman-0.1.0/src/plowman/commands/sow.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import filecmp
+import shutil
+from typing import TYPE_CHECKING
+
+from plowman.commands.base import BaseCommand
+from plowman.lib.constants import HOME
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class SowCommand(BaseCommand):
+    __slots__ = ("verbosity",)
+
+    def __init__(self, verbosity: int) -> None:
+        super().__init__()
+        self.verbosity = verbosity
+
+    def sow_granary(self, granary_path: Path) -> None:
+        for file in granary_path.rglob("*"):
+            if file.is_dir():
+                continue
+            farm = HOME.joinpath(file.relative_to(granary_path)).parent
+            farm.mkdir(exist_ok=True, parents=True)
+            target = farm.joinpath(file.name)
+            if target.exists() and filecmp.cmp(file, target, shallow=False):
+                continue
+
+            target.unlink(missing_ok=True)
+            shutil.copy2(file, target)
+
+    def run(self) -> None:
+        for path, granaries in self.config.items():
+            for granary in granaries:
+                self.sow_granary(path.joinpath(granary))

plowman-0.1.0/src/plowman/lib/cli.py

@@ -0,0 +1,44 @@
+import sys
+from argparse import ArgumentParser
+from dataclasses import dataclass
+from typing import Literal
+
+from plowman.__version__ import __version__
+
+sys.tracebacklimit = 0
+
+
+@dataclass(frozen=True, slots=True)
+class PlowmanArgs:
+    subcommand: Literal["sow"]
+    verbosity: int
+
+
+def parse_args() -> PlowmanArgs:
+    parser = ArgumentParser(prog="plowman", description="Dotfile farm manager")
+    parser.add_argument(
+        "-V",
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+        help="print the version and exit",
+    )
+
+    parent_parser = ArgumentParser(add_help=False)
+    parent_parser.add_argument(
+        "-v",
+        "--verbose",
+        action="count",
+        default=0,
+        dest="verbosity",
+        help="increase the level of verbosity",
+    )
+
+    subparsers = parser.add_subparsers(dest="subcommand", required=True)
+    subparsers.add_parser("sow", parents=[parent_parser])
+
+    args = parser.parse_args()
+    if args.verbosity > 0:
+        sys.tracebacklimit = 1000
+
+    return PlowmanArgs(subcommand=args.subcommand, verbosity=args.verbosity)

plowman-0.1.0/src/plowman/lib/constants.py

@@ -0,0 +1,4 @@
+from pathlib import Path
+
+HOME = Path.home()
+CONFIG_PATH = HOME.joinpath(".config", "plowman", "config.yaml")

plowman-0.1.0/src/plowman/lib/exceptions.py

@@ -0,0 +1,10 @@
+from plowman.lib.constants import CONFIG_PATH
+
+
+class MissingConfigError(FileNotFoundError):
+    def __init__(self) -> None:
+        msg = (
+            "Configuration file not found. "
+            f"Please create a configuration file at `{CONFIG_PATH}`."
+        )
+        super().__init__(msg)