Previously, a small number of functions, methods and classes were
documented using comments. This patch improves consistency by converting
these into docstrings similar to those that already exist in the script.
Signed-off-by: Joel Holdsworth <jholdsworth@xxxxxxxxxx>
---
git-p4.py | 162 +++++++++++++++++++++++++++++++-----------------------
1 file changed, 92 insertions(+), 70 deletions(-)
diff --git a/git-p4.py b/git-p4.py
index 93f4ec843f..0bd1ba00ba 100755
--- a/git-p4.py
+++ b/git-p4.py
@@ -522,7 +522,7 @@ def p4_sync(f, *options):
def p4_add(f):
- # forcibly add file names with wildcards
+ """Forcibly add file names with wildcards."""
if wildcard_present(f):
p4_system(["add", "-f", f])
else:
@@ -590,12 +590,10 @@ def p4_describe(change, shelved=False):
return d
-#
-# Canonicalize the p4 type and return a tuple of the
-# base type, plus any modifiers. See "p4 help filetypes"
-# for a list and explanation.
-#
def split_p4_type(p4type):
+ """Canonicalize the p4 type and return a tuple of the base type, plus any
+ modifiers. See "p4 help filetypes" for a list and explanation.
+ """
p4_filetypes_historical = {
"ctempobj": "binary+Sw",
@@ -626,19 +624,18 @@ def split_p4_type(p4type):
return (base, mods)
-#
-# return the raw p4 type of a file (text, text+ko, etc)
-#
def p4_type(f):
+ """Return the raw p4 type of a file (text, text+ko, etc)."""
+
results = p4CmdList(["fstat", "-T", "headType", wildcard_encode(f)])
return results[0]['headType']
-#
-# Given a type base and modifier, return a regexp matching
-# the keywords that can be expanded in the file
-#
def p4_keywords_regexp_for_type(base, type_mods):
+ """Given a type base and modifier, return a regexp matching the keywords
+ that can be expanded in the file.
+ """
+
if base in ("text", "unicode", "binary"):
if "ko" in type_mods:
return re_ko_keywords
@@ -650,12 +647,11 @@ def p4_keywords_regexp_for_type(base, type_mods):
return None
-#
-# Given a file, return a regexp matching the possible
-# RCS keywords that will be expanded, or None for files
-# with kw expansion turned off.
-#
def p4_keywords_regexp_for_file(file):
+ """Given a file, return a regexp matching the possible RCS keywords that
+ will be expanded, or None for files with kw expansion turned off.
+ """
+
if not os.path.exists(file):
return None
else:
@@ -664,8 +660,9 @@ def p4_keywords_regexp_for_file(file):
def setP4ExecBit(file, mode):
- # Reopens an already open file and changes the execute bit to match
- # the execute bit setting in the passed in mode.
+ """Reopens an already open file and changes the execute bit to match the
+ execute bit setting in the passed in mode.
+ """
p4Type = "+x"
@@ -680,7 +677,7 @@ def setP4ExecBit(file, mode):
def getP4OpenedType(file):
- # Returns the perforce file type for the given file.
+ """Returns the perforce file type for the given file."""
result = p4_read_pipe(["opened", wildcard_encode(file)])
match = re.match(".*\((.+)\)( \*exclusive\*)?\r?$", result)
@@ -690,8 +687,9 @@ def getP4OpenedType(file):
die("Could not determine file type for %s (result: '%s')" % (file, result))
-# Return the set of all p4 labels
def getP4Labels(depotPaths):
+ """Return the set of all p4 labels."""
+
labels = set()
if not isinstance(depotPaths, list):
depotPaths = [depotPaths]
@@ -703,8 +701,9 @@ def getP4Labels(depotPaths):
return labels
-# Return the set of all git tags
def getGitTags():
+ """Return the set of all git tags."""
+
gitTags = set()
for line in read_pipe_lines(["git", "tag"]):
tag = line.strip()
@@ -755,8 +754,9 @@ def parseDiffTreeEntry(entry):
def isModeExec(mode):
- # Returns True if the given git mode represents an executable file,
- # otherwise False.
+ """Returns True if the given git mode represents an executable file,
+ otherwise False.
+ """
return mode[-3:] == "755"
@@ -1274,13 +1274,14 @@ def p4ChangesForPaths(depotPaths, changeRange, requestedBlockSize):
def p4PathStartsWith(path, prefix):
- # This method tries to remedy a potential mixed-case issue:
- #
- # If UserA adds //depot/DirA/file1
- # and UserB adds //depot/dira/file2
- #
- # we may or may not have a problem. If you have core.ignorecase=true,
- # we treat DirA and dira as the same directory
+ """This method tries to remedy a potential mixed-case issue:
+
+ If UserA adds //depot/DirA/file1
+ and UserB adds //depot/dira/file2
+
+ we may or may not have a problem. If you have core.ignorecase=true,
+ we treat DirA and dira as the same directory.
+ """
if gitConfigBool("core.ignorecase"):
return path.lower().startswith(prefix.lower())
return path.startswith(prefix)
@@ -1332,13 +1333,15 @@ def getClientRoot():
return entry["Root"]
-#
-# P4 wildcards are not allowed in filenames. P4 complains
-# if you simply add them, but you can force it with "-f", in
-# which case it translates them into %xx encoding internally.
-#
def wildcard_decode(path):
- # Search for and fix just these four characters. Do % last so
+ """Decode P4 wildcards into %xx encoding
+
+ P4 wildcards are not allowed in filenames. P4 complains if you simply
+ add them, but you can force it with "-f", in which case it translates
+ them into %xx encoding internally.
+ """
+
+ # Search for and fix just these four characters. Do % last so
# that fixing it does not inadvertently create new %-escapes.
# Cannot have * in a filename in windows; untested as to
# what p4 would do in such a case.
@@ -1351,6 +1354,8 @@ def wildcard_decode(path):
def wildcard_encode(path):
+ """Encode %xx coded wildcards into P4 coding."""
+
# do % first to avoid double-encoding the %s introduced here
path = path.replace("%", "%25") \
.replace("*", "%2A") \
@@ -1597,7 +1602,7 @@ def p4UserId(self):
die("Could not find your p4 user id")
def p4UserIsMe(self, p4User):
- # return True if the given p4 user is actually me
+ """Return True if the given p4 user is actually me."""
me = self.p4UserId()
if not p4User or p4User != me:
return False
@@ -1800,7 +1805,9 @@ def prepareLogMessage(self, template, message, jobs):
return result
def patchRCSKeywords(self, file, regexp):
- # Attempt to zap the RCS keywords in a p4 controlled file matching the given regex
+ """Attempt to zap the RCS keywords in a p4 controlled file matching the
+ given regex.
+ """
(handle, outFileName) = tempfile.mkstemp(dir='.')
try:
with os.fdopen(handle, "wb") as outFile, open(file, "rb") as inFile:
@@ -1818,7 +1825,9 @@ def patchRCSKeywords(self, file, regexp):
print("Patched up RCS keywords in %s" % file)
def p4UserForCommit(self,id):
- # Return the tuple (perforce user,git email) for a given git commit id
+ """Return the tuple (perforce user,git email) for a given git commit
+ id.
+ """
self.getUserMapFromPerforceServer()
gitEmail = read_pipe(["git", "log", "--max-count=1",
"--format=%ae", id])
@@ -1829,7 +1838,7 @@ def p4UserForCommit(self,id):
return (self.emails[gitEmail],gitEmail)
def checkValidP4Users(self,commits):
- # check if any git authors cannot be mapped to p4 users
+ """Check if any git authors cannot be mapped to p4 users."""
for id in commits:
(user,email) = self.p4UserForCommit(id)
if not user:
@@ -1840,10 +1849,12 @@ def checkValidP4Users(self,commits):
die("Error: %s\nSet git-p4.allowMissingP4Users to true to allow this." % msg)
def lastP4Changelist(self):
- # Get back the last changelist number submitted in this client spec. This
- # then gets used to patch up the username in the change. If the same
- # client spec is being used by multiple processes then this might go
- # wrong.
+ """Get back the last changelist number submitted in this client spec.
+
+ This then gets used to patch up the username in the change. If the
+ same client spec is being used by multiple processes then this might
+ go wrong.
+ """
results = p4CmdList("client -o") # find the current client
client = None
for r in results:
@@ -1859,7 +1870,7 @@ def lastP4Changelist(self):
die("Could not get changelist number for last submit - cannot patch up user details")
def modifyChangelistUser(self, changelist, newUser):
- # fixup the user field of a changelist after it has been submitted.
+ """Fixup the user field of a changelist after it has been submitted."""
changes = p4CmdList("change -o %s" % changelist)
if len(changes) != 1:
die("Bad output from p4 change modifying %s to user %s" %
@@ -1882,8 +1893,9 @@ def modifyChangelistUser(self, changelist, newUser):
die("Could not modify user field of changelist %s to %s" % (changelist, newUser))
def canChangeChangelists(self):
- # check to see if we have p4 admin or super-user permissions, either of
- # which are required to modify changelists.
+ """Check to see if we have p4 admin or super-user permissions, either
+ of which are required to modify changelists.
+ """
results = p4CmdList(["protects", self.depotPath])
for r in results:
if 'perm' in r:
@@ -2334,9 +2346,11 @@ def applyCommit(self, id):
os.remove(fileName)
return submitted
- # Export git tags as p4 labels. Create a p4 label and then tag
- # with that.
def exportGitTags(self, gitTags):
+ """Export git tags as p4 labels. Create a p4 label and then tag with
+ that.
+ """
+
validLabelRegexp = gitConfig("git-p4.labelExportRegexp")
if len(validLabelRegexp) == 0:
validLabelRegexp = defaultLabelRegexp
@@ -2859,8 +2873,8 @@ def __init__(self):
self.tz = "%+03d%02d" % (- time.timezone / 3600, ((- time.timezone % 3600) / 60))
self.labels = {}
- # Force a checkpoint in fast-import and wait for it to finish
def checkpoint(self):
+ """Force a checkpoint in fast-import and wait for it to finish."""
self.gitStream.write("checkpoint\n\n")
self.gitStream.write("progress checkpoint\n\n")
self.gitStream.flush()
@@ -3006,9 +3020,9 @@ def encodeWithUTF8(self, path):
print('Path with non-ASCII characters detected. Used %s to encode: %s ' % (encoding, path))
return path
- # output one file from the P4 stream
- # - helper for streamP4Files
def streamOneP4File(self, file, contents):
+ """Output one file from the P4 stream - helper for streamP4Files."""
+
file_path = file['depotFile']
relPath = self.stripRepoPath(decode_path(file_path), self.branchPrefixes)
@@ -3100,8 +3114,8 @@ def streamOneP4Deletion(self, file):
if self.largeFileSystem and self.largeFileSystem.isLargeFile(relPath):
self.largeFileSystem.removeLargeFile(relPath)
- # handle another chunk of streaming data
def streamP4FilesCb(self, marshalled):
+ """Handle another chunk of streaming data."""
# catch p4 errors and complain
err = None
@@ -3165,8 +3179,9 @@ def streamP4FilesCb(self, marshalled):
self.stream_have_file_info = True
- # Stream directly from "p4 files" into "git fast-import"
def streamP4Files(self, files):
+ """Stream directly from "p4 files" into "git fast-import."""
+
filesForCommit = []
filesToRead = []
filesToDelete = []
@@ -3270,15 +3285,18 @@ def hasBranchPrefix(self, path):
return hasPrefix
def findShadowedFiles(self, files, change):
- # Perforce allows you commit files and directories with the same name,
- # so you could have files //depot/foo and //depot/foo/bar both checked
- # in. A p4 sync of a repository in this state fails. Deleting one of
- # the files recovers the repository.
- #
- # Git will not allow the broken state to exist and only the most recent
- # of the conflicting names is left in the repository. When one of the
- # conflicting files is deleted we need to re-add the other one to make
- # sure the git repository recovers in the same way as perforce.
+ """Perforce allows you commit files and directories with the same name,
+ so you could have files //depot/foo and //depot/foo/bar both checked
+ in. A p4 sync of a repository in this state fails. Deleting one of
+ the files recovers the repository.
+
+ Git will not allow the broken state to exist and only the most
+ recent of the conflicting names is left in the repository. When one
+ of the conflicting files is deleted we need to re-add the other one
+ to make sure the git repository recovers in the same way as
+ perforce.
+ """
+
deleted = [f for f in files if f['action'] in self.delete_actions]
to_check = set()
for f in deleted:
@@ -3395,8 +3413,11 @@ def commit(self, details, files, branch, parent = "", allow_empty=False):
print("Tag %s does not match with change %s: file count is different."
% (labelDetails["label"], change))
- # Build a dictionary of changelists and labels, for "detect-labels" option.
def getLabels(self):
+ """Build a dictionary of changelists and labels, for "detect-labels"
+ option.
+ """
+
self.labels = {}
l = p4CmdList(["labels"] + ["%s..." % p for p in self.depotPaths])
@@ -3422,11 +3443,12 @@ def getLabels(self):
if self.verbose:
print("Label changes: %s" % self.labels.keys())
- # Import p4 labels as git tags. A direct mapping does not
- # exist, so assume that if all the files are at the same revision
- # then we can use that, or it's something more complicated we should
- # just ignore.
def importP4Labels(self, stream, p4Labels):
+ """Import p4 labels as git tags. A direct mapping does not exist, so
+ assume that if all the files are at the same revision then we can
+ use that, or it's something more complicated we should just ignore.
+ """
+
if verbose:
print("import p4 labels: " + ' '.join(p4Labels))
--
2.34.1
