dploy 0.1.1__tar.gz → 0.1.3__tar.gz

dploy-0.1.3/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: dploy
+Version: 0.1.3
+Summary: Provides functionality similar to GNU Stow as a cross platform CLI tool and Python 3 module
+License-Expression: MIT
+License-File: LICENSE.txt
+Author: Ryan Carney
+Author-email: arecarn@gmail.com
+Requires-Python: >=3.10
+Classifier: Development Status :: 4 - Beta
+Classifier: Topic :: Utilities
+Project-URL: Homepage, https://github.com/arecarn/dploy
+Description-Content-Type: text/markdown
+
+# Dploy
+
+Dploy is a tool for creating symbolic links similarly to [GNU
+Stow](https://www.gnu.org/software/stow/). It is provided as a CLI tool and
+Python 3.10+ module and supports Windows, Linux, and OSX.
+
+Dploy's command `stow` creates symbolic links to the contents of source
+directories or packages in a specified destination directory. Repeating the
+`stow` command with the same arguments will confirm that the contents of the
+package have been symbolically linked.
+
+Dploy's command `unstow` removes symbolic links that resulted from `stow`
+commands. Repeating the `unstow` command with the same arguments will confirm
+that the links to stowed packages have been removed.
+
+## Installation
+
+* Latest Release: `pip install dploy`
+* Development Version: `pip install git+https://github.com/arecarn/dploy.git`
+
+## Basic CLI Usage
+
+* `dploy stow <source-directory>... <destination-directory>`
+* `dploy unstow <source-directory>... <destination-directory>`
+* `dploy clean <source-directory>... <destination-directory>`
+* `dploy --help`
+
+## Rationale
+
+Dploy started out as simple Python script to create symbolic links to my
+dotfiles for Windows, Mac, and Linux. Over time I keep improving and tweaking my
+script to suit my needs, but I was running into a problem.  Keeping all the
+files I wanted to link in a config file was becoming a real pain in the neck.
+
+I started looking for another solution to solve my problem, and found many
+alternatives but none of them seemed to be a good fit. The solution that seemed
+the most promising was using GNU Stow. It seemed like the most simple elegant
+solution to the problem. The only issue was that it didn't support Windows.
+
+Then I thought to myself, why can't I just create my own version of Stow that
+work on Windows, Linux and OSX. So after that my I started morphing
+simple python script into what would become Dploy and learned a lot more about
+python in the process.
+
+## How does it compare with GNU Stow?
+
+Below are just a few few major points of comparison between GNU stow and Dploy.
+
+* Like GNU Stow Dploy runs in two passes. First by collecting the actions
+  required to complete the command and verifying that the command can
+  completed without any issues. If no issues are detected then the second
+  pass executes these actions are execute to complete the command. Otherwise
+  Dploy will exit and indicate why the command can not be completed. This way a
+  stow or unstow operation is atomic and never partially done.
+
+* Like Stow, Dploy supports tree folding and tree unfolding.
+
+* Unlike Stow, Dploy requires an explicit source(s) and a destination
+  directory.
+
+* Unlike Stow, Dploy does not have any concept of ownership, but will only
+  operate on symbolic links and the creation or removal of directories for these
+  symbolic links.
+

dploy-0.1.3/README.md

@@ -0,0 +1,63 @@
+# Dploy
+
+Dploy is a tool for creating symbolic links similarly to [GNU
+Stow](https://www.gnu.org/software/stow/). It is provided as a CLI tool and
+Python 3.10+ module and supports Windows, Linux, and OSX.
+
+Dploy's command `stow` creates symbolic links to the contents of source
+directories or packages in a specified destination directory. Repeating the
+`stow` command with the same arguments will confirm that the contents of the
+package have been symbolically linked.
+
+Dploy's command `unstow` removes symbolic links that resulted from `stow`
+commands. Repeating the `unstow` command with the same arguments will confirm
+that the links to stowed packages have been removed.
+
+## Installation
+
+* Latest Release: `pip install dploy`
+* Development Version: `pip install git+https://github.com/arecarn/dploy.git`
+
+## Basic CLI Usage
+
+* `dploy stow <source-directory>... <destination-directory>`
+* `dploy unstow <source-directory>... <destination-directory>`
+* `dploy clean <source-directory>... <destination-directory>`
+* `dploy --help`
+
+## Rationale
+
+Dploy started out as simple Python script to create symbolic links to my
+dotfiles for Windows, Mac, and Linux. Over time I keep improving and tweaking my
+script to suit my needs, but I was running into a problem.  Keeping all the
+files I wanted to link in a config file was becoming a real pain in the neck.
+
+I started looking for another solution to solve my problem, and found many
+alternatives but none of them seemed to be a good fit. The solution that seemed
+the most promising was using GNU Stow. It seemed like the most simple elegant
+solution to the problem. The only issue was that it didn't support Windows.
+
+Then I thought to myself, why can't I just create my own version of Stow that
+work on Windows, Linux and OSX. So after that my I started morphing
+simple python script into what would become Dploy and learned a lot more about
+python in the process.
+
+## How does it compare with GNU Stow?
+
+Below are just a few few major points of comparison between GNU stow and Dploy.
+
+* Like GNU Stow Dploy runs in two passes. First by collecting the actions
+  required to complete the command and verifying that the command can
+  completed without any issues. If no issues are detected then the second
+  pass executes these actions are execute to complete the command. Otherwise
+  Dploy will exit and indicate why the command can not be completed. This way a
+  stow or unstow operation is atomic and never partially done.
+
+* Like Stow, Dploy supports tree folding and tree unfolding.
+
+* Unlike Stow, Dploy requires an explicit source(s) and a destination
+  directory.
+
+* Unlike Stow, Dploy does not have any concept of ownership, but will only
+  operate on symbolic links and the creation or removal of directories for these
+  symbolic links.

dploy-0.1.3/dploy/__init__.py

@@ -0,0 +1,35 @@
+"""
+dploy script is an attempt at creating a clone of GNU stow that will work on
+Windows as well as *nix
+"""
+
+from dploy import linkcmd
+from dploy import stowcmd
+
+
+def stow(sources, dest, is_silent=True, is_dry_run=False, ignore_patterns=None):
+    """
+    sub command stow
+    """
+    stowcmd.Stow(sources, dest, is_silent, is_dry_run, ignore_patterns)
+
+
+def unstow(sources, dest, is_silent=True, is_dry_run=False, ignore_patterns=None):
+    """
+    sub command unstow
+    """
+    stowcmd.UnStow(sources, dest, is_silent, is_dry_run, ignore_patterns)
+
+
+def clean(sources, dest, is_silent=True, is_dry_run=False, ignore_patterns=None):
+    """
+    sub command clean
+    """
+    stowcmd.Clean(sources, dest, is_silent, is_dry_run, ignore_patterns)
+
+
+def link(source, dest, is_silent=True, is_dry_run=False, ignore_patterns=None):
+    """
+    sub command link
+    """
+    linkcmd.Link(source, dest, is_silent, is_dry_run, ignore_patterns)

{dploy-0.1.1 → dploy-0.1.3}/dploy/__main__.py

@@ -1,18 +1,17 @@
-#!/usr/bin/env python3
-
-"""
-The entry point when dploy is called as a module
-"""
-
-import sys
-assert sys.version_info >= (3, 3), "Requires Python 3.3 or Greater"
-import dploy.cli as cli
-
-def main():
-    """
-    main entry point when using dploy from the command line
-    """
-    cli.run()
-
-if __name__ == '__main__':
-    main()
+#!/usr/bin/env python3
+"""
+The entry point when dploy is called as a module
+"""
+
+from dploy import cli
+
+
+def main():
+    """
+    main entry point when using dploy from the command line
+    """
+    cli.run()
+
+
+if __name__ == "__main__":
+    main()

{dploy-0.1.1 → dploy-0.1.3}/dploy/actions.py

@@ -3,25 +3,86 @@ This module contains the actions that are combined to perform dploy's sub
 commands
 """
 
-import dploy.utils as utils
+from collections import defaultdict
+from dploy import utils
 
 
-class AbstractBaseAction():
+class Actions:
+    """
+    A class that collects and executes action objects
+    """
+
+    def __init__(self, is_silent, is_dry_run):
+        self.actions = []
+        self.is_silent = is_silent
+        self.is_dry_run = is_dry_run
+
+    def add(self, action):
+        """
+        Adds an action
+        """
+        self.actions.append(action)
+
+    def execute(self):
+        """
+        Prints and executes actions
+        """
+        for action in self.actions:
+            if not self.is_silent:
+                print(action)
+            if not self.is_dry_run:
+                action.execute()
+
+    def get_unlink_actions(self):
+        """
+        get the current Unlink() actions from the self.actions
+        """
+        return [a for a in self.actions if isinstance(a, UnLink)]
+
+    def get_unlink_target_parents(self):
+        """
+        Get list of the parents for the current Unlink() actions from
+        self.actions
+        """
+        unlink_actions = self.get_unlink_actions()
+        # sort for deterministic output
+        return sorted(set([a.target.parent for a in unlink_actions]))
+
+    def get_unlink_targets(self):
+        """
+        Get list of the targets for the current Unlink() actions from
+        self.actions
+        """
+        unlink_actions = self.get_unlink_actions()
+        return [a.target for a in unlink_actions]
+
+    def get_duplicates(self):
+        """
+        return a tuple containing tuples with the following structure
+        (link destination, [indices of duplicates])
+        """
+        tally = defaultdict(list)
+        for index, action in enumerate(self.actions):
+            if isinstance(action, SymbolicLink):
+                tally[action.dest].append(index)
+        # sort for deterministic output
+        return sorted([indices for _, indices in tally.items() if len(indices) > 1])
+
+
+class AbstractBaseAction:
     # pylint: disable=too-few-public-methods
     """
     An abstract base class that define the interface for actions
     """
-    def __init__(self):
-        pass
 
-    def _logic(self):
+    def __init__(self):
         pass
 
     def execute(self):
         """
-        function that executes _logic() of each derived action
+        function that executes the logic of each concrete action
         """
-        self._logic()
+        pass
 
 
 class SymbolicLink(AbstractBaseAction):
@@ -29,6 +90,7 @@ class SymbolicLink(AbstractBaseAction):
     """
     Action to create a symbolic link relative to the source of the link
     """
+
     def __init__(self, subcmd, source, dest):
         super().__init__()
         self.source = source
@@ -36,12 +98,13 @@ class SymbolicLink(AbstractBaseAction):
         self.subcmd = subcmd
         self.dest = dest
 
-    def _logic(self):
+    def execute(self):
         self.dest.symlink_to(self.source_relative)
 
     def __repr__(self):
         return "dploy {subcmd}: link {dest} => {source}".format(
-            subcmd=self.subcmd, dest=self.dest, source=self.source_relative)
+            subcmd=self.subcmd, dest=self.dest, source=self.source_relative
+        )
 
 
 class AlreadyLinked(AbstractBaseAction):
@@ -49,6 +112,7 @@ class AlreadyLinked(AbstractBaseAction):
     """
     Action to used to print an already linked message
     """
+
     def __init__(self, subcmd, source, dest):
         super().__init__()
         self.source = source
@@ -56,14 +120,13 @@ class AlreadyLinked(AbstractBaseAction):
         self.dest = dest
         self.subcmd = subcmd
 
-    def _logic(self):
+    def execute(self):
         pass
 
     def __repr__(self):
         return "dploy {subcmd}: already linked {dest} => {source}".format(
-            subcmd=self.subcmd,
-            source=self.source_relative,
-            dest=self.dest)
+            subcmd=self.subcmd, source=self.source_relative, dest=self.dest
+        )
 
 
 class AlreadyUnlinked(AbstractBaseAction):
@@ -71,6 +134,7 @@ class AlreadyUnlinked(AbstractBaseAction):
     """
     Action to used to print an already unlinked message
     """
+
     def __init__(self, subcmd, source, dest):
         super().__init__()
         self.source = source
@@ -78,14 +142,13 @@ class AlreadyUnlinked(AbstractBaseAction):
         self.dest = dest
         self.subcmd = subcmd
 
-    def _logic(self):
+    def execute(self):
         pass
 
     def __repr__(self):
         return "dploy {subcmd}: already unlinked {dest} => {source}".format(
-            subcmd=self.subcmd,
-            source=self.source_relative,
-            dest=self.dest)
+            subcmd=self.subcmd, source=self.source_relative, dest=self.dest
+        )
 
 
 class UnLink(AbstractBaseAction):
@@ -93,53 +156,60 @@ class UnLink(AbstractBaseAction):
     """
     Action to unlink a symbolic link
     """
+
     def __init__(self, subcmd, target):
         super().__init__()
         self.target = target
         self.subcmd = subcmd
 
-    def _logic(self):
+    def execute(self):
         if not self.target.is_symlink():
-            #pylint: disable=line-too-long
-            raise RuntimeError('dploy detected and aborted an attempt to unlink a non-symlink this is a bug and should be reported')
+            # pylint: disable=line-too-long
+            raise RuntimeError(
+                "dploy detected and aborted an attempt to unlink a non-symlink {target} this is a bug and should be reported".format(
+                    target=self.target
+                )
+            )
         self.target.unlink()
 
     def __repr__(self):
-        source_relative = utils.get_relative_path(self.target.resolve(), self.target.parent)
         return "dploy {subcmd}: unlink {target} => {source}".format(
-            subcmd=self.subcmd,
-            target=self.target,
-            source=source_relative)
+            subcmd=self.subcmd, target=self.target, source=utils.readlink(self.target)
+        )
+
 
 class MakeDirectory(AbstractBaseAction):
     # pylint: disable=too-few-public-methods
     """
     Action to create a directory
     """
+
     def __init__(self, subcmd, target):
         super().__init__()
         self.target = target
         self.subcmd = subcmd
 
-    def _logic(self):
+    def execute(self):
         self.target.mkdir()
 
     def __repr__(self):
         return "dploy {subcmd}: make directory {target}".format(
-            target=self.target,
-            subcmd=self.subcmd)
+            target=self.target, subcmd=self.subcmd
+        )
+
 
 class RemoveDirectory(AbstractBaseAction):
     # pylint: disable=too-few-public-methods
     """
     Action to remove a directory
     """
+
     def __init__(self, subcmd, target):
         super().__init__()
         self.target = target
         self.subcmd = subcmd
 
-    def _logic(self):
+    def execute(self):
         self.target.rmdir()
 
     def __repr__(self):

dploy-0.1.3/dploy/cli.py

@@ -0,0 +1,114 @@
+"""
+The command line interface
+"""
+
+import sys
+import argparse
+from dploy import linkcmd
+from dploy import stowcmd
+from dploy import version
+from dploy.error import DployError
+
+
+def add_ignore_argument(parser):
+    """
+    adds the ignore argument to a subcmd parser
+    """
+    parser.add_argument(
+        "--ignore",
+        dest="ignore_patterns",
+        action="append",
+        default=None,
+        help="glob pattern used to ignore directories",
+    )
+
+
+def create_parser():
+    """
+    create the CLI argument parser
+    """
+    parser = argparse.ArgumentParser(prog="dploy")
+
+    parser.add_argument(
+        "--version",
+        action="version",
+        version="%(prog)s {version}".format(version=version.__version__),
+    )
+    parser.add_argument(
+        "--silent", dest="is_silent", action="store_true", help="suppress all output"
+    )
+    parser.add_argument(
+        "--dry-run",
+        dest="is_dry_run",
+        action="store_true",
+        help="show what would be done without doing it",
+    )
+
+    sub_parsers = parser.add_subparsers(dest="subcmd")
+
+    stow_parser = sub_parsers.add_parser("stow")
+    stow_parser.add_argument("source", nargs="+", help="source directory to stow")
+    stow_parser.add_argument("dest", help="destination path to stow into")
+    add_ignore_argument(stow_parser)
+
+    unstow_parser = sub_parsers.add_parser("unstow")
+    unstow_parser.add_argument(
+        "source", nargs="+", help="source directory to unstow from"
+    )
+    unstow_parser.add_argument("dest", help="destination path to unstow")
+    add_ignore_argument(unstow_parser)
+
+    clean_parser = sub_parsers.add_parser("clean")
+    clean_parser.add_argument(
+        "source", nargs="+", help="source directory to clean from"
+    )
+    clean_parser.add_argument("dest", help="destination path to clean")
+    add_ignore_argument(clean_parser)
+
+    link_parser = sub_parsers.add_parser("link")
+    link_parser.add_argument("source", help="source file or directory to link")
+    link_parser.add_argument("dest", help="destination path to link")
+    add_ignore_argument(link_parser)
+    return parser
+
+
+def run(arguments=None):
+    """
+    interpret the parser arguments and execute the corresponding commands
+    """
+
+    subcmd_map = {
+        "stow": stowcmd.Stow,
+        "unstow": stowcmd.UnStow,
+        "clean": stowcmd.Clean,
+        "link": linkcmd.Link,
+    }
+
+    try:
+        parser = create_parser()
+
+        if arguments is None:
+            args = parser.parse_args()
+        else:
+            args = parser.parse_args(arguments)
+
+        if args.subcmd in subcmd_map:
+            subcmd = subcmd_map[args.subcmd]
+        else:
+            parser.print_help()
+            sys.exit(0)
+
+        try:
+            subcmd(
+                args.source,
+                args.dest,
+                is_silent=args.is_silent,
+                is_dry_run=args.is_dry_run,
+                ignore_patterns=args.ignore_patterns,
+            )
+        except DployError:
+            sys.exit(1)
+
+    except (KeyboardInterrupt) as error:
+        print(error, file=sys.stderr)
+        sys.exit(130)