Entities

Provide a way of representing the entities of a rule system.

class openfisca_core.entities.CoreEntity(*_CoreEntity__args, **_CoreEntity__kwargs)

Base class to build entities from.

Parameters:

• *__args – Any arguments.

• **__kwargs – Any keyword arguments.

Examples

>>> from openfisca_core import entities
>>> from openfisca_core.entities import types as t

>>> class Entity(entities.CoreEntity):
...     def __init__(self, key):
...         self.key = t.EntityKey(key)

>>> Entity("individual")
Entity(individual)

static check_role_validity(role)

Check if role is an instance of Role.

Parameters:

role (object) – Any object.

Raises:

ValueError – When role is not a Role.

Return type:

None

Examples

>>> from openfisca_core import entities

>>> role = entities.Role({"key": "key"}, object())
>>> entities.check_role_validity(role)

>>> entities.check_role_validity("hey!")
Traceback (most recent call last):
ValueError: hey! is not a valid role

check_variable_defined_for_entity(variable_name)

Check if variable_name is defined for self.

Parameters:

variable_name (NewType(VariableName, str)) – The Variable to be found.

Raises:

ValueError – When the Variable exists but is defined for another Entity.

Return type:

None

Examples

>>> from openfisca_core import (
...     entities,
...     periods,
...     taxbenefitsystems,
...     variables,
... )

>>> this = entities.SingleEntity("this", "", "", "")
>>> that = entities.SingleEntity("that", "", "", "")
>>> tax_benefit_system = taxbenefitsystems.TaxBenefitSystem([that])
>>> this.set_tax_benefit_system(tax_benefit_system)

>>> this.check_variable_defined_for_entity("tax")
Traceback (most recent call last):
VariableNotFoundError: You tried to calculate or to set a value...

>>> class tax(variables.Variable):
...     definition_period = periods.WEEK
...     value_type = int
...     entity = that

>>> this._tax_benefit_system.add_variable(tax)
<openfisca_core.entities._core_entity.tax object at ...>

>>> this.check_variable_defined_for_entity("tax")
Traceback (most recent call last):
ValueError: You tried to compute the variable 'tax' for the enti...

>>> tax.entity = this

>>> this._tax_benefit_system.update_variable(tax)
<openfisca_core.entities._core_entity.tax object at ...>

>>> this.check_variable_defined_for_entity("tax")

doc: str

A full description.

get_variable(variable_name, check_existence=False)

Get variable_name from variables.

Parameters:

• variable_name (NewType(VariableName, str)) – The Variable to be found.

• check_existence (bool) – Was the Variable found?

Returns:

• Variable – When the Variable exists.

• None – When the Variable doesn’t exist.

Raises:

• ValueError – When the _tax_benefit_system is not set yet.

• ValueError – When check_existence is True and the Variable doesn’t exist.

Return type:

Variable | None

Examples

>>> from openfisca_core import (
...     entities,
...     periods,
...     taxbenefitsystems,
...     variables,
... )

>>> this = entities.SingleEntity("this", "", "", "")
>>> that = entities.SingleEntity("that", "", "", "")

>>> this.get_variable("tax")
Traceback (most recent call last):
ValueError: You must set 'tax_benefit_system' before calling thi...

>>> tax_benefit_system = taxbenefitsystems.TaxBenefitSystem([this])
>>> this.set_tax_benefit_system(tax_benefit_system)

>>> this.get_variable("tax")

>>> this.get_variable("tax", check_existence=True)
Traceback (most recent call last):
VariableNotFoundError: You tried to calculate or to set a value...

>>> class tax(variables.Variable):
...     definition_period = periods.MONTH
...     value_type = float
...     entity = that

>>> this._tax_benefit_system.add_variable(tax)
<openfisca_core.entities._core_entity.tax object at ...>

>>> this.get_variable("tax")
<openfisca_core.entities._core_entity.tax object at ...>

is_person: ClassVar[bool]

Whether the CoreEntity is a person or not.

key: NewType(EntityKey, str)

A key to identify the CoreEntity.

label: str

A summary description.

plural: NewType(EntityPlural, str)

The key pluralised.

set_tax_benefit_system(tax_benefit_system)

A CoreEntity belongs to a TaxBenefitSystem.

Return type:

None

class openfisca_core.entities.Entity(key, plural, label, doc)

An entity (e.g. a person, a household) on which calculations can be run.

Parameters:

• key (str) – A key to identify the Entity.

• plural (str) – The key pluralised.

• label (str) – A summary description.

• doc (str) – A full description.

Examples

>>> from openfisca_core import entities

