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.
"""
# Support for Python 2.7
from __future__ import absolute_import, division, print_function, unicode_literals
from builtins import *
[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)