← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/add.py

  • Committer: John Arbash Meinel
  • Date: 2007-04-09 21:06:31 UTC
  • mto: This revision was merged to the branch mainline in revision 2566.
  • Revision ID: john@arbash-meinel.com-20070409210631-llhncalt7gct9wms
Clean up add.py documentation.
Add doc strings for undocumented functions.
Move documentation to the right location for 'smart_add_tree'
Fix rst documentation (the lines need to be indented for each parameter)

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/add.py
14
14
# along with this program; if not, write to the Free Software
15
15
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
16
16
 
 
17
"""Helper functions for adding files to working trees."""
 
18
 
17
19
import errno
18
20
import os
19
21
from os.path import dirname
29
31
 
30
32
 
31
33
def glob_expand_for_win32(file_list):
 
34
    """Replacement for glob expansion by the shell.
 
35
 
 
36
    Win32's cmd.exe does not do glob expansion (eg ``*.py``), so we do our own
 
37
    here.
 
38
 
 
39
    :param file_list: A list of filenames which may include shell globs.
 
40
    :return: An expanded list of filenames.
 
41
    """
32
42
    if not file_list:
33
43
        return
34
44
    import glob
35
45
    expanded_file_list = []
36
46
    for possible_glob in file_list:
37
47
        glob_files = glob.glob(possible_glob)
38
 
       
 
48
 
39
49
        if glob_files == []:
40
50
            # special case to let the normal code path handle
41
51
            # files that do not exists
59
69
    """A class which defines what action to take when adding a file."""
60
70
 
61
71
    def __init__(self, to_file=None, should_print=None):
 
72
        """Initialize an action which prints added files to an output stream.
 
73
 
 
74
        :param to_file: The stream to write into. This is expected to take
 
75
            Unicode paths. If not supplied, it will default to ``sys.stdout``.
 
76
        :param should_print: If False, printing will be supressed.
 
77
        """
62
78
        self._to_file = to_file
63
79
        if to_file is None:
64
80
            self._to_file = sys.stdout
169
185
 
170
186
 
171
187
def smart_add_tree(tree, file_list, recurse=True, action=None, save=True):
 
188
    """Add files to version, optionally recursing into directories.
 
189
 
 
190
    This is designed more towards DWIM for humans than API simplicity.
 
191
    For the specific behaviour see the help for cmd_add().
 
192
 
 
193
    This calls reporter with each (path, kind, file_id) of added files.
 
194
 
 
195
    Returns the number of files added.
 
196
 
 
197
    :param save: Save the inventory after completing the adds. If False this
 
198
        provides dry-run functionality by doing the add and not saving the
 
199
        inventory.  Note that the modified inventory is left in place, allowing
 
200
        further dry-run tasks to take place. To restore the original inventory
 
201
        call tree.read_working_inventory().
 
202
    """
172
203
    tree.lock_tree_write()
173
204
    try:
174
205
        return _smart_add_tree(tree=tree, file_list=file_list, recurse=recurse,
176
207
    finally:
177
208
        tree.unlock()
178
209
 
 
210
 
179
211
def _smart_add_tree(tree, file_list, recurse=True, action=None, save=True):
180
 
    """Add files to version, optionally recursing into directories.
181
 
 
182
 
    This is designed more towards DWIM for humans than API simplicity.
183
 
    For the specific behaviour see the help for cmd_add().
184
 
 
185
 
    This calls reporter with each (path, kind, file_id) of added files.
186
 
 
187
 
    Returns the number of files added.
188
 
    
189
 
    :param save: Save the inventory after completing the adds. If False this
190
 
    provides dry-run functionality by doing the add and not saving the
191
 
    inventory.  Note that the modified inventory is left in place, allowing 
192
 
    further dry-run tasks to take place. To restore the original inventory
193
 
    call tree.read_working_inventory().
 
212
    """Helper for smart_add_tree.
 
213
 
 
214
    The tree should be locked before entering this function. See smart_add_tree
 
215
    for parameter definitions.
194
216
    """
195
217
    assert isinstance(recurse, bool)
196
218
    if action is None:
347
369
 
348
370
    :param inv: Inventory which will receive the new entry.
349
371
    :param parent_ie: Parent inventory entry if known, or None.  If
350
 
    None, the parent is looked up by name and used if present, otherwise
351
 
    it is recursively added.
 
372
        None, the parent is looked up by name and used if present, otherwise it
 
373
        is recursively added.
352
374
    :param kind: Kind of new entry (file, directory, etc)
353
375
    :param action: callback(inv, parent_ie, path, kind); return ignored.
354
 
    :returns: A list of paths which have been added.
 
376
    :return: A list of paths which have been added.
355
377
    """
356
378
    # Nothing to do if path is already versioned.
357
379
    # This is safe from infinite recursion because the tree root is