>>> entity = entities.SingleEntity(
...     "individual",
...     "individuals",
...     "An individual",
...     "\t\t\tThe minimal legal entity on which a rule might be a...",
... )

>>> repr(entities.SingleEntity)
"<class 'openfisca_core.entities.entity.Entity'>"

>>> repr(entity)
'Entity(individual)'

>>> str(entity)
'Entity(individual)'

static check_role_validity(role)

Check if role is an instance of Role.

Parameters:

role (object) – Any object.

Raises:

ValueError – When role is not a Role.

Return type:

None

Examples

>>> from openfisca_core import entities

>>> role = entities.Role({"key": "key"}, object())
>>> entities.check_role_validity(role)

>>> entities.check_role_validity("hey!")
Traceback (most recent call last):
ValueError: hey! is not a valid role

check_variable_defined_for_entity(variable_name)

Check if variable_name is defined for self.

Parameters:

variable_name (NewType(VariableName, str)) – The Variable to be found.

Raises:

ValueError – When the Variable exists but is defined for another Entity.

Return type:

None

Examples

>>> from openfisca_core import (
...     entities,
...     periods,
...     taxbenefitsystems,
...     variables,
... )

>>> this = entities.SingleEntity("this", "", "", "")
>>> that = entities.SingleEntity("that", "", "", "")
>>> tax_benefit_system = taxbenefitsystems.TaxBenefitSystem([that])
>>> this.set_tax_benefit_system(tax_benefit_system)

>>> this.check_variable_defined_for_entity("tax")
Traceback (most recent call last):
VariableNotFoundError: You tried to calculate or to set a value...

>>> class tax(variables.Variable):
...     definition_period = periods.WEEK
...     value_type = int
...     entity = that

>>> this._tax_benefit_system.add_variable(tax)
<openfisca_core.entities._core_entity.tax object at ...>

>>> this.check_variable_defined_for_entity("tax")
Traceback (most recent call last):
ValueError: You tried to compute the variable 'tax' for the enti...

>>> tax.entity = this

>>> this._tax_benefit_system.update_variable(tax)
<openfisca_core.entities._core_entity.tax object at ...>

>>> this.check_variable_defined_for_entity("tax")

doc: str

A full description.

get_variable(variable_name, check_existence=False)

Get variable_name from variables.

Parameters:

• variable_name (NewType(VariableName, str)) – The Variable to be found.

• check_existence (bool) – Was the Variable found?

Returns:

• Variable – When the Variable exists.

• None – When the Variable doesn’t exist.

Raises:

• ValueError – When the _tax_benefit_system is not set yet.

• ValueError – When check_existence is True and the Variable doesn’t exist.

Return type:

Variable | None

Examples

>>> from openfisca_core import (
...     entities,
...     periods,
...     taxbenefitsystems,
...     variables,
... )

>>> this = entities.SingleEntity("this", "", "", "")
>>> that = entities.SingleEntity("that", "", "", "")

>>> this.get_variable("tax")
Traceback (most recent call last):
ValueError: You must set 'tax_benefit_system' before calling thi...

>>> tax_benefit_system = taxbenefitsystems.TaxBenefitSystem([this])
>>> this.set_tax_benefit_system(tax_benefit_system)

>>> this.get_variable("tax")

>>> this.get_variable("tax", check_existence=True)
Traceback (most recent call last):
VariableNotFoundError: You tried to calculate or to set a value...

>>> class tax(variables.Variable):
...     definition_period = periods.MONTH
...     value_type = float
...     entity = that

>>> this._tax_benefit_system.add_variable(tax)
<openfisca_core.entities._core_entity.tax object at ...>

>>> this.get_variable("tax")
<openfisca_core.entities._core_entity.tax object at ...>

is_person: ClassVar[bool] = True

Whether the Entity is a person or not.

key: NewType(EntityKey, str)

A key to identify the Entity.

label: str

A summary description.

plural: NewType(EntityPlural, str)

The key pluralised.

set_tax_benefit_system(tax_benefit_system)

A CoreEntity belongs to a TaxBenefitSystem.

Return type:

None

class openfisca_core.entities.GroupEntity(key, plural, label, doc, roles, containing_entities=())

Represents an entity containing several others with different roles.

A GroupEntity represents an Entity containing several other entities, with different roles, and on which calculations can be run.

Parameters:

• key (str) – A key to identify the GroupEntity.

• plural (str) – The key pluralised.

• label (str) – A summary description.

• doc (str) – A full description.

• roles (Sequence[RoleParams]) – The list of roles of the group entity.

• containing_entities (Iterable[str]) – The list of keys of group entities whose members are guaranteed to be a superset of this group’s entities.

Examples

>>> from openfisca_core import entities

