Source code for podgen.person

# -*- coding: utf-8 -*-
"""
    podgen.person
    ~~~~~~~~~~~~~

    This file contains the Person class, which is used to represent a person or
    an entity.

    :copyright: 2016, Thorben Dahl <thorben@sjostrom.no>
    :license: FreeBSD and LGPL, see license.* for more details.
"""
[docs]class Person(object): """Data-oriented class representing a single person or entity. A Person can represent both real persons and less personal entities like organizations. Example:: >>> p.authors = [Person("Example Radio", "mail@example.org")] .. note:: At any time, one of name or email must be present. Both cannot be None or empty at the same time. .. warning:: **Any names and email addresses** you put into a Person object will eventually be included and **published** together with the feed. If you want to keep a name or email address private, then you must make sure it isn't used in a Person object (or to be precise: that the Person object with the name or email address isn't used in any Podcast or Episode.) Example of use:: >>> from podgen import Person >>> Person("John Doe") Person(name=John Doe, email=None) >>> Person(email="johndoe@example.org") Person(name=None, email=johndoe@example.org) >>> Person() ValueError: You must provide either a name or an email address. """ def __init__(self, name=None, email=None): """Create new person with a name, email or both. You don't need to provide both a name and an email, but you must provide one of them. :param name: This person's name. :type name: str or None :param email: This person's email address. The address it made public when the feed is published, so be careful about adding a personal email address here. The spambots are always on lookout! :type email: str or None """ if not self._is_valid(name, email): raise ValueError("You must provide either a name or an email " "address.") self.__name = name self.__email = email def _is_valid(self, name, email): """Check whether one of name and email are usable.""" return name or email @property def name(self): """This person's name. :type: :obj:`str` """ return self.__name @name.setter def name(self, new_name): if not self._is_valid(new_name, self.email): raise ValueError("The name or email must be present at any time, " "cannot set name to \"%s\" as long as email is " "\"%s\"" % (new_name, self.email)) self.__name = new_name @property def email(self): """This person's public email address. :type: :obj:`str` """ return self.__email @email.setter def email(self, new_email): if not self._is_valid(self.name, new_email): raise ValueError("The name or email must be present at any time, " "cannot set email to \"%s\" as long as name is " "\"%s\"" % (new_email, self.name)) self.__email = new_email def __str__(self): if self.email is None: return self.name elif self.name is None: return self.email else: return "%s (%s)" % (self.email, self.name) def __repr__(self): return "Person(name=%s, email=%s)" % (self.name, self.email)