Coverage for .tox/coverage/lib/python3.11/site-packages/wuttamess/sync.py: 100%

1# -*- coding: utf-8; -*- 

2################################################################################ 

3# 

4# WuttaMess -- Fabric Automation Helpers 

5# Copyright © 2024 Lance Edgar 

6# 

7# This file is part of Wutta Framework. 

8# 

9# Wutta Framework is free software: you can redistribute it and/or modify it 

10# under the terms of the GNU General Public License as published by the Free 

11# Software Foundation, either version 3 of the License, or (at your option) any 

12# later version. 

13# 

14# Wutta Framework is distributed in the hope that it will be useful, but 

15# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 

16# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for 

17# more details. 

18# 

19# You should have received a copy of the GNU General Public License along with 

20# Wutta Framework. If not, see <http://www.gnu.org/licenses/>. 

21# 

22################################################################################ 

23""" 

24Synchronize Files 

25 

26See :doc:`/narr/usage` for a basic example. 

27""" 

28 

29import fabsync 

30 

31 

32def make_root(path, dest='/'): 

33 """ 

34 Make and return a "root" object for use with future sync calls. 

35 

36 This is a convenience wrapper around 

37 :func:`fabsync:fabsync.load()`. 

38 

39 :param path: Path to local file tree. Usually this is relative to 

40 the ``fabfile.py`` location, otherwise should be absolute. 

41 

42 :param dest: Path for target file tree. 

43 """ 

44 return fabsync.load(path, dest) 

45 

46 

47def make_selector(subpath=None, **kwargs): 

48 """ 

49 Make and return an "item selector" for use with a sync call. 

50 

51 This is a convenience wrapper around 

52 :meth:`fabsync:fabsync.ItemSelector.new()`. 

53 

54 :param subpath: (Optional) Relative subpath of the file tree to 

55 sync, e.g. ``'etc/postfix'``. 

56 

57 :param tags: Optional iterable of tags to include; excluding any 

58 files which are not so tagged. E.g. ``{'foo'}`` 

59 """ 

60 return fabsync.ItemSelector.new(subpath, **kwargs) 

61 

62 

63def isync(c, root, selector=None, tags=None, echo=True, **kwargs): 

64 """ 

65 Sync files, yielding the result for each as it goes. 

66 

67 This is a convenience wrapper around 

68 :func:`fabsync:fabsync.isync()`. 

69 

70 :param c: Fabric connection. 

71 

72 :param root: File tree "root" object as obtained from 

73 :func:`make_root()`. 

74 

75 :param selector: This can be a simple "subpath" string, indicating 

76 a section of the file tree (e.g. ``'etc/postfix'``). Or can be 

77 a :class:`fabsync.ItemSelector` instance. 

78 

79 :param tags: Optional iterable of tags to select. If ``selector`` 

80 is a subpath string, and you specify ``tags`` then they will be 

81 included when creating the actual selector. 

82 

83 :param echo: Flag indicating whether the path for each file synced 

84 should be echoed to stdout. Generally thought to be useful but 

85 may be disabled. 

86 

87 :param \**kwargs: Any remaining kwargs are passed as-is to 

88 :func:`fabsync:fabsync.isync()`. 

89 """ 

90 if selector: 

91 if not isinstance(selector, fabsync.ItemSelector): 

92 kw = {} 

93 if tags: 

94 kw['tags'] = tags 

95 selector = make_selector(selector, **kw) 

96 kwargs['selector'] = selector 

97 

98 for result in fabsync.isync(c, root, **kwargs): 

99 if echo: 

100 print(f"{result.path}{' [modified]' if result.modified else ''}") 

101 yield result 

102 

103 

104def check_isync(c, root, selector=None, **kwargs): 

105 """ 

106 Sync all files and return boolean indicating whether any actual 

107 modifications were made. 

108 

109 Arguments are the same as for :func:`isync()`, which this calls. 

110 

111 :returns: ``True`` if any sync result indicates a file was 

112 modified; otherwise ``False``. 

113 """ 

114 return any([result.modified 

115 for result in isync(c, root, selector, **kwargs)])