Merge lp:~jml/pkgme/copyright into lp:pkgme

[Jonathan Lange]

Add ExplicitCopyright element for overriding default copyright.

As per https://bugs.launchpad.net/pkgme-devportal/+bug/1026121 we want to
be able to override the default copyright ('$year $maintainer') with custom
text from certain backends.

This branch enables that by adding an ExplicitCopyright info_element and using
that instead of $year $maintainer if it's set.

According to http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/#file-syntax
the copyright field must be formatted the same way as the description field
in the control file. Thus, I extracted the debian formatting bit from description,
re-targetted the description tests against that & re-used it for copyright.

[James Westby (james-w)]

review: Approve

=== modified file 'pkgme/info_elements.py'
--- pkgme/info_elements.py	2012-07-18 08:51:10 +0000
+++ pkgme/info_elements.py	2012-08-21 15:30:25 +0000
@@ -217,11 +217,58 @@
 
     Named after the Perl built-in that does the same thing.
     """
+    # XXX: This is unused in pkgme, can we delete it? -- jml
     if text and text[-1] == '\n':
         return text[:-1]
     return text
 
 
+
+def _format_lines(lines):
+    first_line, lines = lines[0], lines[1:]
+    yield first_line
+    for i, line in enumerate(lines):
+        is_blank = bool(not line.strip())
+        if is_blank:
+            yield ' .'
+        elif line[0] == ' ':
+            yield line
+        else:
+            yield ' ' + line
+
+
+def debian_formatted_text(user_text):
+    """Prepare ``user_text`` as Debian formatted text.
+
+    If ``user_text`` looks to already be formatted according to Debian policy,
+    then we pass it through.  If it does not, then we do our best to clean it
+    up.
+
+    We determine whether ``user_text`` is already Debian-formatted by checking
+    whether the second line is indented by a space. If so, then we assume it's
+    Debian-formatted.  If later lines break Debian formatting, then we raise a
+    ValueError.
+
+    This style of formatting is used for the Description field of the
+    ``debian/control`` file, and for various fields in the
+    ``debian/copyright`` file.
+
+    See also:
+    * http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/#file-syntax
+    * http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Description
+
+    :param user_text: A string to be formatted as text for Debian files.
+    :raise ValueError: When the string initially looks to be Debian-formatted
+        but actually is not.
+    :return: A correctly formatted version of that string.
+    """
+    if isinstance(user_text, unicode):
+        user_text = user_text.encode('utf-8')
+    if not user_text.strip():
+        return ''
+    return '\n'.join(_format_lines(user_text.strip().splitlines()))
+
+
 class Description(InfoElement):
 
     name = "description"
@@ -229,31 +276,9 @@
     default = "a package"
 
     @classmethod
-    def _format_lines(cls, lines):
-        first_line, lines = lines[0], lines[1:]
-        yield first_line
-        for i, line in enumerate(lines):
-            is_blank = bool(not line.strip())
-            if is_blank:
-                yield ' .'
-            elif line[0] == ' ':
-                yield line
-            else:
-                yield ' ' + line
-
-    @classmethod
     def clean(cls, value):
         """Prepare a string for the Description field in the control file.
 
-        If ``value`` looks to already be formatted according to Debian policy,
-        then we pass it through.  If it does not, then we do our best to clean
-        it up.
-
-        We determine whether ``value`` is already Debian-formatted by checking
-        whether the second line is indented by a space. If so, then we assume
-        it's Debian-formatted.  If later lines break Debian formatting, then
-        we raise a ValueError.
-
         See http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Description
         for the rules governing the Description field.
 
@@ -261,13 +286,9 @@
             file.
         :raise ValueError: When the string initially looks to be Debian-
             formatted but actually is not.
