debian.copyright module

Utilities for parsing and creating machine-readable debian/copyright files.

The specification for the format (also known as DEP5) is available here: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/

Start from the Copyright docstring for usage information.

Copyright Classes

class debian.copyright.Copyright(sequence=None, encoding='utf-8', strict=True)

Bases: object

Represents a debian/copyright file.

A Copyright object contains a Header paragraph and a list of additional Files or License paragraphs. It provides methods to iterate over those paragraphs, in addition to adding new ones. It also provides a mechanism for finding the Files paragraph (if any) that matches a particular filename.

Typical usage:

with io.open('debian/copyright', 'rt', encoding='utf-8') as f:
    c = copyright.Copyright(f)

    header = c.header
    # Header exposes standard fields, e.g.
    print('Upstream name: ', header.upstream_name)
    lic = header.license
    if lic:
        print('Overall license: ', lic.synopsis)
    # You can also retrive and set custom fields.
    header['My-Special-Field'] = 'Very special'

    # Find the license for a given file.
    paragraph = c.find_files_paragraph('debian/rules')
    if paragraph:
        print('License for debian/rules: ', paragraph.license)

    # Dump the result, including changes, to another file.
    with io.open('debian/copyright.new', 'wt', encoding='utf-8') as f:
        c.dump(f=f)

It is possible to build up a Copyright from scratch, by modifying the header and using add_files_paragraph and add_license_paragraph. See the associated method docstrings.

add_files_paragraph(paragraph)

Adds a FilesParagraph to this object.

The paragraph is inserted directly after the last FilesParagraph (which might be before a standalone LicenseParagraph).

add_license_paragraph(paragraph)

Adds a LicenceParagraph to this object.

The paragraph is inserted after any other paragraphs.

all_files_paragraphs()

Returns an iterator over the contained FilesParagraph objects.

all_license_paragraphs()

Returns an iterator over standalone LicenseParagraph objects.

all_paragraphs()

Returns an iterator over all paragraphs (header, Files, License).

The header (returned first) will be returned as a Header object; file paragraphs as FilesParagraph objects; license paragraphs as LicenseParagraph objects.

dump(f=None)

Dumps the contents of the copyright file.

If f is None, returns a unicode object. Otherwise, writes the contents to f, which must be a file-like object that is opened in text mode (i.e. that accepts unicode objects directly). It is thus up to the caller to arrange for the file to do any appropriate encoding.

find_files_paragraph(filename)

Returns the FilesParagraph for the given filename.

In accordance with the spec, this method returns the last FilesParagraph that matches the filename. If no paragraphs matched, returns None.

header

The file header paragraph.

exception debian.copyright.Error

Bases: Exception

Base class for exceptions in this module.

class debian.copyright.FilesParagraph(data, _internal_validate=True, strict=True)

Bases: debian.deb822.RestrictedWrapper

Represents a Files paragraph of a debian/copyright file.

This kind of paragraph is used to specify the copyright and license for a particular set of files in the package.

_RestrictedWrapper__restricted_fields = frozenset({'comment', 'copyright', 'files', 'license'})

comment

Comment

copyright

Copyright

classmethod create(files, copyright, license)

Create a new FilesParagraph from its required parts.

Parameters:

• files – The list of file globs.
• copyright_info – The copyright for the files (free-form text).
• license_info – The Licence for the files.

files

Files

files_pattern()

Returns a regular expression equivalent to the Files globs.

Caches the result until files is set to a different value.

Raises ValueError if any of the globs are invalid.

license

License

matches(filename)

Returns True iff filename is matched by a glob in Files.

class debian.copyright.Header(data=None)

Bases: debian.deb822.RestrictedWrapper

Represents the header paragraph of a debian/copyright file.

Property values are all immutable, such that in order to modify them you must explicitly set them (rather than modifying a returned reference).

_RestrictedWrapper__restricted_fields = frozenset({'copyright', 'format', 'comment', 'source', 'upstream-name', 'disclaimer', 'upstream-contact', 'license'})

comment

Comment

copyright

Copyright

current_format()

Returns True iff the format is the current format.

disclaimer

Disclaimer

format

Format

known_format()

Returns True iff the format is known.

license

License

source

Source

upstream_contact

Upstream-Contact

upstream_name

Upstream-Name

class debian.copyright.License

Bases: debian.copyright.License

Represents the contents of a License field. Immutable.

classmethod from_str(s)

to_str()

class debian.copyright.LicenseParagraph(data, _internal_validate=True)

Bases: debian.deb822.RestrictedWrapper

Represents a standalone license paragraph of a debian/copyright file.

Minimally, this kind of paragraph requires a ‘License’ field and has no ‘Files’ field. It is used to give a short name to a license text, which can be referred to from the header or files paragraphs.

_LicenseParagraph__files

Files

_RestrictedWrapper__restricted_fields = frozenset({'comment', 'files', 'license'})

comment

Comment

classmethod create(license)

Returns a LicenseParagraph with the given license.

license

License

exception debian.copyright.MachineReadableFormatError

Bases: debian.copyright.Error, ValueError

Raised when the input is not valid.

This is both a copyright.Error and a ValueError to ease handling of errors coming from this module.

exception debian.copyright.NotMachineReadableError

Bases: debian.copyright.Error

Raised when the input is not a machine-readable debian/copyright file.

class debian.copyright._LineBased

Bases: object

Namespace for conversion methods for line-based lists as tuples.

static from_str(s)

Returns the lines in ‘s’, with whitespace stripped, as a tuple.

static to_str(seq)

Returns the sequence as a string with each element on its own line.

If ‘seq’ has one element, the result will be on a single line. Otherwise, the first line will be blank.

class debian.copyright._SpaceSeparated

Bases: object

Namespace for conversion methods for space-separated lists as tuples.

_has_space = re.compile('\\s')

static from_str(s)

Returns the values in s as a tuple (empty if only whitespace).

classmethod to_str(seq)

Returns the sequence as a space-separated string (None if empty).

debian.copyright._complain(msg, strict)

debian.copyright._single_line(s)

Returns s if it is a single line; otherwise raises MachineReadableFormatError.

debian.copyright.format_multiline(s)

Formats multiline text for insertion in a Deb822 field.

Each line except for the first one is prefixed with a single space. Lines that are blank or only whitespace are replaced with ‘ .’

debian.copyright.format_multiline_lines(lines)

Same as format_multline, but taking input pre-split into lines.

debian.copyright.globs_to_re(globs)

Returns an re object for the given globs.

Only * and ? wildcards are supported. Literal * and ? may be matched via * and ?, respectively. A literal backslash is matched \. Any other character after a backslash is forbidden.

Empty globs match nothing.

Raises MachineReadableFormatError if any of the globs is illegal.

debian.copyright.parse_multiline(s)

Inverse of format_multiline.

Technically it can’t be a perfect inverse, since format_multline must replace all-whitespace lines with ‘ .’. Specifically, this function:

• Does nothing to the first line
• Removes first character (which must be ‘ ‘) from each proceeding line.
• Replaces any line that is ‘.’ with an empty line.

debian.copyright.parse_multiline_as_lines(s)

Same as parse_multiline, but returns a list of lines.

(This is the inverse of format_multiline_lines.)