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: List[str] | IO[str] | None = None, encoding: str = 'utf-8', strict: bool = 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 retrieve 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: FilesParagraph) → None¶

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: LicenseParagraph) → None¶

Adds a LicenceParagraph to this object.

The paragraph is inserted after any other paragraphs.

all_files_paragraphs() → Iterator[FilesParagraph]¶: Returns an iterator over the contained FilesParagraph objects.

all_license_paragraphs() → Iterator[LicenseParagraph]¶: Returns an iterator over standalone LicenseParagraph objects.

all_paragraphs() → Iterator[Header | FilesParagraph | LicenseParagraph]¶

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: IO[str] | None = None) → str | 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: str) → FilesParagraph | None¶

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.

property header: Header¶: The file header paragraph.

exception debian.copyright.Error¶

Bases: Exception

Base class for exceptions in this module.

class debian.copyright.FilesParagraph(data: Deb822ParagraphElement, _internal_validate: bool = True, strict: bool = True)¶

Bases: _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'})¶

_default_re = re.compile('')¶

property comment: Any¶: Comment

property copyright: Any¶: Copyright

classmethod create(files: List[str] | None, copyright: str | None, license: License | None) → FilesParagraph¶

Create a new FilesParagraph from its required parts.

Parameters:

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

property files: Any¶: Files

files_pattern() → Pattern[str] | None¶

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.

property license: Any¶: License

matches(filename: str) → bool¶: Returns True iff filename is matched by a glob in Files.

class debian.copyright.Header(data: Deb822ParagraphElement | None = None)¶

Bases: _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({'comment', 'copyright', 'disclaimer', 'files-excluded', 'files-included', 'format', 'license', 'source', 'upstream-contact', 'upstream-name'})¶

property comment: Any¶: Comment

property copyright: Any¶: Copyright

current_format() → bool¶: Returns True iff the format is the current format.

property disclaimer: Any¶: Disclaimer

property files_excluded: Any¶: Files-Excluded

property files_included: Any¶: Files-Included

property format: Any¶: Format

known_format() → bool¶: Returns True iff the format is known.

property license: Any¶: License

property source: Any¶: Source

property upstream_contact: Any¶: Upstream-Contact

property upstream_name: Any¶: Upstream-Name

class debian.copyright.License(synopsis: str, text: str | None = '')¶

Bases: License

Represents the contents of a License field. Immutable.

classmethod from_str(s: str | None) → License | None¶

to_str() → str¶

class debian.copyright.LicenseParagraph(data: Deb822ParagraphElement, _internal_validate: bool = True)¶

Bases: _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.

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

property __files: Any¶: Files

property comment: Any¶: Comment

classmethod create(license: License) → LicenseParagraph¶: Returns a LicenseParagraph with the given license.

property license: Any¶: License

exception debian.copyright.MachineReadableFormatError¶

Bases: 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: Error

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

class debian.copyright._ClassInitMeta(name, bases, attrs)¶

Bases: type

Metaclass for classes that can be initialized at creation time.

Implement the method:

@classmethod
def _class_init(cls, new_attrs):
    pass

on a class, and apply this metaclass to it. The _class_init method will be called right after the class is created. The ‘new_attrs’ param is a dict containing the attributes added in the definition of the class.

class debian.copyright._LineBased¶

Bases: object

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

static from_str(s: str | None) → Iterable[str]¶: Returns the lines in ‘s’, with whitespace stripped, as a tuple.

static to_str(seq: Iterable[str]) → str | None¶

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._RestrictedWrapper(data: Deb822ParagraphElement, _internal_validate: bool = True)¶

Bases: object

Base class to wrap a Deb822 object, restricting write access to some keys.

The underlying data is hidden internally. Subclasses may keep a reference to the data before giving it to this class’s constructor, if necessary, but RestrictedField should cover most use-cases. The dump method from Deb822 is directly proxied.

Typical usage:

class Foo:
    def __init__(self, ...):
        # ...

    @staticmethod
    def from_str(self, s):
        # Parse s...
        return Foo(...)

    def to_str(self):
        # Return in string format.
        return ...

class MyClass(deb822._RestrictedWrapper):
    def __init__(self):
        data = Deb822ParagraphElement.new_empty_paragraph()
        data['Bar'] = 'baz'
        super(MyClass, self).__init__(data)

    foo = deb822.RestrictedField(
            'Foo', from_str=Foo.from_str, to_str=Foo.to_str)

    bar = deb822.RestrictedField('Bar', allow_none=False)

d = MyClass()
d['Bar'] # returns 'baz'
d['Bar'] = 'quux' # raises RestrictedFieldError
d.bar = 'quux'
d.bar # returns 'quux'
d['Bar'] # returns 'quux'

d.foo = Foo(...)
d['Foo'] # returns string representation of foo

classmethod _RestrictedWrapper__init_restricted_field(attr_name, field)¶

_RestrictedWrapper__restricted_fields = frozenset({})¶

classmethod _class_init(new_attrs)¶

property _underlying_paragraph: Deb822ParagraphElement¶

dump(fd: IO[str] | IO[bytes] | None = None, encoding: str | None = None, text_mode: bool = False) → str | None¶

Calls dump() on the underlying data object.

See Deb822.dump for more information.

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: str | None) → Iterable[str]¶: Returns the values in s as a tuple (empty if only whitespace).

classmethod to_str(seq: Iterable[str]) → str | None¶: Returns the sequence as a space-separated string (None if empty).

debian.copyright._complain(msg: str, strict: bool) → None¶

debian.copyright._single_line(s: str) → str¶: Returns s if it is a single line; otherwise raises MachineReadableFormatError.

debian.copyright.format_multiline(s: str | None) → str | None¶

Formats multiline text for insertion in a Deb822ParagraphElement 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: List[str]) → str¶: Same as format_multline, but taking input pre-split into lines.

debian.copyright.globs_to_re(globs: Iterable[str]) → Pattern[str]¶

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: str | None) → str | None¶

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: str) → List[str]¶

Same as parse_multiline, but returns a list of lines.

(This is the inverse of format_multiline_lines.)

debian.copyright module¶

Copyright Classes¶

Table of Contents

Previous topic

Next topic

This Page