>>> family_roles = [
...     {
...         "key": "parent",
...         "subroles": ["first_parent", "second_parent"],
...     }
... ]

>>> family = entities.GroupEntity(
...     "family",
...     "families",
...     "A family",
...     "\t\t\tAll the people somehow related living together.",
...     family_roles,
... )

>>> household_roles = [
...     {
...         "key": "partners",
...         "subroles": ["first_partner", "second_partner"],
...     }
... ]

>>> household = entities.GroupEntity(
...     "household",
...     "households",
...     "A household",
...     "\t\t\tAll the people who live together in the same place.",
...     household_roles,
...     (family.key,),
... )

>>> repr(entities.GroupEntity)
"<class 'openfisca_core.entities.group_entity.GroupEntity'>"

>>> repr(household)
'GroupEntity(household)'

>>> str(household)
'GroupEntity(household)'

static check_role_validity(role)

Check if role is an instance of Role.

Parameters:

role (object) – Any object.

Raises:

ValueError – When role is not a Role.

Return type:

None

Examples

>>> from openfisca_core import entities

>>> role = entities.Role({"key": "key"}, object())
>>> entities.check_role_validity(role)

>>> entities.check_role_validity("hey!")
Traceback (most recent call last):
ValueError: hey! is not a valid role

check_variable_defined_for_entity(variable_name)

Check if variable_name is defined for self.

Parameters:

variable_name (NewType(VariableName, str)) – The Variable to be found.

Raises:

ValueError – When the Variable exists but is defined for another Entity.

Return type:

None

Examples

>>> from openfisca_core import (
...     entities,
...     periods,
...     taxbenefitsystems,
...     variables,
... )

>>> this = entities.SingleEntity("this", "", "", "")
>>> that = entities.SingleEntity("that", "", "", "")
>>> tax_benefit_system = taxbenefitsystems.TaxBenefitSystem([that])
>>> this.set_tax_benefit_system(tax_benefit_system)

>>> this.check_variable_defined_for_entity("tax")
Traceback (most recent call last):
VariableNotFoundError: You tried to calculate or to set a value...

>>> class tax(variables.Variable):
...     definition_period = periods.WEEK
...     value_type = int
...     entity = that

>>> this._tax_benefit_system.add_variable(tax)
<openfisca_core.entities._core_entity.tax object at ...>

>>> this.check_variable_defined_for_entity("tax")
Traceback (most recent call last):
ValueError: You tried to compute the variable 'tax' for the enti...

>>> tax.entity = this

>>> this._tax_benefit_system.update_variable(tax)
<openfisca_core.entities._core_entity.tax object at ...>

>>> this.check_variable_defined_for_entity("tax")

doc: str

A full description.

get_variable(variable_name, check_existence=False)

Get variable_name from variables.

Parameters:

• variable_name (NewType(VariableName, str)) – The Variable to be found.

• check_existence (bool) – Was the Variable found?

Returns:

• Variable – When the Variable exists.

• None – When the Variable doesn’t exist.

Raises:

• ValueError – When the _tax_benefit_system is not set yet.

• ValueError – When check_existence is True and the Variable doesn’t exist.

Return type:

Variable | None

Examples

>>> from openfisca_core import (
...     entities,
...     periods,
...     taxbenefitsystems,
...     variables,
... )

>>> this = entities.SingleEntity("this", "", "", "")
>>> that = entities.SingleEntity("that", "", "", "")

>>> this.get_variable("tax")
Traceback (most recent call last):
ValueError: You must set 'tax_benefit_system' before calling thi...

>>> tax_benefit_system = taxbenefitsystems.TaxBenefitSystem([this])
>>> this.set_tax_benefit_system(tax_benefit_system)

>>> this.get_variable("tax")

>>> this.get_variable("tax", check_existence=True)
Traceback (most recent call last):
VariableNotFoundError: You tried to calculate or to set a value...

>>> class tax(variables.Variable):
...     definition_period = periods.MONTH
...     value_type = float
...     entity = that

>>> this._tax_benefit_system.add_variable(tax)
<openfisca_core.entities._core_entity.tax object at ...>

>>> this.get_variable("tax")
<openfisca_core.entities._core_entity.tax object at ...>

is_person: ClassVar[bool] = False

Whether the entity is a person or not.

key: NewType(EntityKey, str)

A key to identify the Entity.

label: str

A summary description.

plural: NewType(EntityPlural, str)

The key pluralised.

roles: Iterable[Role]

The list of roles of the GroupEntity.

set_tax_benefit_system(tax_benefit_system)

A CoreEntity belongs to a TaxBenefitSystem.

Return type:

None

class openfisca_core.entities.Role(description, entity)