-        :return: A correctly-formatted version of that string.
+        :return: A correctly formatted version of that string.
         """
-        if isinstance(value, unicode):
-            value = value.encode('utf-8')
-        if not value.strip():
-            return ''
-        return '\n'.join(cls._format_lines(value.strip().splitlines()))
+        return debian_formatted_text(value)
 
 
 class Version(InfoElement):
@@ -328,6 +349,17 @@
     description = "The path to the executable for an application."
 
 
+class ExplicitCopyright(InfoElement):
+
+    name = 'explicit_copyright'
+    description = 'An explicit copyright statement to override the default.'
+
+    @classmethod
+    def clean(cls, value):
+        if value is not None:
+            return debian_formatted_text(value)
+
+
 class TagLine(InfoElement):
 
     name = 'tagline'

=== modified file 'pkgme/package_files.py'
--- pkgme/package_files.py	2012-07-20 19:24:04 +0000
+++ pkgme/package_files.py	2012-08-21 15:30:25 +0000
@@ -17,6 +17,7 @@
     Description,
     Distribution,
     Executable,
+    ExplicitCopyright,
     ExtraFiles,
     ExtraFilesFromPaths,
     ExtraTargets,
@@ -181,6 +182,7 @@
     # See http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
 
     elements = [
+        ExplicitCopyright,
         PackageName,
         License,
         Homepage,

=== modified file 'pkgme/templates/copyright'
--- pkgme/templates/copyright	2012-07-05 14:16:12 +0000
+++ pkgme/templates/copyright	2012-08-21 15:30:25 +0000
@@ -5,7 +5,11 @@
 Upstream-Contact: $maintainer
 
 Files: *
+#if $explicit_copyright
+Copyright: $explicit_copyright
+#else
 Copyright: $year $maintainer
+#end if
 License: $license
 #import os.path
 #set $path = os.path.join("/usr/share/common-licenses", $license)

=== modified file 'pkgme/tests/test_info_elements.py'
--- pkgme/tests/test_info_elements.py	2012-06-04 16:40:24 +0000
+++ pkgme/tests/test_info_elements.py	2012-08-21 15:30:25 +0000
@@ -5,6 +5,7 @@
 
 from pkgme.info_elements import (
     BuildDepends,
+    debian_formatted_text,
     Description,
     Distribution,
     ExtraFiles,
@@ -153,7 +154,7 @@
             Distribution.get_default(), release_keys['DISTRIB_CODENAME'])
 
 
-class DescriptionTestCase(TestCase):
+class DebianFormattedTextTests(TestCase):
 
     # http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Description
 
@@ -161,14 +162,14 @@
         # If the description is just a single line with no line breaks, then
         # that counts as the synopsis and no special formatting is needed.
         description = "single line description"
-        cleaned = Description.clean(description)
+        cleaned = debian_formatted_text(description)
         self.assertEqual(description, cleaned)
 
     def test_single_line_trailing_newline(self):
         # If the single line ends with a newline then we remove that newline,
         # as it's not needed for the Description in the template.
         description = "single line description\n"
-        cleaned = Description.clean(description)
+        cleaned = debian_formatted_text(description)
         self.assertEqual(description.rstrip(), cleaned)
 
     def test_indented_further_lines(self):
@@ -180,7 +181,7 @@
   more preformatted text
  more information
 """
-        cleaned = Description.clean(description)
+        cleaned = debian_formatted_text(description)
         self.assertEqual(description.rstrip(), cleaned)
 
     def test_non_indented_further_lines(self):
@@ -193,7 +194,7 @@
  follow-up line
 more information
 """
-        description = Description.clean(bad_description)
+        description = debian_formatted_text(bad_description)
         self.assertEqual("""\
 initial synopsis
  follow-up line
@@ -209,7 +210,7 @@
 
  more information
 """
-        description = Description.clean(bad_description)
+        description = debian_formatted_text(bad_description)
         self.assertEqual("""initial synopsis
  follow-up line
  .
@@ -223,7 +224,7 @@
 follow-up line
 more information
 """
-        cleaned = Description.clean(description)
+        cleaned = debian_formatted_text(description)
         self.assertEqual("""initial synopsis
  follow-up line
  more information""", cleaned)
@@ -239,7 +240,7 @@
 that previous line has spaces in it, but needs to be marked
 up as a blank line all the same
 """