The role of an Entity within a GroupEntity.

Each Entity related to a GroupEntity has a Role. For example, if you have a family, its roles could include a parent, a child, and so on. Or if you have a tax household, its roles could include the taxpayer, a spouse, several dependents, and the like.

Parameters:

• description (RoleParams) – A description of the Role.

• entity (GroupEntity) – The Entity to which the Role belongs.

Examples

>>> from openfisca_core import entities

>>> entity = entities.GroupEntity("key", "plural", "label", "doc", [])
>>> role = entities.Role({"key": "parent"}, entity)

>>> repr(entities.Role)
"<class 'openfisca_core.entities.role.Role'>"

>>> repr(role)
'Role(parent)'

>>> str(role)
'Role(parent)'

>>> {role}
{Role(parent)}

>>> role.key
'parent'

description: _Description

A description of the Role.

property doc: None | str

A full description, non-indented.

entity: GroupEntity

The GroupEntity the Role belongs to.

property key: RoleKey

A key to identify the Role.

property label: None | str

A summary description.

max: None | int = None

Max number of members.

property plural: None | RolePlural

The key pluralised.

subroles: None | Iterable[Role] = None

A list of subroles.

openfisca_core.entities.SingleEntity

alias of Entity

openfisca_core.entities.build_entity(key, plural, label, doc='', roles=None, is_person=False, *, class_override=None, containing_entities=())

Build an Entity or a GroupEntity.

Parameters:

• key (str) – Key to identify the Entity or GroupEntity.

• plural (str) – The key pluralised.

• label (str) – A summary description.

• doc (str) – A full description.

• roles (None | Sequence[RoleParams]) – A list of roles —if it’s a GroupEntity.

• is_person (bool) – If is an individual, or not.

• class_override (object) –

  ?

• containing_entities (Sequence[str]) – Keys of contained entities.

Returns:

• Entity – When is_person is True.

• GroupEntity – When is_person is False.

Raises:

NotImplementedError – If roles is None.

Return type:

SingleEntity | GroupEntity

Examples

>>> from openfisca_core import entities

>>> entity = entities.build_entity(
...     "syndicate",
...     "syndicates",
...     "Banks loaning jointly.",
...     roles=[],
...     containing_entities=(),
... )
>>> entity
GroupEntity(syndicate)

>>> entities.build_entity(
...     "company",
...     "companies",
...     "A small or medium company.",
...     is_person=True,
... )
Entity(company)

>>> role = entities.Role({"key": "key"}, entity)

>>> entities.build_entity(
...     "syndicate",
...     "syndicates",
...     "Banks loaning jointly.",
...     roles=[role],
... )
Traceback (most recent call last):
TypeError: 'Role' object is not subscriptable

openfisca_core.entities.check_role_validity(role)

Check if role is an instance of Role.

Parameters:

role (object) – Any object.

Raises:

ValueError – When role is not a Role.

Return type:

None

Examples

>>> from openfisca_core import entities

>>> role = entities.Role({"key": "key"}, object())
>>> entities.check_role_validity(role)

>>> entities.check_role_validity("hey!")
Traceback (most recent call last):
ValueError: hey! is not a valid role

openfisca_core.entities.find_role(roles, key, *, total=None)

Find a Role in a GroupEntity.

Parameters:

• roles (Iterable[Role]) – The roles to search.

• key (NewType(RoleKey, str)) – The key of the role to find.

• total (None | int) – The max attribute of the role to find.

Returns:

• Role – The role if found

• None – Else None.

Return type:

None | Role

Examples

>>> from openfisca_core import entities
>>> from openfisca_core.entities import types as t

>>> principal = t.RoleParams(
...     key="principal",
...     label="Principal",
...     doc="Person focus of a calculation in a family context.",
...     max=1,
... )

>>> partner = t.RoleParams(
...     key="partner",
...     plural="partners",
...     label="Partners",
...     doc="Persons partners of the principal.",
... )

>>> parent = t.RoleParams(
...     key="parent",
...     plural="parents",
...     label="Parents",
...     doc="Persons parents of children of the principal",
...     subroles=["first_parent", "second_parent"],
... )

>>> group_entity = entities.build_entity(
...     key="family",
...     plural="families",
...     label="Family",
...     doc="A Family represents a collection of related persons.",
...     roles=[principal, partner, parent],
... )

>>> entities.find_role(group_entity.roles, "principal", total=1)
Role(principal)

>>> entities.find_role(group_entity.roles, "partner")
Role(partner)

>>> entities.find_role(group_entity.roles, "parent", total=2)
Role(parent)

>>> entities.find_role(group_entity.roles, "first_parent", total=1)
Role(first_parent)