-        cleaned = Description.clean(description)
+        cleaned = debian_formatted_text(description)
         self.assertEqual("""initial synopsis
  follow-up line
  .
@@ -250,9 +251,9 @@
 
     def test_empty_description(self):
         # If the description is empty, then we return an empty description.
-        self.assertEqual('', Description.clean(''))
-        self.assertEqual('', Description.clean('\n'))
-        self.assertEqual('', Description.clean('  '))
+        self.assertEqual('', debian_formatted_text(''))
+        self.assertEqual('', debian_formatted_text('\n'))
+        self.assertEqual('', debian_formatted_text('  '))
 
     def test_initial_blank_lines(self):
         description = """
@@ -261,7 +262,7 @@
 follow-up line
 more information
 """
-        cleaned = Description.clean(description)
+        cleaned = debian_formatted_text(description)
         self.assertEqual("""initial synopsis
  follow-up line
  more information""", cleaned)
@@ -272,10 +273,28 @@
         description = (
             u'\u201cPretty \u2018speech\u2019 marks\u201d\u202a \u2013'
             u'what fun!')
-        cleaned = Description.clean(description)
+        cleaned = debian_formatted_text(description)
         self.assertEqual(description.encode('utf-8'), cleaned)
 
 
+class DescriptionTestCase(TestCase):
+
+    # http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Description
+
+    def test_debian_formats_text(self):
+        # Description.clean returns the description as Debian-formatted text.
+        description = """initial synopsis
+follow-up line
+
+more information
+
+that previous line has spaces in it, but needs to be marked
+up as a blank line all the same
+"""
+        cleaned = Description.clean(description)
+        self.assertEqual(debian_formatted_text(description), cleaned)
+
+
 class TestMaintainer(TestCase):
 
     def test_unspecified(self):

=== modified file 'pkgme/tests/test_package_files.py'
--- pkgme/tests/test_package_files.py	2012-07-20 19:24:04 +0000
+++ pkgme/tests/test_package_files.py	2012-08-21 15:30:25 +0000
@@ -13,9 +13,11 @@
     Buildsystem,
     Categories,
     DebhelperAddons,
+    debian_formatted_text,
     Depends,
     Description,
     Executable,
+    ExplicitCopyright,
     ExtraFiles,
     ExtraFilesFromPaths,
     ExtraTargets,
@@ -260,8 +262,54 @@
 Files: debian/*
 Copyright: %(year)s The friendly pkgme.net robot
 License: public-domain
-""" % { 'year' : datetime.datetime.now().year, 
-      })
+""" % {'year' : datetime.datetime.now().year,})
+
+    def test_explicit_copyright(self):
+        package_file = self.get_object(
+            {ExplicitCopyright.name: "blah blah blah",
+             License.name: 'proprietary',
+            })
+        self.assertEqual(package_file.get_contents(),
+                         """\
+Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+Upstream-Name: somepackage
+Upstream-Contact: Random Guy <[e-mail]>
+
+Files: *
+Copyright: blah blah blah
+License: proprietary
+
+Files: debian/*
+Copyright: %(year)s The friendly pkgme.net robot
+License: public-domain
+""" % {'year' : datetime.datetime.now().year,})
+
+    def test_explicit_copyright_multiline(self):
+        copyright_msg = """\
+Please see the enclosed PDF file for the exact copyright holders or contact the submitter of the application '%(submitter)s'
+
+This file was automatically generated.
+""" % {'submitter': 'Arthur Dent <[e-mail]'}
+        package_file = self.get_object(
+            {ExplicitCopyright.name: copyright_msg,
+             License.name: 'proprietary',
+            })
+        self.assertEqual(package_file.get_contents(),
+                         """\
+Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+Upstream-Name: somepackage
+Upstream-Contact: Random Guy <[e-mail]>
+
+Files: *
+Copyright: %(clean_copyright)s
+License: proprietary
+
+Files: debian/*
+Copyright: %(year)s The friendly pkgme.net robot
+License: public-domain
+""" % {'year' : datetime.datetime.now().year,
+       'clean_copyright': debian_formatted_text(copyright_msg),
+       })
 
     def test_overwrite(self):
         package_file = self.get_object()